考慮事項必要な IAM アクセス許可 AWS for Fluent Bit イメージの使用 FireLens 設定を使用するタスク定義の作成 Fluent ロガーライブラリの使用正規表現を使用したログのフィルタリングタスク定義の例

カスタムログルーティング

Amazon ECS 対応 FireLens では、タスク定義パラメータを使用して AWS のサービスや AWS パートナーネットワーク (APN ) の宛先にログをルーティングし、ログを保存および分析できます。FireLens は Fluentd および Fluent Bitで動作します。提供されている AWS for Fluent Bit イメージを使用することも、独自の Fluentd または Fluent Bit イメージを使用することもできます。

FireLens 設定を使用した Amazon ECS タスク定義の作成は、AWS SDK、AWS CLI、および AWS マネジメントコンソールでサポートされています。

考慮事項

Amazon ECS 対応 FireLens を使用する際は、以下の点を考慮してください。

Amazon ECS 対応 FireLens は、Fargate および EC2 の両方の起動タイプを使用するタスクでサポートされています。
Amazon ECS の FireLensは、AWS CloudFormation テンプレートでサポートされています。詳細については、AWS CloudFormation ユーザーガイド の「AWS:: ECS::TaskDefinition FirelensConfiguration」を参照してください。
bridge ネットワークモードを使用するタスクの場合、FireLens 設定のコンテナは、それに依存するアプリケーションコンテナが開始する前に開始する必要があります。コンテナの開始順序を制御するには、タスク定義の依存関係条件を使用します。詳細については、「コンテナの依存関係」を参照してください。

注記

FireLens 設定のコンテナ定義で依存関係条件パラメータを使用する場合は、各コンテナに START または HEALTHY 条件要件があることを確認してください。

必要な IAM アクセス許可

この機能を使用するには、タスク用の IAM ロールを作成し、AWS のサービスを使用するために必要なアクセス許可をタスクに付与する必要があります。たとえば、コンテナから Kinesis Data Firehose にログをルーティングする場合、タスクには firehose:PutRecordBatch API を呼び出すためのアクセス許可が必要です。詳細については、IAM ユーザーガイドの「IAM ID アクセス許可の追加と削除」を参照してください。

次の IAM ポリシー例では、ログを Kinesis Data Firehose にルーティングするために必要なアクセス許可を追加します。


{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "firehose:PutRecordBatch"
      ],
      "Resource": [
        "*"
      ]
    }
  ]
}

以下の場合は、タスクに Amazon ECS タスク実行ロールが必要になることもあります。詳細については、「Amazon ECS タスク実行 IAM ロール」を参照してください。

タスクで Fargate 起動タイプを使用していて、Amazon ECR からコンテナイメージをプルしたり、ログ設定で AWS Secrets Manager の機密データを参照したりする場合は、タスク実行 IAM ロールを含める必要があります。
Amazon S3 でホストされるカスタム設定ファイルを指定する場合、タスク実行 IAM ロールには、設定ファイル用の s3:GetObject アクセス許可と、ファイルが格納されている Amazon S3 バケットに対する s3:GetBucketLocation アクセス許可を含める必要があります。詳細については、Amazon Simple Storage Service コンソールユーザーガイドの「ポリシーでのアクセス許可の指定」を参照してください。

次の IAM ポリシー例では、Amazon S3 からファイルを取得するために必要なアクセス許可を追加します。Amazon S3 バケットの名前と設定ファイル名を指定します。
```
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:GetObject"
      ],
      "Resource": [
        "arn:aws:s3:::examplebucket/folder_name/config_file_name"
      ]
    },
    {
      "Effect": "Allow",
      "Action": [
        "s3:GetBucketLocation"
      ],
      "Resource": [
        "arn:aws:s3:::examplebucket"
      ]
    }
  ]
}
```

AWS for Fluent Bit イメージの使用

AWS には、CloudWatch Logs 用と Kinesis Data Firehose 用の両方のプラグインを持つ Fluent Bit イメージが用意されています。Fluent Bit は、リソース使用率が Fluentd よりも低いため、ログルーターとして使用することをお勧めします。詳細については、「 CloudWatch Logs for Fluent Bit 」および「 Amazon Kinesis Firehose for Fluent Bit」を参照してください。

