Kinesis エージェント インストール時の手順といろいろメモ

EC2 から Kinesis Firehose にデータを配信する際のKinesis エージェント インストールの手順を検証しました。
エラーやひっかかりポイントもメモしています。
殴り書きですが、誰かの助けになれば嬉しいです。

（Kinesis Datastream の場合もほぼ同様の手順で設定できます。
エージェントの設定ファイルで datastream.endpoint を記載する必要があります。）


<br>

## Kinesis エージェントインストール前の環境準備

### 1. Agent をインストールする EC2 に IAM ロール付与
検証では S3 に配信する設定にしたので以下の権限を IAM ロールに設定しました。
　・AmazonKinesisFirehoseFullAccess
　・CloudWatchFullAccess
　・AmazonS3FullAccess

必要な権限を Kinesis エージェントの設定ファイルに AWS アクセスキーとシークレットアクセスキーを設定する方法もあります。
また、Kinesis エージェントは他 AWS リソースに Put 権限が必要な操作がほとんどなので、必要な場合は更に権限を絞れると思います。

[AWSドキュメント> Amazon Kinesis Data Streams > 前提条件](https://docs.aws.amazon.com/ja_jp/streams/latest/dev/writing-with-agents.html#prereqs)


<br>

## Kinesis エージェントの設定

### 1. エージェントインストール
インストールOS : Amazon Linux2

AWS ドキュメントの「Amazon Linux AMI を使用してエージェントを設定する」方法だと、以下のエラーが出てしまいます。(2020年4月時点の amazonlinux2)

```
$ sudo yum install –y aws-kinesis-agent
Loaded plugins: extras_suggestions, langpacks, priorities, update-motd
amzn2-core                                                                                     | 2.4 kB  00:00:00     
No package aws-kinesis-agent available.
Error: Nothing to do
```

Kinesis エージェントの GitHub ページ（[GitHub - awslabs/amazon-kinesis-agent: Continuously monitors a set of log files and sends new data to the Amazon Kinesis Stream and Amazon Kinesis Firehose in near-real-time.](https://github.com/awslabs/amazon-kinesis-agent)）を見に行くと README に以下の記載がありました。
>**Building from Source**
The installation done by the setup script is only tested on the following OS Disributions:
>
>Red Hat Enterprise Linux version 7 or later
Amazon Linux AMI version 2015.09 or later
Ubuntu Linux version 12.04 or later
Debian Linux version 8.6 or later

ということで今回は AWS ドキュメントに記載の「Red Hat Enterprise Linux を使用してエージェントを設定する」方法でインストールしちゃいます。

```
$sudo yum install –y https://s3.amazonaws.com/streaming-data-agent/aws-kinesis-agent-latest.amzn1.noarch.rpm
.
.
.
Complete!
```

ちょっと遠回りでしたがインストールできました。バージョンも確認しておきます。

```
$ yum list | grep aws-kinesis-agent
aws-kinesis-agent.noarch               1.1.4-1.amzn1                  installed 
```


<br>


### 2. Kinesis エージェント設定ファイルの編集

Kinesis エージェントの設定ファイルを編集して、Kinesis Firehose にデータ配信できるようにします。

```
vim /etc/aws-kinesis/agent.json
```

設定ファイルの処理オプション等の情報は、以下の AWS ドキュメントにまとまっています。
[Agent Configuration Settings](https://docs.aws.amazon.com/firehose/latest/dev/writing-with-agents.html#agent-config-settings)


今回は以下のように設定しました。

```
{
  "cloudwatch.emitMetrics": true,
  "cloudwatch.endpoint": "https://monitoring.ap-northeast-1.amazonaws.com",
  "firehose.endpoint": "https://firehose.ap-northeast-1.amazonaws.com",

  "flows": [
    {
      "filePattern": "/tmp/demo-app.log/*",
      "deliveryStream": "demo-firehose-stream",
      "initialPosition": "START_OF_FILE",
      "maxBufferAgeMillis": "2000",
      "dataProcessingOptions": [
        {
          "optionName": "LOGTOJSON",
          "logFormat": "COMBINEDAPACHELOG"
        }
      ]
    }
  ]
}
```

設定ファイルの内の `"dataProcessingOptions"` は Kinesis にデータ配信する前にログ処理(加工)ができる設定です。
`"optionName": "LOGTOJSON"` はログ形式が Apache log や Syslog の場合には有効な処理オプションです。

>LOGTOJSON
ログ形式から JSON 形式にレコードを変換します。サポートされているログ形式は、Apache Common Log、Apache Combined Log、Apache Error Log、および RFC3164 Syslog です。
>[Use the Agent to Preprocess Data](https://docs.aws.amazon.com/firehose/latest/dev/writing-with-agents.html#pre-processing)

他処理オプションだと CSV ファイル等も変換できます。
詳細は AWS ドキュメントに記載されています。
[Use the Agent to Preprocess Data](https://docs.aws.amazon.com/firehose/latest/dev/writing-with-agents.html#pre-processing)



### 3. Kinesis エージェント起動

以下コマンドでエージェントを起動します。

```
$ sudo service aws-kinesis-agent start
```

他コマンドもまとめて記載します。
※設定ファイル(`/etc/aws-kinesis/agent.json`)変更後は再起動をお忘れなく！

```
# サービス起動停止
$ sudo service aws-kinesis-agent start
$ sudo service aws-kinesis-agent restart
$ sudo service aws-kinesis-agent stop
$ sudo service aws-kinesis-agent status

# 自動起動の設定
$ sudo chkconfig aws-kinesis-agent on
$ sudo chkconfig aws-kinesis-agent off
```

<br>

## その他メモ

- Kinesis エージェントの設定ファイル例

AWS ドキュメントにエージェントの設定ファイル例があります。
[AWSドキュメント> Amazon Kinesis Data Streams > エージェントの設定](https://docs.aws.amazon.com/ja_jp/streams/latest/dev/writing-with-agents.html#agent-config-settings)

GitHub にも参考になりそうな `agent.json` がありました。
[amazon-kinesis-agent/configuration/example at master · awslabs/amazon-kinesis-agent · GitHub](https://github.com/awslabs/amazon-kinesis-agent/tree/master/configuration/example)


<br>

- Kinesis firehose 確認用 awscli コマンド
Kinesis エージェントをインストールした EC2 上で、EC2⇔Firehose 間の疎通確認をした時のコマンドメモです。

```
# Kinesis firehose の設定値確認
$ aws firehose describe-delivery-stream --delivery-stream-name demo-firehose-stream

# Kinesis firehose でテストレコード配信
$ aws firehose put-record --delivery-stream-name demo-firehose-stream --record Data="some data\n"

# Kinesis firehose で JSON データでテストレコード配信
$ aws firehose put-record --delivery-stream-name demo-firehose-stream --record '{"Data":"{\"field1\":vlue1}"}'
```

<br>


- S3 確認用 awscli コマンド
ちゃんとログが S3 に配信されているか確認する時用のメモです。

```
$ aws s3 cp s3://${BUCKET_NAME}/2020/04/01/04/demo-firehose-stream-1-2020-02-13-04-13-17-xxx-xxx-xxx-xxx-xxx - | cat


aws s3 ls s3://${BUCKET_NAME} --recursive
```


<br>

- Kinesis エージェントのログ確認
ログは `/var/log/aws-kinesis-agent/aws-kinesis-agent.log` に出力されます。
以下はデータ配信が上手くいかなかった時に出たエラーのメモです。

```
# パスが上手くいってない時のエラー
2020-02-13 05:42:03.245+0000  (FileTailer[fh:demo-firehose-stream:/home/ec2-user/apache-log*]) com.amazon.kinesis.streaming.agent.Agent [ERROR] FATAL: Thread FileTailer[fh:demo-firehose-stream:/home/ec2-user/apache-log*] threw an unrecoverable error. Aborting application
java.lang.RuntimeException: java.nio.file.AccessDeniedException: /home/ec2-user

# 必要な AWS サービスの権限が無い時のエラー
2020-02-13 06:59:04.043+0000  (sender-57) com.amazon.kinesis.streaming.agent.tailing.AsyncPublisher [ERROR] AsyncPublisher[fh:demo-firehose-stream:/tmp/demo-apache-log/*]:RecordBuffer(id=2,records=20,bytes=4626) Retriable send error (com.amazonaws.services.kinesisfirehose.model.AmazonKinesisFirehoseException: User: arn:aws:sts::123456789012:assumed-role/demo-firehose-stream/i-xxxxx is not authorized to perform: firehose:PutRecordBatch on resource: arn:aws:firehose:ap-northeast-1:123456789012:deliverystream/demo-firehose-stream (Service: AmazonKinesisFirehose; Status Code: 400; Error Code: AccessDeniedException; Request ID: xxx-xxx-xxx-xxx-xxx)). Will retry.

# その後成功した時のログ
2020-02-14 03:18:13.802+0000  (FileTailer[fh:demo-firehose-stream:/tmp/demo-apache-log/*].MetricsEmitter RUNNING) com.amazon.kinesis.streaming.agent.tailing.FileTailer [INFO] FileTailer[fh:demo-firehose-stream:/tmp/demo-apache-log/*]: Tailer Progress: Tailer has parsed 5938 records (1344370 bytes), transformed 0 records, skipped 0 records, and has successfully sent 5938 records to destination.
2020-02-14 03:18:13.808+0000  (Agent.MetricsEmitter RUNNING) com.amazon.kinesis.streaming.agent.Agent [INFO] Agent: Progress: 5938 records parsed (1344370 bytes), and 5938 records sent successfully to destinations. Uptime: 68580047ms
```

<br>


## 参考 AWS ドキュメント

[Kinesis エージェントを使用した Kinesis Data Firehose への書き込み](https://docs.aws.amazon.com/ja_jp/firehose/latest/dev/writing-with-agents.html)

[Amazon CloudWatch による Kinesis Data Streams エージェントのヘルスのモニタリング](https://docs.aws.amazon.com/ja_jp/streams/latest/dev/agent-health.html)

[サンプルデータを使用した配信ストリームのテスト](https://docs.aws.amazon.com/ja_jp/firehose/latest/dev/test-drive-firehose.html)

[Amazon Kinesis Data Firehose データ配信](https://docs.aws.amazon.com/ja_jp/firehose/latest/dev/basic-deliver.html)

[複数のファイルディレクトリを監視し、複数のストリームに書き込み](https://docs.aws.amazon.com/ja_jp/streams/latest/dev/writing-with-agents.html#sim-writes)