s3

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 the buffer section. For more details, see time chunk keys.

This document doesn't describe all parameters. If you want to know full features, check the Further Reading section.

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, see Buffer Section Configuration. By default, this plugin uses the file buffer.

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.

Credentials on AWS environment

S3 plugin supports several credentials.

See README.

s3_bucket

type	default	version
string	required	1.0.0

The Amazon S3 bucket name.

buffer

The buffer of the S3 plugin. The default is the time-sliced buffer.

For more details, see buffer.

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 some regions:

• us-east-1

• us-west-1

• eu-central-1

• ap-southeast-1

• sa-east-1

See the complete list of regions here.

<format> Directive

The format of the object content. The default is out_file.

JSON example:

<format>
  @type json
</format>

See formatter article for more detail.

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) by default.

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 (e.g. Ruby's variable interpolation):

• path: the value of the path parameter above

• time_slice: the time string as formatted by buffer configuration

• 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: default

• path: hello

• time_slice: %Y%m%d

• store_as: json

Then, hello20141111_0.json would be the example of an 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.

Supported types: lzo, json, txt

proxy_uri

type	default	version
string	nil	1.0.0

The proxy URL.

ssl_verify_peer

type	default	version
bool	true	1.0.0

Verify the SSL certificate of the endpoint. If false, the endpoint SSL certificate is ignored.

@log_level

It allows the user to set different levels of logging for each plugin.

Supported levels: fatal, error, warn, info, debug, trace

Please see the logging article for further details.

Further Reading

This page does not describe all the possible configurations. For more details, follow this:

• fluent-plugin-s3

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.