AWS for Fluent Bit イメージは Docker Hub で利用できます。ただし、Amazon ECR では、以下のイメージを使用することをお勧めします。これらのイメージにより、可用性が向上します。

リージョン名	リージョン	イメージ URI
米国東部（バージニア北部）	us-east-1	`906394416424.dkr.ecr.us-east-1.amazonaws.com/aws-for-fluent-bit:latest`
米国東部 (オハイオ)	us-east-2	`906394416424.dkr.ecr.us-east-2.amazonaws.com/aws-for-fluent-bit:latest`
米国西部 (北カリフォルニア)	us-west-1	`906394416424.dkr.ecr.us-west-1.amazonaws.com/aws-for-fluent-bit:latest`
米国西部 (オレゴン)	us-west-2	`906394416424.dkr.ecr.us-west-2.amazonaws.com/aws-for-fluent-bit:latest`
アジアパシフィック (香港)	ap-east-1	`449074385750.dkr.ecr.ap-east-1.amazonaws.com/aws-for-fluent-bit:latest`
アジアパシフィック (ムンバイ)	ap-south-1	`906394416424.dkr.ecr.ap-south-1.amazonaws.com/aws-for-fluent-bit:latest`
アジアパシフィック (ソウル)	ap-northeast-2	`906394416424.dkr.ecr.ap-northeast-2.amazonaws.com/aws-for-fluent-bit:latest`
アジアパシフィック (シンガポール)	ap-southeast-1	`906394416424.dkr.ecr.ap-southeast-1.amazonaws.com/aws-for-fluent-bit:latest`
アジアパシフィック (シドニー)	ap-southeast-2	`906394416424.dkr.ecr.ap-southeast-2.amazonaws.com/aws-for-fluent-bit:latest`
アジアパシフィック (東京)	ap-northeast-1	`906394416424.dkr.ecr.ap-northeast-1.amazonaws.com/aws-for-fluent-bit:latest`
カナダ (中部)	ca-central-1	`906394416424.dkr.ecr.ca-central-1.amazonaws.com/aws-for-fluent-bit:latest`
欧州 (フランクフルト)	eu-central-1	`906394416424.dkr.ecr.eu-central-1.amazonaws.com/aws-for-fluent-bit:latest`
欧州 (アイルランド)	eu-west-1	`906394416424.dkr.ecr.eu-west-1.amazonaws.com/aws-for-fluent-bit:latest`
欧州 (ロンドン)	eu-west-2	`906394416424.dkr.ecr.eu-west-2.amazonaws.com/aws-for-fluent-bit:latest`
欧州 (パリ)	eu-west-3	`906394416424.dkr.ecr.eu-west-3.amazonaws.com/aws-for-fluent-bit:latest`
欧州 (ストックホルム)	eu-north-1	`906394416424.dkr.ecr.eu-north-1.amazonaws.com/aws-for-fluent-bit:latest`
中東 (バーレーン)	me-south-1	`741863432321.dkr.ecr.me-south-1.amazonaws.com/aws-for-fluent-bit:latest`
南米 (サンパウロ)	sa-east-1	`906394416424.dkr.ecr.sa-east-1.amazonaws.com/aws-for-fluent-bit:latest`
AWS GovCloud (米国東部)	us-gov-east-1	`161423150738.dkr.ecr.us-gov-east-1.amazonaws.com/aws-for-fluent-bit:latest`
AWS GovCloud (US-West)	us-gov-west-1	`161423150738.dkr.ecr.us-gov-west-1.amazonaws.com/aws-for-fluent-bit:latest`
中国 (北京)	cn-north-1	`128054284489.dkr.ecr.cn-north-1.amazonaws.com.cn/aws-for-fluent-bit:latest`
中国 (寧夏)	cn-northwest-1	`128054284489.dkr.ecr.cn-northwest-1.amazonaws.com.cn/aws-for-fluent-bit:latest`

FireLens 設定を使用するタスク定義の作成

FireLens でカスタムログルーティングを使用するには、タスク定義で以下を指定する必要があります。

FireLens 設定を含むログルーターコンテナ。コンテナは essential とマークすることが推奨されます。
awsfirelens ログドライバーを指定するログ設定を含む 1 つ以上のアプリケーションコンテナ。
タスクでログをルーティングするために必要なアクセス許可を含むタスク IAM ロール ARN。

