# http

The `out_http` Output plugin writes records via HTTP/HTTPS.

This plugin is introduced since fluentd v1.7.0.

It is included in Fluentd's core.

## Example Configuration

```
<match pattern>
  @type http

  endpoint http://logserver.com:9000/api
  open_timeout 2

  <format>
    @type json
  </format>
  <buffer>
    flush_interval 10s
  </buffer>
</match>
```

Please see the [Configuration File](https://docs.fluentd.org/configuration/config-file) article for the basic structure and syntax of the configuration file.

For `<buffer>`, refer to [Buffer Section Configuration](https://docs.fluentd.org/configuration/buffer-section).

## Parameters

### `@type`

The value must be `http`.

### `endpoint`

| type   | default  | version |
| ------ | -------- | ------- |
| string | required | 1.7.0   |

The endpoint for HTTP request. If you want to use HTTPS, use `https` prefix.

```
# Use HTTP
endpoint http://example.com/api

# Use HTTPS. You can set additional HTTPS parameters like tls_xxx
endpoint https://example.com/api
```

The `endpoint` parameter supports placeholders, so you can embed time, tag and record fields in the endpoint. Placeholders also require the buffer section in order to work. Here is an example:

```
endpoint http://example.com/api/${tag}-${key}
<buffer tag,key>
  # buffer parameters
</buffer>
```

See [Buffer Section Configurations](https://docs.fluentd.org/configuration/buffer-section) for more details.

### `http_method`

| type | default | available values | version |
| ---- | ------- | ---------------- | ------- |
| enum | post    | post/put         | 1.7.0   |

The method for HTTP request.

### `proxy`

| type   | default  | version |
| ------ | -------- | ------- |
| string | optional | 1.7.0   |

The proxy for HTTP request.

### `content_type`

| type   | default | version |
| ------ | ------- | ------- |
| string | nil     | 1.7.0   |

`Content-Type` for HTTP request. `out_http` automatically set `Content-Type` for built-in formatters when this parameter is not specified.

Here is a table:

* `json` with `json_array false`: `application/x-ndjson`
* `json` with `json_array true`: `application/json`
* `csv`: `text/csv`
* `tsv`, `ltsv`: `text/tab-separated-values`
* `msgpack`: `application/x-msgpack`
* `out_file`, `single_value`, `stdout`, `hash`: `text/plain`

### `json_array`

| type | default | version |
| ---- | ------- | ------- |
| bool | false   | 1.10.4  |

Using the array format of JSON. This parameter is used and valid only for json format. When `json_array` as true, Content-Type should be `application/json` and be able to use JSON data for the HTTP request body.

* `json_array true`

```
[
  {"key":"value", ...},
  {"key":"value", ...},
  ...
]
```

* `json_array false`

```
{"key":"value", ...}
{"key":"value", ...}
...
```

### `compress`

| type | default | available values | version |
| ---- | ------- | ---------------- | ------- |
| enum | text    | text/gzip        | 1.17.1  |

The option to compress HTTP request body.

### `<format>` Directive

The format of the payload. The default `@type` is `json`.

Here is `single_value` example:

```
<format>
  @type single_value
</format>
```

See [`formatter`](https://docs.fluentd.org/formatter) article for more detail.

### `headers`

| type | default | version |
| ---- | ------- | ------- |
| hash | nil     | 1.7.0   |

Additional headers for HTTP request.

```
headers {"key1":"value1", "key2":"value2"}
```

### headers\_from\_placeholders

| type | default | version |
| ---- | ------- | ------- |
| hash | nil     | 1.12.1  |

Additional placeholder based headers for HTTP request. If you want to use tag or record field, use this parameter instead of `headers`.

```
headers_from_placeholders {"x-foo-bar":"${$.foo.bar}","x-tag":"app-${tag}"}
<buffer tag,$.foo.bar>
  # buffer parameters...
</buffer>
```

### `open_timeout`

| type    | default | version |
| ------- | ------- | ------- |
| integer | nil     | 1.7.0   |

The connection open timeout in seconds.

See also [Ruby document](https://docs.ruby-lang.org/en/master/Net/HTTP.html#attribute-i-open_timeout).

### `read_timeout`

| type    | default | version |
| ------- | ------- | ------- |
| integer | nil     | 1.7.0   |

The read timeout in seconds.

See also [Ruby document](https://docs.ruby-lang.org/en/master/Net/HTTP.html#attribute-i-read_timeout).

### `ssl_timeout`

| type    | default | version |
| ------- | ------- | ------- |
| integer | nil     | 1.7.0   |

The TLS timeout in seconds.

### `reuse_connections`

| type | default | version |
| ---- | ------- | ------- |
| bool | false   | 1.17.0  |

Try to reuse connections. This will improve performance.

### `tls_ca_cert_path`

| type   | default | version |
| ------ | ------- | ------- |
| string | nil     | 1.7.0   |

The CA certificate path for TLS.

### `tls_client_cert_path`

| type   | default | version |
| ------ | ------- | ------- |
| string | nil     | 1.7.0   |

The client certificate path for TLS.

### `tls_private_key_path`

| type   | default | version |
| ------ | ------- | ------- |
| string | nil     | 1.7.0   |

The client private key path for TLS.

### `tls_private_key_passphrase`

| type   | default | version |
| ------ | ------- | ------- |
| string | nil     | 1.7.0   |

The client private key passphrase for TLS.

### `tls_verify_mode`

| type | default | available values | version |
| ---- | ------- | ---------------- | ------- |
| enum | peer    | peer/none        | 1.7.0   |

The verify mode of TLS.

### `tls_version`

| type | default  | available values                         | version |
| ---- | -------- | ---------------------------------------- | ------- |
| enum | TLSv1\_2 | TLSv1\_3(since 1.19.0)/TLSv1\_2/TLSv1\_1 | 1.7.0   |

The default version of TLS.

### `tls_ciphers`

| type   | default                  | version |
| ------ | ------------------------ | ------- |
| string | ALL:!aNULL:!eNULL:!SSLv2 | 1.7.0   |

The cipher suites configuration of TLS.

### `error_response_as_unrecoverable`

| type | default | version |
| ---- | ------- | ------- |
| bool | true    | 1.7.0   |

Raise `UnrecoverableError` when the response code is not SUCCESS, 1xx/3xx/4xx/5xx. If `false`, `out_http` logs error message instead of raising `UnrecoverableError`.

See also [Handling Unrecoverable Errors](https://docs.fluentd.org/buffer#handling-unrecoverable-errors).

### `retryable_response_codes`

| type         | default | version |
| ------------ | ------- | ------- |
| array of int | \[503]  | 1.7.0   |

The list of retryable response codes. If the response code is included in this list, `out_http` retries the buffer flush.

### `<auth>` Section

Specifies HTTP authentication.

#### `method`

| type | default | available values | version                         |
| ---- | ------- | ---------------- | ------------------------------- |
| enum | basic   | basic/aws\_sigv4 | basic:1.7.0 / aws\_sigv4:1.17.0 |

The method for HTTP authentication.

* `basic`: basic authentication
* `aws_sigv4`: [AWS Signature Version 4](https://docs.aws.amazon.com/AmazonS3/latest/API/sig-v4-authenticating-requests.html)

#### Parameters for `method basic`

```
<auth>
  method basic
  username fluentd
  password hello
</auth>
```

**`username`**

| type   | default | version |
| ------ | ------- | ------- |
| string | nil     | 1.7.0   |

The username for basic authentication.

**`password`**

| type   | default | version |
| ------ | ------- | ------- |
| string | nil     | 1.7.0   |

The password for basic authentication.

#### Parameters for `method aws_sigv4`

Parameters for [AWS Signature Version 4](https://docs.aws.amazon.com/AmazonS3/latest/API/sig-v4-authenticating-requests.html).

```
<auth>
  method aws_sigv4
  aws_service osis
  aws_region us-east-1
  aws_role_arn arn:aws:iam::123456789012:role/MyRole
</auth>
```

**`aws_service`**

| type   | default | version |
| ------ | ------- | ------- |
| string | nil     | 1.17.0  |

The AWS service to authenticate against.

This parameter is required when you specify `aws_sigv4` for `method`.

**`aws_region`**

| type   | default | version |
| ------ | ------- | ------- |
| string | nil     | 1.17.0  |

The AWS region to use when authenticating.

This parameter is required when you specify `aws_sigv4` for `method`.

**`aws_role_arn`**

| type   | default | version |
| ------ | ------- | ------- |
| string | nil     | 1.17.0  |

The AWS role ARN to assume when authenticating.

This parameter is optional when you specify `aws_sigv4` for `method`. If you provide it, Fluentd will assume that AWS role and send requests signing from that role. Otherwise, Fluentd will use the credentials found by the [credential provider chain](https://docs.aws.amazon.com/sdk-for-ruby/v3/developer-guide/setup-config.html) as defined in the AWS documentation.

## Common Output / Buffer parameters

For common output / buffer parameters, please check the following articles:

* [Output Plugin Overview](https://docs.fluentd.org/output)
* [Buffer Section Configuration](https://docs.fluentd.org/configuration/buffer-section)

## The Payload Content

`out_http`'s request body depends on `<format>` configuration. For example, the default setting generates newline delimited JSON like this:

```
# \n is added by `add_newline true` parameter in <format>
{"key1":"value1","key2":"value2",...}\n
{"key1":"value1","key2":"value2",...}\n
{"key1":"value1","key2":"value2",...}\n
{"key1":"value1","key2":"value2",...}\n
...
```

With `@type single_value`:

```
log line1\n
log line2\n
log line3\n
log line4\n
...
```

## Troubleshooting

### 400 Bad request between `out_http` and `in_http`

When getting the following error:

```
#0 got unrecoverable error in primary and no secondary error_class=Fluent::UnrecoverableError error="400 Bad Request 400 Bad Request\n'json' or 'msgpack' parameter is required\n"
#0 bad chunk is moved to /tmp/fluent/backup/worker0/object_3ff8a73edae8/5a71a08ca19b1b343c8dce1b74c9a963.log
```

Users should specify `json` format with `json_array` as true for `out_http` configuration:

```
<match **>
  @type http
  endpoint http://some.your.http.endpoint:9811/your-awesome-path
  <format>
    @type json
  </format>
  json_array true
  <buffer>
    flush_interval 2s
  </buffer>
</match>
```

And receiver `in_http` configuration should be:

```
<source>
  @type http
  port 9811
  bind 0.0.0.0
  <parse>
    @type json
  </parse>
</source>
```

Or specify `msgpack` format:

```
<match **>
  @type http
  endpoint http://some.your.http.endpoint:9882/your-awesome-path
  <format>
    @type msgpack
  </format>
  <buffer>
    flush_interval 2s
  </buffer>
</match>
```

And, receiver `in_http` configuration should be:

```
<source>
  @type http
  port 9882
  bind 0.0.0.0
  <parse>
    @type msgpack
  </parse>
  <format>
    @type json
  </format>
</source>
```

But, we recommend to use in/out [`forward`](https://docs.fluentd.org/output/forward) plugin to communicate with two Fluentd instances due to `at-most-once` and `at-least-once` semantics for rigidity.

If this article is incorrect or outdated, or omits critical information, please [let us know](https://github.com/fluent/fluentd-docs-gitbook/issues?state=open). [Fluentd](http://www.fluentd.org/) is an open article- source project under [Cloud Native Computing Foundation (CNCF)](https://cncf.io/). All components are available under the Apache 2 License.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.fluentd.org/output/http.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.