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.

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.

Parameters

@type (required)

The value must be s3.

aws_key_id

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

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

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

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

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

The format of the time written in files.

path

The path prefix of the files on S3. The default is “” (no prefix).

s3_object_key_format

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.

store_as

The compression type. You can also choose “lzo”, “json”, or “txt”.

proxy_uri

The proxy url. The default is nil.

ssl_verify_peer

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.

• fluent-plugin-s3 repository

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.