# 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](https://docs.fluentd.org/configuration/buffer-section#time).
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](https://docs.fluentd.org/deployment/plugin-management) article.
## Example Configuration
```
@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 argument.
@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
```
Please see the [Store Apache Logs into Amazon S3](https://docs.fluentd.org/how-to-guides/apache-to-s3) article for real-world use cases.
Please see the [Config File](https://docs.fluentd.org/configuration/config-file) article for the basic structure and syntax of the configuration file.
For `` section, see [Buffer Section Configuration](https://docs.fluentd.org/configuration/buffer-section). By default, this plugin uses the [`file`](https://docs.fluentd.org/buffer/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](https://github.com/fluent/fluent-plugin-s3#configuration-credentials).
### `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`](https://docs.fluentd.org/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](http://docs.aws.amazon.com/general/latest/gr/rande.html#s3_region).
### `` Directive
The format of the object content. The default is `out_file`.
JSON example:
```
@type json
```
See [`formatter`](https://docs.fluentd.org/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](https://docs.fluentd.org/deployment/logging) article for further details.
## Further Reading
This page does not describe all the possible configurations. For more details, follow this:
* [`fluent-plugin-s3`](https://github.com/fluent/fluent-plugin-s3)
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-source project under [Cloud Native Computing Foundation (CNCF)](https://cncf.io/). All components are available under the Apache 2 License.