Amazon S3 Output Plugin
The out_s3
Output plugin writes records into the Amazon S3 cloud object storage service. By default, it creates files on an hourly basis. This means that when you first import records using the plugin, no file is created immediately.
The file will be created when the timekey
condition has been met. To change the output frequency, please modify the timekey
value in buffer section. In more detail, please refer to the time chunk keys in bufferdocument.
This document doesn't describe all parameters. If you want to know full features, check the Further Reading section. |
Table of Contents
Installation
out_s3
is included in td-agent by default. Fluentd gem users will need to install the fluent-plugin-s3 gem. In order to install it, please refer to the Plugin Management article.
Example Configuration
<match pattern> @type s3 aws_key_id YOUR_AWS_KEY_ID aws_sec_key YOUR_AWS_SECRET_KEY s3_bucket YOUR_S3_BUCKET_NAME s3_region ap-northeast-1 path logs/ # if you want to use ${tag} or %Y/%m/%d/ like syntax in path / s3_object_key_format, # need to specify tag for ${tag} and time for %Y/%m/%d in <buffer> argument. <buffer tag,time> @type file path /var/log/fluent/s3 timekey 3600 # 1 hour partition timekey_wait 10m timekey_use_utc true # use utc chunk_limit_size 256m </buffer> </match>
Please see the Store Apache Logs into Amazon S3 article for real-world use cases.
Please see the Config File article for the basic structure and syntax of the configuration file. |
For <buffer> section, please check Buffer section cofiguration. This plugin uses file buffer by default. |
Parameters
@type (required)
The value must be s3
.
aws_key_id
type | default | version |
---|---|---|
string | required/optional | 1.0.0 |
The AWS access key id. This parameter is required when your agent is not running on an EC2 instance with an IAM Instance Profile.
aws_sec_key
type | default | version |
---|---|---|
string | required/optional | 1.0.0 |
The AWS secret key. This parameter is required when your agent is not running on an EC2 instance with an IAM Instance Profile.
s3_bucket
type | default | version |
---|---|---|
string | required | 1.0.0 |
The Amazon S3 bucket name.
buffer
The buffer of the S3 plugin. The default settings is time sliced buffer.
See buffer article for more detail.
s3_region
type | default | version |
---|---|---|
string | ENV[“AWS_REGION”] or “us-east-1” | 1.0.0 |
The Amazon S3 region name. Please select the appropriate region name and confirm that your bucket has been created in the correct region. Here are the region examples.
- us-east-1
- us-west-1
- eu-central-1
- ap-southeast-1
- sa-east-1
The full list can be found official AWS document.
s3_endpoint
type | default | version |
---|---|---|
string | nil | 1.0.0 |
This option is deprecated because latest aws-sdk ignores this option. Please use s3_region
instead.
The Amazon S3 enpoint name. Please select the appropriate endpoint name from the list below and confirm that your bucket has been created in the correct region.
- s3.amazonaws.com
- s3-us-west-1.amazonaws.com
- s3-us-west-2.amazonaws.com
- s3.sa-east-1.amazonaws.com
- s3-eu-west-1.amazonaws.com
- s3-ap-southeast-1.amazonaws.com
- s3-ap-northeast-1.amazonaws.com
The most recent versions of the endpoints can be found here.
<format> directive
The format of the object content. The default is out_file
.
Here is json example:
<format> @type json </format>
See formatter article for more detail.
format
Deprecated parameter. Use <format>
instead.
time_slice_format
type | default | version |
---|---|---|
string | ISO-8601 | 1.0.0 |
The format of the time written in files.
path
type | default | version |
---|---|---|
string | “” | 1.0.0 |
The path prefix of the files on S3. The default is “” (no prefix).
The actual path on S3 will be: “{path}{time_slice_format}_{sequential_index}.gz” (see `s3_object_key_format`) |
s3_object_key_format
type | default | version |
---|---|---|
string | “%{path}%{time_slice}_%{index}.%{file_extension}” | 1.0.0 |
The actual S3 path. This is interpolated to the actual path (ex: Ruby’s variable interpolation).
- path: the value of the
path
parameter above - time_slice: the time string as formatted by
time_slice_format
- index: the index for the given path. Incremented per buffer flush
- file_extension: as determined by the
store_as
parameter.
For example, if
-
s3_object_key_format
is as default -
path
is “hello” -
time_slice_format
is “%Y%m%d” -
store_as
is “json”
Then, “hello20141111_0.json” would be an example actual S3 path.
This parameter is for advanced users. Most users should NOT modify it. Also, always make sure that %{index} appears in the customized `s3_object_key_format` (Otherwise, multiple buffer flushes within the same time slice throws an error). |
store_as
type | default | version |
---|---|---|
string | “gzip” | 1.0.0 |
The compression type. You can also choose “lzo”, “json”, or “txt”.
proxy_uri
type | default | version |
---|---|---|
string | nil | 1.0.0 |
The proxy url. The default is nil.
ssl_verify_peer
type | default | version |
---|---|---|
bool | true | 1.0.0 |
Verify SSL certificate of the endpoint. Set false when you want to ignore the endpoint SSL certificate.
@log_level option
The @log_level
option allows the user to set different levels of logging for each plugin. The supported log levels are: fatal
, error
, warn
, info
, debug
, and trace
.
Please see the logging article for further details.
Further Reading
This page doesn’t describe all the possible configurations. If you want to know about other configurations, please check the link below.
If this article is incorrect or outdated, or omits critical information, please let us know. Fluentd is a open source project under Cloud Native Computing Foundation (CNCF). All components are available under the Apache 2 License.