AWS マネジメントコンソールを使用して新しいタスク定義を作成する場合、ログルーターコンテナを簡単に追加できる FireLens 統合セクションがあります。詳細については、「タスク定義の作成」を参照してください。

Amazon ECS はログ設定を変換し、Fluentd または Fluent Bit 出力設定を生成します。出力設定は、/fluent-bit/etc/fluent-bit.conf (Fluent Bit) および /fluentd/etc/fluent.conf (Fluentd) のログルーティングコンテナにマウントされます。

以下のタスク定義の例では、Fluent Bit を使用してログを CloudWatch Logs にルーティングするログルーターコンテナを定義しています。また、ログ設定を使用してログを Amazon Kinesis Data Firehose にルーティングするアプリケーションコンテナも定義しています。


{
	"family": "firelens-example-firehose",
	"taskRoleArn": "arn:aws:iam::123456789012:role/ecs_task_iam_role",
	"containerDefinitions": [
		{
			"essential": true,
			"image": "906394416424.dkr.ecr.us-west-2.amazonaws.com/aws-for-fluent-bit:latest",
			"name": "log_router",
			"firelensConfiguration": {
				"type": "fluentbit"
			},
			"logConfiguration": {
				"logDriver": "awslogs",
				"options": {
					"awslogs-group": "firelens-container",
					"awslogs-region": "us-west-2",
					"awslogs-create-group": "true",
					"awslogs-stream-prefix": "firelens"
				}
			},
			"memoryReservation": 50
		 },
		 {
			 "essential": true,
			 "image": "httpd",
			 "name": "app",
			 "logConfiguration": {
				 "logDriver":"awsfirelens",
				 "options": {
					"Name": "firehose",
					"region": "us-west-2",
					"delivery_stream": "my-stream"
				}
			},
			"memoryReservation": 100		
            }
	]
}

logConfiguration オブジェクトのオプションとして指定されたキーと値のペアは、Fluentd または Fluent Bit 出力設定の生成に使用されます。Fluent Bit 出力定義のコード例は次のとおりです。


[OUTPUT]
    Name   firehose
    Match  app-firelens*
    region us-west-2
    delivery_stream my-stream

注記

FireLens は match 設定を管理します。この設定は、タスク定義で指定されません。

Amazon ECS メタデータの使用

タスク定義で FireLens 設定を指定する場合、必要に応じて enable-ecs-log-metadata の値を切り替えることができます。デフォルトでは、Amazon ECS は、ログのソースを識別するのに役立つ追加のフィールドをログエントリに追加します。このアクションを無効にするには、enable-ecs-log-metadata を false に設定します。

ecs_cluster – タスクが所属するクラスターの名前。
ecs_task_arn – コンテナが所属するタスクの完全な ARN。
ecs_task_definition – タスクが使用しているタスク定義名とリビジョン。
ec2_instance_id – コンテナがホストされている Amazon EC2 インスタンス ID。このフィールドは、EC2 起動タイプを使用するタスクでのみ有効です。

Amazon ECS ログメタデータ設定値を指定するときに必要な構文を次に示します。


{
   "containerDefinitions":[
      {
         "essential":true,
         "image":"906394416424.dkr.ecr.us-west-2.amazonaws.com/aws-for-fluent-bit:latest",
         "name":"log_router",
         "firelensConfiguration":{
            "type":"fluentbit",
            "options":{
               "enable-ecs-log-metadata":"true | false"
            }
         }
      }
   ]
}

カスタム設定ファイルの指定

FireLens で自動的に生成される設定ファイルに加えて、自分でカスタム設定ファイルを指定することもできます。設定ファイル形式は、使用しているログルーターのネイティブ形式です。詳細については、「Fluentd 設定ファイルの構文」および「Fluent Bit 設定スキーマ」を参照してください。

カスタム設定ファイルの場合、bridge または awsvpc ネットワークモードを使用するタスクでは、TCP 経由で Fluentd または Fluent Bit 転送入力を設定しないでください (FireLens ではそれが入力設定に追加されます)。

カスタム設定ファイルを指定するには、FireLens 設定に次のオプションを含める必要があります。

