ECS のイベントキャプチャ機能について調べてみた
ECS のイベントキャプチャ機能とは？
2025 年 10 月に ECS でワンクリックでのイベントキャプチャセットアップ機能と、イベント履歴クエリ機能がサポートされており、これらをまとめてイベントキャプチャ機能と呼ぶようです。
イベントキャプチャセットアップ機能は、マネジメントコンソールで ECS クラスター設定から「イベントキャプチャをオンにする」を有効化することで、ECS 関連のイベントを CloudWatch ログに出力する設定を行ってくれるものです。
特に、停止した古いタスクの情報は 1 時間で消えてしまうため、CloudWatch Logs にイベントログを連携しておくとトラブルシューティングに役立ちます。
Stopped tasks only appear in the console for 1 hour.
https://docs.aws.amazon.com/AmazonECS/latest/developerguide/stopped-task-errors.html
また、こちらはマネジメントコンソール限定の機能であり、現状専用の API があるようなものではありません。
有効化すると、裏で CreateLogGroup や PutRule API が実行されて各種リソースが作成されます。
イベント履歴クエリ機能はマネジメントコンソールの「イベント履歴」タブから簡単にイベント検索を行うことができる機能です。
CloudWatch Logs に出力したイベントログに対して、Logs Insights クエリを使わずに過去イベントの調査を行うことができます。
やってみた
イベントキャプチャをオンにしてみる
クラスター設定から「イベントキャプチャをオンにする」をクリックします。
この際、イベントログの保持期間のみ選択可能です。
今回はデフォルトの 7 日間に設定します。
EventBridge ルールと CloudWatch ロググループが作成され、コンソールから各リソースの詳細ページに移動できるようになります。
作成されたリソースを確認していきます。
EventsToLogs-<クラスター名>-<ランダム文字列> という命名規則で EventBridge ルールが作成されていました。
イベントパターンは下記のように設定されました。
{
"source": ["aws.ecs"],
"detail": {
"clusterArn": [
"arn:aws:ecs:ap-northeast-1:<AWS_ACCOUNT_ID>:cluster/default"
]
}
}
作成された EventBridge ルールのターゲットには合わせて作成された CloudWatch ロググループ /aws/events/ecs/containerinsights/<ECS_CLUSTER_NAME>/performance が指定されました。
イベントの絞り込みに関して
ECS イベントには下記 4 種類が存在しています。
| イベントの種類 | 内容 |
|---|---|
| Container instance state change events | コンテナインスタンスの状態が変わった時に発生するイベント 例) ECS コンテナエージェントが ECS と接続できなくなった |
| Task state change events | ECS タスクの状態が変わった時に発生するイベント 例) ECS タスクが停止した |
| Service action events | ECS サービスの状態が変わった時に発生するイベント 例) ECS サービスが安定状態になった |
| Service deployment state change events | ECS サービスのデプロイメントに関するイベント 例) デプロイメントが完了した |
また、Service action events と Service deployment state change events はイベントごとに重要度が定義されています。
イベントキャプチャを有効化した際に CloudWatch ログに保存するイベントを種類や重要度で細かく制御することはできません。
そのような要件があれば、自前で EventBridge ルールを作成するか、作成された EventBridge ルールのポリシーを直接変更する必要があります。
Event capture stores all events for simplicity. You cannot configure rules in the Amazon ECS console to capture only specific events.
https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-lifecycle-events.html#task-lifecycle-events-limitations
CloudWatch ロググループのリソースベースポリシーについて
イベントキャプチャをオンにすると、下記リソースベースポリシーが設定されます。
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "EventBridgeToCloudWatchLogs",
"Effect": "Allow",
"Principal": {
"Service": "events.amazonaws.com"
},
"Action": ["logs:CreateLogStream", "logs:PutLogEvents"],
"Resource": "arn:aws:logs:ap-northeast-1:<AWS_ACCOUNT_ID>:log-group:/aws/events/ecs/containerinsights/*:*",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "<AWS_ACCOUNT_ID>"
},
"ArnLike": {
"aws:SourceArn": "arn:aws:events:ap-northeast-1:<AWS_ACCOUNT_ID>:rule/EventsToLogs*"
}
}
}
]
}
昨年のアップデートで EventBridge から各種ターゲットの呼び出しは IAM ロール推奨になったと思っていたのですが、CloudWatch ログはまだリソースベースポリシーを利用しないといけなそうですね。
(たしかに Lambda、SNS、SQS、Event Bus は書いてあるけど、CloudWatch ログは書いてない...？そうなると all target types とは一体...？)
Amazon EventBridge expands execution role support to AWS Lambda, Amazon SNS, and Amazon SQS event bus targets, making this feature available for all target types.
https://aws.amazon.com/about-aws/whats-new/2025/03/amazon-eventbridge-iam-execution-role-all-targets/
マネジメントコンソールから設定する際も SNS トピックは実行ロールを利用可能でした。
CloudWatch ログの場合は、設定できない。
ECS イベントキャプチャとはあまり関係無いので今回この点についてこれ以上突っ込みませんが、リソースベースポリシー設定は忘れがちなので、丸っと設定してくれるのはありがたいですね。
イベント履歴クエリを利用してみる
ECS サービス詳細ページもしくは ECS クラスター詳細ページの「イベント履歴」からタスク状態イベントやサービスアクションイベントを簡単に閲覧することが可能です。
事前定義済みのクエリを利用してマネジメントコンソールから CloudWatch Logs Insights のクエリを実行しているようで、検索条件は制限されています。
The Amazon ECS console provides predefined query criteria. For advanced queries, use Amazon CloudWatch Logs Logs Insights to query the log group directly.
https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-lifecycle-events.html#task-lifecycle-events-limitations
とはいえ、この位の条件で絞り込めれば十分に感じます。
クラスターレベルのイベント履歴とサービスレベルのイベント履歴
イベント履歴クエリを実行する際、クラスターレベルでのイベントの表示(クラスター詳細ページのイベントタブから検索)とサービスレベルでのイベントの表示(サービス詳細ページのイベントタブから検索)が可能です。
クラスターレベルで条件を指定せずに「タスク状態変更イベント」を検索してみると、下記クエリが実行されました(CloudTrail から確認)。
filter `detail-type` = \"ECS Task State Change\" | fields @message | sort @timestamp desc | dedup id
サービスレベルで条件を指定せずに「タスク状態変更イベント」を検索すると下記クエリが実行されました。
filter `detail-type` = \"ECS Task State Change\" | parse detail.group \"service:*\" as serviceName | filter serviceName = \"sample-ecs-app-7c89\" | fields @message | sort @timestamp desc | dedup id
サービスレベルだと、特に指定せずともサービス名に関する条件が適用されるようです。
一方で、クラスターレベルでもサービス条件を付与して検索することは可能です。
複数サービスが存在しており、クラスター内に存在するタスクの状態変化をまとめて確認したい場合はクラスターレベルのイベント履歴を使うと良いでしょう。
逆にそれ以外の場合は ECS サービス詳細ページの「イベント」タブが優秀なので、基本は ECS サービスレベルで利用すれば良いと思います。
ECS サービスが消えない限り直近 100 イベントが表示されるので、ECS サービス側のイベントはこちらで確認して、タスク側の状態変化は「イベント履歴」から確認すると捗りそうに感じました。
To ensure that this event view is helpful, we only show the 100 most recent events.
https://docs.aws.amazon.com/AmazonECS/latest/developerguide/service-event-messages.html
EventBridge ルールや CloudWatch ロググループを IaC で管理しながらイベント履歴クエリを利用するには？
ECS イベントキャプチャは便利ですが、専用 API が存在しないため IaC 経由で利用することはできません。
そこで、同等のリソースを IaC で定義した際にイベント履歴クエリだけ利用することはできるのか調査してみます。
イベントキャプチャを有効化していない ESC クラスターでイベント履歴タブを扱おうとすると、Log group '/aws/events/ecs/containerinsights/<クラスター名>/performance' does not exist for account ID 'xxxxxxxxxxxx' というエラーで怒られました。
ロググループがあれば利用できそうな雰囲気ですね。
というわけで、/aws/events/ecs/containerinsights/<クラスター名>/performance という命名で CloudWatch ロググループを作成します。
EventBridge ルールを作成して、ECS イベントを作成した CloudWatch ロググループに配信します。
作成完了後、無事タスク状態変更イベントクエリを利用できるようになりました！
IaC 管理している場合は下記を作成すれば、イベント履歴タブだけ利用できるようです。
- CloudWatch ロググループ
- ロググループ名は
/aws/events/ecs/containerinsights/<クラスター名>/performanceである必要あり
- ロググループ名は
- EventBridge ルール
- CloudWatch ログのリソースベースポリシー
認識させるためのタグ付け等も不要です。
「クエリを実行」をクリックすると決められたクエリが実行されるだけだが、logGroupName 属性がクラスター名から自動生成されるということですね。
最後に
ECS イベントキャプチャ、かなり便利ですね。
ECS イベントの保存や通知はセットアップが結構面倒なので積極的に使っていきたい所です。
あまりこのための EventBridge ルールなどを意識したく無いので、専用 API を生やして EventBridge ルールを管理してくれるともっと嬉しいなと思いました。
