fluentdのoutput_s3プラグイン


output_s3プラグインは、fluentdでs3にアップロードするためのプラグインです。
プラグイン全般の基礎知識は[こちら](http://documents.mazgi.com/fluentd/doc/plugin.html)から。
td-agentを使用している場合はデフォルトで入っていますが、fluentのgemを使用している場合はfluent-gemからインストールします。

```
$ fluent-gem install fluent-plugin-s3
```

## パラメーター
### type (required)
output_s3プラグインを使用するのでs3とします。

### aws_key_id (required/optional)
AWSのアクセスキーid

### aws_sec_key (required/optional)
AWSのシークレットキー

### s3_bucket (required)
S3のバケット名

### buffer_path (required)
ログをバッファする際のファイルパス

### s3_region
S3のリージョン
Asia Pacific (Tokyo)はap-northeast-1
※ s3_endpointがdeprecatedになり、s3_regionを使用する事が推奨されています。

リージョン一覧はこちら
http://docs.aws.amazon.com/general/latest/gr/rande.html#s3_region

### format
S3オブジェクトの出力形式
デフォルトはout_fileで、他にjson, ltsv, single_valueがある

### time_slice_format
出力されるファイル名の一部になるもの
下記は出力時に実際の時刻に変換される

- %Y: 年(4桁の数字)
- %m: 月 (01..12)
- %d: 日付 (01..31)
- %H: 時間(00..23)
- %M: 分(00..59)
- %S: 秒(00..60)

デフォルトは`%Y%m%d%H`で、1時間毎にファイルが生成される

### time_slice_wait
バッファをフラッシュするまでの時間(分)で、デフォルトは10分
time_slice_formatでファイルが生成され、time_slice_waitの分数待った後にファイル出力されます。
待っている間はテンポラリなファイルとして`production.20140707.b4fd94dc2cd24b79d.log`のような形でファイルが存在し、`production.20140707_0.log.gz`としてファイルが保存されます。

### time_format
出力されるログの時間の形式。
デフォルトはISO-8601

### path
S3への出力先パス。
実際には下記のようなパスに出力されます。

`{path}{time_slice_format}_{sequential_number}.gz`

### utc
UTCを使用する。デフォルトはローカルタイム。

### store_as
圧縮形式。
デフォルトはgzipで、他にはizo, json, txtがある。

### proxy_uri
プロキシのURIで、デフォルトはnil

### use_ssl
FluentdとS3間でSSLを有効にするかどうか。
デフォルトはyes

## バッファパラメーター
### buffer_type
バッファタイプ。
デフォルトはmemoryで、fileタイプも選択可能。

### buffer_path
バッファタイプがファイルの際のパス。

### buffer_queue_limit
バッファキューのサイズで、デフォルトは64。
処理出来なかったログデータは、このbuffer_queue_limitとbuffer_chunk_limitによって決定されます。
k(KB), m(MB),g(GB)で指定します。

### buffer_chunk_limit
バッファチャンクのサイズで、デフォルトは8m。
k(KB), m(MB),g(GB)で指定します。

### flush_interval
データフラッシュの間隔で、デフォルトは60sです。
s(秒), m(分), h(時間)で指定します。

### retry_wait
書き込みのリトライ間隔

### retry_limit
書き込みのリトライ数

### max_retry_wait
書き込みのリトライ数の最大値

### num_threads
フラッシュとバッファのスレッド数。
デフォルトは1で、変更するとアウトプット先へのデータ書き込みを並列にすることが出来る。

## 設定例
s3へのアップロードの確認をするにあたって、設定によってなかなかあがらない。。なんて事があるので、matchディレクティブのoutput_copyプラグインでアウトプットをいくつかに分けました。
stdoutで、即座にデバッグして、そもそもファイルに書き込めるかと言う所をoutput_fileプラグインで試して、s3にも同時にあげます。

あがらない際は`/var/log/td-agent/td-agent.log`を確認します。
本番で確認する際は[capistranoのタスクに指定したら](http://qiita.com/momoayumi/items/853179f4192d1c8cfe5a)やりやすいかと思います。

flush_intervalは長いとデバッグしにくいので、初めは1sなどにすると即座にファイルが生成されてやりやすいです。

```
<match *.**>
  type copy
  <store>
    type file
    path /var/log/fluent/sinatra.log
    buffer_path /var/log/fluent/sinatra
    time_slice_format %Y%m%d
    time_format %Y%m%dT%H%M%S%z
  </store>
  <store>
    type s3
    aws_key_id xxxxxxxx
    aws_sec_key xxxxxxxx
    s3_endpoint  xxxxxxxx
    path logs/td-agent/
    format json
    time_slice_format %Y%m%d%H
    flush_interval 1s
    buffer_path /var/log/td-agent
    buffer_chunk_limit 8m
    buffer_queue_limit 1280
    retry_limit 10
    retry_wait 5s
  </store>
  <store>
    type stdout
  </store>
</match>
```

configファイルを変更したら、
`$ sudo /etc/init.d/td-agent reload`で設定ファイルをリロードし、`$ sudo /etc/init.d/td-agent restart`でサーバーを再起動すれば変更が反映されます。

軽く動かしてみたい際はsinatraで動かしたサンプルがあるので[こちら](http://qiita.com/momoayumi/items/175a7a802cebca8ae404)から。

## 参考

バッファのチャンク + キューについて: http://tech-sketch.jp/2013/05/fluentd-buffer.html

fluentdのout fileプラグインの仕様について : http://blog.tnmt.info/2012/10/19/about-fluentd-out-file-plugin/


## 追記

これまで使用されていたs3_endpointですが、今後はs3_regionを使用する事が推奨されているようです。

```
s3 region name. For example, US West (Oregon) Region is “us-west-2”. The full list of regions are available here. > docs.aws.amazon.com/general/latest/gr/rande.html#s3_region. We recommend using `s3_region` instead of `s3_endpoint`.
```

参考リンク : https://github.com/fluent/fluent-plugin-s3