Logstashが実装するS3プラグイン(input/output)の活用について


## 目的

　LogstashにはS3内のデータを抽出（Input）したり、データを出力（Output）するプラグインが存在します。[Logstashプラグインのサポートについて](https://qiita.com/hamingcode/items/0d5fa544351592ff37f3)の記事にて解説した通り、両プラグイン供にTier1のプラグインであり、Elastic社の有償サポートに加入している場合はプロダクト保証があります。Inputプラグインの最新バージョンは```version: v3.4.1```であリ、Outputプラグインの最新バージョンは```version: v3.4.1```であります。
　本投稿では、それらプラグインの基本的な利用方法について解説します。Elastic社のマニュアルから、基本的な設定方法をピックアップして設定の勘所を記載します。それぞれのマニュアルは以下を参考にしました。
　


- [S3 input-plugin official document by Elastic](https://www.elastic.co/guide/en/logstash/current/plugins-inputs-s3.html)
- [S3 output-plugin official document by Elastic](https://www.elastic.co/guide/en/logstash/current/plugins-outputs-s3.html)

![ダウンロード.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/482612/e08377d3-d4be-e35a-16aa-85a58774e1c6.png)



## S3 input plugin

### Main Parameter

S3 input pluginで利用する主要パラメータについて、以下で解説します。基本的にはこれらのパラメータを設定するだけで良いですが、より応用的な使い方をしたい場合は、[S3 input-plugin official document by Elastic](https://www.elastic.co/guide/en/logstash/current/plugins-inputs-s3.html)を参照してください。

- ***access_key_id***: [string]
- ***secret_access_key***: [string]
  - S3にアクセスするためのcredential情報を記載します。コンフィグレーションファイルに、これらの情報を記載したくない場合は、credential情報が記載された別ファイルをパラメータで指定することも可能です。具体的には、```aws_credentials_file```の値を設定します。

- ***aws_credentials_file*** [string]
  - AWS credential情報が格納されたyamlファイルのpath情報です。このパラメータは、```access_key_id```と```secret_access_key```のパラメータが設定されていない場合にのみ、読み込まれます。

- ***bucket*** [string]
  - S3 bucketの名前。Logstashインスタンスからアクセス可能なS3 bucketを指定する必要があります。

- ***region*** [string]
  - S3 bucketのRegion。デフォルト値は```us-east-1```のため、必要に応じて変更する必要があります。

- ***delete*** [boolean]
  - ```true```に設定することで、データ抽出後にS3内のオリジナルデータを削除することができます。


- ***temporary_directory*** [string]
  - S3から取得したデータを一時的に保管するディレクトリ。デフォルトのディレクトリパスは、```/tmp/logstash```です。

- ***watch_for_new_files*** [boolean]
  - S3に格納される新規ファイルを継続的に取得し続けるかどうかを設定します。

- ***interval*** [number]
  - LogstashがS3にデータ取得するインターバル。デフォルトは60秒。


- ***include_object_properties*** [boolean]
  - S3のオブジェクトプロパティをデータ取得対象にするか否かを決定します。


- ***prefix*** [string]
  - データ取得対象のプレフィックス長を設定する。もし、設定されている場合、プレフィックスがマッチしたファイルに限り、Lostashのデータ取得対象となります。
 

### Setting Example
以下にS3 input pluginの設定例を示します。

```ruby:input_plugin_example
input {
  s3 {
    access_key_id => "<your-access_key_id>"
    secret_access_key => "<your-access_secret_access_key>"
    region => "<your-region>"
    bucket => "<your-bucket>"
    prefix => "Logs"
    interval => "10"
    delete => false
    watch_for_new_files => true
    include_object_properties => false
  }
}
```

## S3 output plugin

### Main Parameter
S3 output pluginで利用する主要パラメータについて、以下で解説します。基本的にはこれらのパラメータを設定するだけで良いですが、より応用的な使い方をしたい場合は、[S3 output-plugin official document by Elastic](https://www.elastic.co/guide/en/logstash/current/plugins-outputs-s3.html)を参照してください。

- ***access_key_id***: [string]
- ***secret_access_key***: [string]
  - S3にアクセスするためのcredential情報を記載します。コンフィグレーションファイルに、これらの情報を記載したくない場合は、credential情報が記載された別ファイルをパラメータで指定することも可能です。具体的には、```aws_credentials_file```の値を設定します。

- ***bucket*** [string]
  - S3 bucketの名前。Logstashインスタンスからアクセス可能なS3 bucketを指定する必要があります。

- ***region*** [string]
  - S3 bucketのRegion。デフォルト値は```us-east-1```のため、必要に応じて変更する必要があります。

- ***temporary_directory*** [string]
  - S3へデータ出力する前に使用する一時保管用のディレクトリ。デフォルトのディレクトリパスは、```/tmp/logstash```です。このディレクトリにS3へ格納する前のファイルが格納され、```rotation_strategy```などで設定したローテーション方針に従い処理されることになります。


- ***canned_acl*** [string]
  - 格納ファイルに対するアクセス制限。```private, public-read, public-read-write, authenticated-read, aws-exec-read, bucket-owner-read, bucket-owner-full-control, log-delivery-write```から１つ選択します。デフォルト値は、```private```です。


- ***encoding*** [string]
  - 格納ファイルに対する圧縮方式。```none, gzip```から１つ選択する。デフォルト値は、```node```です。


- ***upload_queue_size*** [number]
  - S3へアップロードする前にLogstashインスタンスのキュー内に保持する最大メッセージ数。デフォルト値は```4```です。


- ***storage_class*** [string]
  - 格納ファイルのデータ保持方式。```STANDARD, REDUCED_REDUNDANCY, STANDARD_IA, ONEZONE_IA```から１つ選択します。デフォルト値は、```STANDARD```です。


- ***restore*** [boolean]
  - Logstash異常終了時の回復機能利用有無を指定します。trueの場合、```temporary_directory```内のログファイルがrecoverされてuploadされます。デフォルト値は、```true```です。

- ***rotation_strategy*** [string]
  - 出力するファイルをローテーションするアルゴリズムを指定します。```size_and_time, size, time```から１つ選択します。デフォルト値は、```size_and_time```です。


- ***size_file*** [number]
  - ローテーションするファイルサイズ(byte)を指定します。デフォルト値は、```5242880```bytesです。


- ***time_file*** [number]
  - ローテーションするタイミング(分)を指定します。デフォルト値は、```15```分です。


- ***prefix*** [string]
  - ファイル名のprefixを設定します。prefixで指定したオブジェクト名称で格納されます。


### Setting Example
以下にS3 output pluginの設定例を示します。

```ruby:output_plugin_example
output {
  s3{
    access_key_id => "<your-access_key_id>"
    secret_access_key => "<your-access_secret_access_key>"
    region => "<your-region>"
    bucket => "<your-bucket>"
    prefix => "test/%{+YYYY}/%{+MM}/%{+dd}"
    encoding => "gzip"
    rotation_strategy => "time"
    time_file => 1
  }
}
```

以上です。