概要
Amazon ECS (以下、 ECS) におけるログ管理では、FireLens と AWS For Fluent Bit を組み合わせた構成が広く採用されています1。この構成により、 AWSLogs ドライバーでは実現できない柔軟なログルーティングとカスタマイズが可能になります。
しかし、ログ分析やトラブルシューティングにおいて、特定のタスクを識別するためのタスク ID が直接的には取得できないという課題があります。FireLens はデフォルトでタスク ARN を提供しますが、多くの運用シナリオではタスク ID そのものが必要になります。
この記事では、Fluent Bit の設定をカスタマイズして、ログにタスク ID を含める方法を解説します。
前提
Fluent Bit のコンフィグには YAML と Classic mode の 2 種類の形式があります。本記事では、現在も広く使用されている Classic mode 形式での設定例を紹介します。
注意: Classic mode 形式は 2026 年末に非推奨となる予定です2。新規プロジェクトでは YAML 形式の採用を検討することをお勧めしますが、既存環境での実装や学習目的では、Classic mode 形式も有効です。
課題の詳細
FireLens は、ECS タスクのログにクラスター名やタスク ARN といったメタデータをデフォルトで付与します3。
しかし、タスク ID そのものは独立したフィールドとして提供されません。
また、 ECS Filter という Fluent Bit のプラグインがありますが、EC2 起動タイプでのみ機能し、 Fargate 起動タイプでは利用できません。
これにより、以下のような運用上の課題が発生します:
- ログ分析ツールでタスク ID の検索・集計が困難
- トラブルシューティング時のタスク特定に手間がかかる
例えば、CloudWatch Logs で特定のタスクのログを検索する際、タスク ARN 全体での検索が必要となり、クエリが複雑になってしまいます。
解決方法: Fluent Bit によるタスク ID 抽出
この課題を解決するため、Fluent Bit のフィルター機能を使用してタスク ARN からタスク ID を抽出し、独立したフィールドとして追加する方法を実装します。
アプローチの概要
既存の FireLens 機能を活用しながらタスク ID を取得します。
- FireLens が提供する
ecs_task_arnフィールドを取得 - Fluent Bit の正規表現フィルターでタスク ID を抽出
- 新しいフィールド
ecs_task_idとしてログレコードに追加
タスクARN 形式
ECS タスク ARN には、アカウント設定により 2 つの形式が存在します4:
- 従来形式:
arn:aws:ecs:region:aws_account_id:task/task-id - 新形式:
arn:aws:ecs:region:aws_account_id:task/cluster-name/task-id
どちらの形式でも、最後のスラッシュ (/) 以降がタスク ID であることがポイントです。
コンフィグ例
パーサー
タスク ARN をパースしてタスク ID を取得するコンフィグは次のようになります。
[PARSER]
Name ecs_task_id
Format regex
Regex .*\/(?<ecs_task_id>[^\/]+)$
正規表現の解説:
.*\/: 文字列の先頭から一番最後の/までにマッチ (貪欲マッチ)(?<ecs_task_id>[^\/]+):ecs_task_idという名前付きキャプチャグループで、最後の/以降の、/を含まない 1 文字以上の文字列 (つまりタスク ID) を取得。これにより新形式と従来形式の ARN 両方に対応$: 文字列の終端を示す
フィルター
次のように Filter から呼び出します。これにより、 ecs_task_id というフィールドがログに追加されます。
[FILTER]
Name parser
Match *-firelens-*
Key_Name ecs_task_arn
Parser ecs_task_id
Reserve_Data true
Preserve_Key true
結果
ログをクエリして、ログにタスク ID (ecs_task_id 列) が正しく追加されることを確認しました。
SELECT dt, ecs_task_id FROM logs WHERE dt > '2025/10/01' LIMIT 10;
おわりに
この記事では、 ECS の FireLens において、タスク ID をログに含める実践的な方法を詳しく解説しました。
今後 AWS For Fluent Bit v3.0.0 を検証して YAML 編も出すかもしれません。
参考
実装
OpenTelemetry Collector の Resource Detection Processor の実装を参考にしました。この実装でもタスク ARN をパースしてタスク ID を取得しています。
// Parses ECS Task ARN into subcomponents according to its spec // See: https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-account-settings.html#ecs-resource-ids func parseTaskARN(taskARN string) (region, account, taskID string) { parts := strings.Split(taskARN, ":") if len(parts) >= 5 { region := parts[3] account := parts[4] // ECS Task ARNs come in two versions. In the old one, the last part of the ARN contains // only the "task/<task-id>". In the new one, it contains "task/cluster-name/task-id". // This handles both cases. taskInfo := parts[5] taskInfoParts := strings.Split(taskInfo, "/") taskID := taskInfoParts[len(taskInfoParts)-1] return region, account, taskID } return "", "", "" }
ドキュメント
- Using custom log routing with FireLens for Amazon ECS - AWS Prescriptive Guidance↩
- Fluent Bit Classic Mode Configuration↩
- Example Amazon ECS task definition: Route logs to FireLens - Amazon Elastic Container Service↩
- Access Amazon ECS features with account settings - Amazon Elastic Container Service↩