config-file-type: カスタム設定ファイルのソースの場所。使用できるオプションは、s3 または file です。
config-file-value: カスタム設定ファイルのソース。s3 設定ファイルタイプを使用する場合、設定ファイルの値は Amazon S3 バケットとファイルの完全な ARN です。file 設定ファイルタイプを使用する場合、設定ファイルの値は、コンテナイメージ内またはコンテナにマウントされているボリューム上に存在する設定ファイルの完全パスです。

重要

カスタム設定ファイルを使用する場合は、FireLens が使用するパスとは異なるパスを指定する必要があります。Amazon ECS では /fluent-bit/etc/fluent-bit.conf (Fluent Bit) と /fluentd/etc/fluent.conf (Fluentd) のファイルパスは予約されています。

次の例は、カスタム設定を指定するときに必要な構文を示しています。

重要

Amazon S3 でホストされるカスタム設定ファイルを指定するには、適切なアクセス許可を持つタスク実行 IAM ロールが作成済みであることを確認します。詳細については、「必要な IAM アクセス許可」を参照してください。

カスタム設定を指定するときに必要な構文を次に示します。


{
   "containerDefinitions":[
      {
         "essential":true,
         "image":"906394416424.dkr.ecr.us-west-2.amazonaws.com/aws-for-fluent-bit:latest",
         "name":"log_router",
         "firelensConfiguration":{
            "type":"fluentbit",
            "options":{
               "config-file-type":"s3 | file",
               "config-file-value":"arn:aws:s3:::mybucket/fluent.conf | filepath"
            }
         }
      }
   ]
}

注記

Fargate 起動タイプを使用するタスクの場合、サポートされる config-file-type の値は file のみです。

Fluent ロガーライブラリの使用

awsfirelens ログドライバーがタスク定義で指定されている場合、ECS エージェントは次の環境変数をコンテナに挿入します。

FLUENT_HOST: FireLens コンテナに割り当てられた IP アドレス。
FLUENT_PORT: Fluent Forward プロトコルがリッスンしているポート。

FLUENT_HOST 環境変数および FLUENT_PORT 環境変数を使用すると、stdout を介することなく、コードからログルーターに直接ログを記録できます。詳細については、GitHub の「flluent-logger-golang」を参照してください。

正規表現を使用したログのフィルタリング

Fluentd と Fluent Bit はどちらも、ログの内容に応じたログのフィルタリングをサポートしています。FireLens には、このフィルタリングを有効にするための簡単な方法があります。コンテナ定義のログ設定 options では、正規表現を値として受け取る特殊なキー include-pattern および exclude-pattern を指定できます。exclude-pattern キーでは、正規表現に一致するすべてのログが削除されます。include-pattern では、正規表現に一致するログのみが送信されます。これらのキーは一緒に使用できます。

次の例は、このフィルタの使用方法を示しています。


{
   "containerDefinitions":[
      {
         "logConfiguration":{
            "logDriver":"awsfirelens",
            "options":{
               "@type":"cloudwatch_logs",
               "log_group_name":"firelens-testing",
               "auto_create_stream":"true",
               "use_tag_as_stream":"true",
               "region":"us-west-2",
               "exclude-pattern":"^[a-z][aeiou].*$",
               "include-pattern":"^.*[aeiou]$"
            }
         }
      }
   ]
}

タスク定義の例

次に示すのは、一般的なログルーティングオプションを示すタスク定義の例です。その他の例については、GitHub の「Amazon ECS FireLens の例」を参照してください。

トピック

CloudWatch Logs へのログの転送
Amazon Kinesis Data Firehose 配信ストリームへのログの転送
外部の Fluentd または Fluent Bit への転送

CloudWatch Logs へのログの転送

次のタスク定義の例は、CloudWatch Logs ロググループにログを転送するログ設定を指定する方法を示しています。詳細については、Amazon CloudWatch Logs User Guideの「Amazon CloudWatch Logs とは」を参照してください。

ログ設定オプションで、ロググループ名とロググループが存在するリージョンを指定します。Fluent Bit で自動的にロググループを作成するには、"auto_create_group":"true" を指定します。フィルタリングに役立つログストリームプレフィックスを指定することもできます。詳細については、「CloudWatch Logs 用の Fluent Bit プラグイン」を参照してください。


