The in_http
Input plugin allows you to send events through HTTP requests. Using this plugin, you can trivially launch a REST endpoint to gather data.
Here is a sample configuration:
<source>
@type http
port 9880
bind 0.0.0.0
body_size_limit 32m
keepalive_timeout 10s
</source>
For the full list of the configurable options, see the Parameters section.
By default, the data format depends on the Content-Type
.
In summary, you can send the following format.
json
ndjson
msgpack
Here is a simple example to post a record using curl
, which uses the default Content-Type application/x-www-form-urlencoded
.
Example: post JSON data with the tag "app.log":
curl -X POST -d 'json={"foo":"bar"}' http://localhost:9880/app.log
Example: post NDJSON data with the tag "app.log":
ndjson=`echo -e 'ndjson={"k1":"v1"}\n{"k2":"v2"}\n'`
curl -X POST -d "$ndjson" http://localhost:9880/app.log
Example: post MessagePack data with the tag "app.log":
msgpack=`echo -e "msgpack=\x81\xa3foo\xa3bar"`
curl -X POST -d "$msgpack" http://localhost:9880/app.log
Some Media Types other than application/x-www-form-urlencoded
support specific formats.
If those Media Types are specified with Content-Type:
, the prefix such as json=
is not necessary for posting data.
Example: Post JSON data with Content-Type: application/json
:
curl -X POST -d '{"foo":"bar"}' -H 'Content-Type: application/json' \
http://localhost:9880/app.log
For more details regarding the message body syntax and Content-Type
see How to use HTTP Content-Type Header
By default, timestamps are assigned to each record on arrival. You can override the timestamp using the time
parameter:
# Overwrite the timestamp to 2018-02-16 04:40:37.3137116
$ curl -X POST -d 'json={"foo":"bar"}' \
http://localhost:9880/test.tag?time=1518756037.3137116
Here is another example in JavaScript:
// Post a record using XMLHttpRequest
var form = new FormData();
form.set('json', JSON.stringify({"foo": "bar"}));
var req = new XMLHttpRequest();
req.open('POST', 'http://localhost:9880/debug.log');
req.send(form);
For more advanced usage, please read the Tips and Tricks section.
See Common Parameters.
The value must be http
.
type | default | version |
---|---|---|
integer | 9880 | 0.14.0 |
The port to listen to.
type | default | version |
---|---|---|
string | 0.0.0.0 (all addresses) | 0.14.0 |
The bind address to listen to.
type | default | version |
---|---|---|
size | 32MB | 0.14.0 |
The size limit of the POSTed element.
type | default | version |
---|---|---|
size | 10 (seconds) | 0.14.0 |
The timeout limit for keeping the connection alive.
type | default | version |
---|---|---|
bool | false | 0.14.0 |
Adds HTTP_
prefix headers to the record.
type | default | version |
---|---|---|
bool | false | 0.14.0 |
Adds REMOTE_ADDR
field to the record. The value of REMOTE_ADDR
is the client's address.
If your system set multiple X-Forwarded-For
headers in the request, in_http
uses the first one. For example:
X-Forwarded-For: host1, host2
X-Forwarded-For: host3
If the above multiple headers are sent, the value of REMOTE_ADDR
will be host1
.
type | default | version |
---|---|---|
array | nil(disabled) | 0.14.0 |
Whitelist domains for CORS.
If you set ["domain1", "domain2"]
to cors_allow_origins
, in_http
returns 403
to access from other domains. Since Fluentd v1.2.6, you can use a wildcard character *
to allow requests from any origins.
Example:
<source>
@type http
port 9880
cors_allow_origins ["*"]
</source>
type | default | version |
---|---|---|
bool | false | 1.14.0 |
Add Access-Control-Allow-Credentials
header. It's needed when a request's credentials mode is include
. An example of use case is using Beacon API, its request mode is always include
.
type | default | version |
---|---|---|
bool | false | 0.12.0 |
Responds with an empty GIF image of 1x1 pixel (rather than an empty string).
type | default | version |
---|---|---|
bool | false | v1.8.0 |
Respond status code with 204. This option will be deprecated at v2 because fluentd v2 will respond 204 as default.
type | default | available values | version |
---|---|---|---|
enum | tcp | tcp, tls | 1.5.0 |
This section is for setting TLS transport or some general transport configurations.
type | default | available transport type | version |
---|---|---|---|
integer | 0 | tcp, tls | 1.14.6 |
The timeout (seconds) to set SO_LINGER
.
The default value 0
is to send RST rather than FIN to avoid lots of connections sitting in TIME_WAIT on closing on non-Windows.
You can set positive value to send FIN on closing on non-Windows.
{% hint style='info' %} On Windows, Fluentd sends FIN without depending on this setting. {% endhint %}
<transport tcp>
linger_timeout 1
</transport>
<transport tls>
cert_path /path/to/fluentd.crt
# other parameters
</transport>
See How to Enable TLS Encryption section for how to use and see Configuration Example for all supported parameters.
Without <transport tls>
, in_http
uses HTTP.
Use the parser plugin to parse the incoming data. See also Handle other formats using parser plugins section.
Deprecated parameter. Use <parse>
directive instead.
You can post data in MessagePack format by adding the msgpack=
prefix:
# Send data in msgpack format
$ msgpack=`echo -e "\x81\xa3foo\xa3bar"`
$ curl -X POST -d "msgpack=$msgpack" http://localhost:9880/app.log
in_http
plugin recognizes HTTP Content-Type
header in the incoming requests.
If you use the default <parse>
setting, the data format depends on the Content-Type
.
(If you set the <parse>
directive to use a specific Parser, the Content-Type
is not used).
By default curl
uses -H "Content-Type: application/x-www-form-urlencoded"
, which allows the use of the prefix json=
, ndjson=
, and msgpack=
as seen on the previous examples.
On the other hand, some Media Types other than application/x-www-form-urlencoded
support specific formats.
If those Media Types are specified with Content-Type:
, the prefix such as json=
is not necessary for posting data.
Here is the list of supported Media Types:
Media Types | data format | version |
---|---|---|
application/json |
JSON | - |
application/csp-report |
JSON | 1.17.0 |
application/msgpack |
MessagePack | - |
application/x-ndjson |
NDJSON | 1.14.5 |
Examples:
curl -X POST -d '{"foo":"bar"}' -H 'Content-Type: application/json' \
http://localhost:9880/app.log
msgpack=`echo -e "\x81\xa3foo\xa3bar"`
curl -X POST -d "$msgpack" -H 'Content-Type: application/msgpack' \
http://localhost:9880/app.log
Also, you can use multipart/form-data
.
For more details about multipart/form-data
, please see Why in_http
removes '+' from my log.
You can handle various input formats by using the <parse>
directive. For example, add the following settings to the configuration file:
<source>
@type http
port 9880
<parse>
@type regexp
expression /^(?<field1>\d+):(?<field2>\w+)$/
</parse>
</source>
Now you can post custom-format records like this:
# This will be parsed into {"field1":"123456","field2":"awesome"}
$ curl -X POST -d '123456:awesome' http://localhost:9880/app.log
Many other formats (e.g. csv
/syslog
/nginx
) are also supported. For the full list of supported formats, see Parser Plugin Overview.
NOTE: Some parser plugins do not support the batch mode. So, if you want to use bulk insertion for handling a large data set, please consider keeping the default JSON (or MessagePack) format or write batch mode supported parser (return array object).
You can post multiple records with a single request by packing data into a JSON/MessagePack array:
# Send multiple events as a JSON array
$ curl -X POST -d 'json=[{"foo":"bar"},{"abc":"def"},{"xyz":"123"}]' \
http://localhost:9880/app.log
This significantly improves the throughput since it reduces the number of HTTP requests. Here is a simple benchmark on MacBook Pro with Ruby 2.3:
json | msgpack | msgpack array(10 items) |
---|---|---|
2100 events/sec | 2400 events/sec | 10000 events/sec |
Tested configuration and Ruby script are here.
Since v1.2.3, Fluentd can handle gzip-compressed payloads. To enable this feature, you need to add the Content-Encoding
header to your requests.
# Send gzip-compressed payload
$ echo 'json={"foo":"bar"}' | gzip > json.gz
$ curl --data-binary @json.gz -H "Content-Encoding: gzip" \
http://localhost:9880/app.log
You do not need any configuration to enable this feature.
If you use this plugin under the multi-process environment, the port will be shared.
<system>
workers 3
</system>
<source>
@type http
port 9880
</source>
With this configuration, three (3) workers share 9880 port. No need for an additional port. Incoming data will be routed to three (3) workers automatically.
This happens when using the content type application/x-www-form-urlencoded
.
It is a limitation of the HTTP spec, you either need to encode the message or you can use the content type application/json
.
For example:
# bad
curl -X POST --location "http://localhost:9880/app.loge" \
-d "json=[{\"log\":\"message ; remaining message\"}]"
# good
curl -X POST --location "http://localhost:9880/app.log" \
-H "Content-Type: application/json" \
-d "{\"log\":\"message ; remaining message\"}"
This is HTTP spec, not fluentd problem. You need to encode your payload properly or use multipart request. Here is a Ruby example:
# Good
URI.encode_www_form({json: {"message" => "foo+bar"}.to_json})
# Bad
"json=#{"message" => "foo+bar"}.to_json}"
curl
command example:
# Good
curl -X POST -H 'Content-Type: multipart/form-data' -F 'json={"message":"foo+bar"}' http://localhost:9880/app.log
# Bad
curl -X POST -F 'json={"message":"foo+bar"}' http://localhost:9880/app.log
Since v1.5.0, in_http
support TLS transport. Here is a configuration example with HTTPS client:
<source>
@type http
bind 0.0.0.0
<transport tls>
ca_path /etc/pki/ca.pem
cert_path /etc/pki/cert.pem
private_key_path /etc/pki/key.pem
private_key_passphrase PASSPHRASE
</transport>
</source>
- https client
require 'net/http'
require 'net/https'
require 'msgpack'
record = { 'msgpack' => { 'k' => 'hello', 'k1' => 1234}.to_msgpack }
def post(path, params)
http = Net::HTTP.new('127.0.0.1', 9880)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE
req = Net::HTTP::Post.new(path, {})
req.set_form_data(params)
http.request(req)
end
puts post("/test.http?time=#{Time.now.to_i}", record).body
Fluentd supports TLS mutual authentication (i.e. client certificate auth). If you want to use this feature, please set the client_cert_auth
and ca_path
options like this:
<source>
@type http
<transport tls>
...
client_cert_auth true
ca_path /path/to/ca/cert
</transport>
</source>
When this feature is enabled, Fluentd will check all the incoming requests for a client certificate signed by the trusted CA. Requests with an invalid client certificate will fail.
If this article is incorrect or outdated, or omits critical information, please let us know. Fluentd is an open-source project under Cloud Native Computing Foundation (CNCF). All components are available under the Apache 2 License.