{
	"family": "firelens-example-cloudwatch",
	"taskRoleArn": "arn:aws:iam::123456789012:role/ecs_task_iam_role",
	"containerDefinitions": [
		{
			"essential": true,
			"image": "906394416424.dkr.ecr.us-west-2.amazonaws.com/aws-for-fluent-bit:latest",
			"name": "log_router",
			"firelensConfiguration": {
				"type": "fluentbit"
			},
			"logConfiguration": {
				"logDriver": "awslogs",
				"options": {
					"awslogs-group": "firelens-container",
					"awslogs-region": "us-west-2",
					"awslogs-create-group": "true",
					"awslogs-stream-prefix": "firelens"
				}
			},
			"memoryReservation": 50
		 },
		 {
			 "essential": true,
			 "image": "nginx",
			 "name": "app",
			 "logConfiguration": {
				 "logDriver":"awsfirelens",
				 "options": {
					"Name": "cloudwatch",
					"region": "us-west-2",
					"log_group_name": "firelens-testing-fluent-bit",
					"auto_create_group": "true",
					"log_stream_prefix": "from-fluent-bit"
				}
			},
			"memoryReservation": 100
		}
	]
}

Amazon Kinesis Data Firehose 配信ストリームへのログの転送

次のタスク定義の例は、Amazon Kinesis Data Firehose 配信ストリームにログを転送するログ設定を指定する方法を示しています。Kinesis Data Firehose 配信ストリームはすでに存在している必要があります。詳細については、Amazon Kinesis Data Firehose 開発者ガイドの「Amazon Kinesis Data Firehose 配信ストリームの作成」を参照してください。

ログ設定オプションで、配信ストリーム名と配信ストリームが存在するリージョンを指定します。詳細については、「 Amazon Kinesis Firehose 用の Fluent Bit プラグイン」を参照してください。


{
	"family": "firelens-example-firehose",
	"taskRoleArn": "arn:aws:iam::123456789012:role/ecs_task_iam_role",
	"containerDefinitions": [
		{
			"essential": true,
			"image": "906394416424.dkr.ecr.us-west-2.amazonaws.com/aws-for-fluent-bit:latest",
			"name": "log_router",
			"firelensConfiguration": {
				"type": "fluentbit"
			},
			"logConfiguration": {
				"logDriver": "awslogs",
				"options": {
					"awslogs-group": "firelens-container",
					"awslogs-region": "us-west-2",
					"awslogs-create-group": "true",
					"awslogs-stream-prefix": "firelens"
				}
			},
			"memoryReservation": 50
		 },
		 {
			 "essential": true,
			 "image": "httpd",
			 "name": "app",
			 "logConfiguration": {
				 "logDriver":"awsfirelens",
				 "options": {
					"Name": "firehose",
					"region": "us-west-2",
					"delivery_stream": "my-stream"
				}
			},
			"memoryReservation": 100		
            }
	]
}

外部の Fluentd または Fluent Bit への転送

次のタスク定義の例は、外部の Fluentd または Fluent Bit ホストにログを転送するログ設定を指定する方法を示しています。環境の host と port を指定します。


{
	"family": "firelens-example-forward",
	"taskRoleArn": "arn:aws:iam::123456789012:role/ecs_task_iam_role",
	"containerDefinitions": [
		{
			"essential": true,
			"image": "906394416424.dkr.ecr.us-west-2.amazonaws.com/aws-for-fluent-bit:latest",
			"name": "log_router",
			"firelensConfiguration": {
				"type": "fluentbit"
			},
			"logConfiguration": {
				"logDriver": "awslogs",
				"options": {
					"awslogs-group": "firelens-container",
					"awslogs-region": "us-west-2",
					"awslogs-create-group": "true",
					"awslogs-stream-prefix": "firelens"
				}
			},
			"memoryReservation": 50
		 },
		 {
			 "essential": true,
			 "image": "httpd",
			 "name": "app",
			 "logConfiguration": {
				 "logDriver":"awsfirelens",
				 "options": {
					"Name": "forward",
					"Host": "fluentdhost",
					"Port": "24224"
				}
			},
			"memoryReservation": 100
		}
	]
}

ブラウザで JavaScript が無効になっているか、使用できません。

AWS ドキュメントを使用するには、JavaScript を有効にする必要があります。手順については、使用するブラウザのヘルプページを参照してください。

ドキュメントの表記規則

awslogs ログドライバーを使用する

タスクのプライベートレジストリの認証