Amazon ECS Action Logs を試す — デプロイ失敗の調査はどう変わるか

2026.07.31
Amazon ECS Action Logs を試す — デプロイ失敗の調査はどう変わるか
この記事をシェアする

2026年7月21日に発表された Amazon ECS の新機能 Action Logs を、東京リージョンの Fargate クラスターで実際に試しました。この記事では、コンソールと AWS CLI それぞれの有効化手順を確認します。さらにデプロイサーキットブレーカーによるロールバックを意図的に発生させ、Action Logs、従来のサービスイベント、Amazon Q による根本原因分析がそれぞれ何を見せてくれるのかを比較します。

この記事の要約

  • Action Logs は、サービスデプロイ時に ECS が裏側で行う操作をデプロイメント単位で記録する新機能。クラスター単位のオプトインで、追加の IAM 設定なしに有効化できる
  • サービスイベントが「タスクが起動した / 停止した」を流すのに対し、Action Logs は「デプロイ開始 / ロールバック / 成功」というライフサイクルを構造化 JSON で残す
  • サーキットブレーカー発動時は WARN レベルのログが記録され、コンソールの「Amazon Q で検査」ボタンから根本原因分析まで一気に進めた
  • 執筆時点(2026年7月30日)では AWS CLI のドキュメントに ECS 用の log-type が未記載だが、ACTION_LOGS を指定すれば CLI からも有効化できる

1. Amazon ECS Action Logs とは

Action Logs は、ECS がユーザーに代わって実行したアクションをタイムスタンプ付きで記録する可視化機能です(2026年7月21日発表)。対象はサービスデプロイと ECS Managed Daemon の更新です。

これまで ECS のデプロイで観察できたのは、DescribeServices が返すサービスイベント(最新100件のメッセージ)と、タスクの開始・終了状態くらいでした。デプロイの内部で ECS が何をしていたかはブラックボックスで、込み入った調査はサポートへの問い合わせや複数ソースの突き合わせが必要でした。Action Logs はこの間を埋める機能です。

主な仕様は次のとおりです。

  • クラスター単位でオプトイン(デフォルト無効)
  • 配信先は CloudWatch Logs / Amazon S3 / Amazon Data Firehose から選択
  • 各ログエントリはイベント名、ログレベル(INFO / WARN / ERROR)、リソース ARN、ステータス理由を含む構造化 JSON
  • 全リージョン対応(GovCloud 含む)
  • 機能自体は無料。配信先の標準料金(CloudWatch vended logs 料金)のみ発生

公式ドキュメントには「失敗タスクのメタデータを標準の1時間保持を超えて保持できる」という利点も明記されています。停止したタスクはコンソールでは1時間しか表示されないため(公式ドキュメントに明記)、これは後述するとおり夜間障害の調査などで効いてきます。

2. 検証の構成

使い捨ての最小構成で検証しました。コードはすべて AWS CLI + シェルスクリプトです。

項目内容
リージョンap-northeast-1(東京)
クラスターFargate、desired count 2 の nginx サービス
コンテナイメージpublic.ecr.aws/nginx/nginx:1.27(ECR・イメージビルド不要)
失敗の再現方法コマンド上書き sh -c "exit 1" で起動直後にクラッシュ
デプロイ設定ローリング更新 + サーキットブレーカー(rollback 有効)
Action Logs 配信先CloudWatch Logs

検証は 2026年7月23日〜30日に実施しました。発表直後の機能なので、記載内容は今後変わる可能性があります。

3. Action Logs を有効化する

3-1. コンソールから有効化する

クラスター詳細画面の「アクション」→「クラスターを更新」を開くと、「アクションログ」セクションが追加されています。「追加」を押すと配信先を3つから選べます。

アクションログセクションの追加メニュー。CloudWatch Logs / S3 / Data Firehose の3択

「Amazon CloudWatch Logs へ」を選ぶと配信設定のダイアログが開きます。

CloudWatch Logs への配信ダイアログ。ログタイプ ACTION_LOGS、配信先ロググループ、フィールド選択が並ぶ

このダイアログにはいくつか注目ポイントがあります。

  • ログタイプは ACTION_LOGS がプリセット済み
  • 配信先ロググループのデフォルト提案は /aws/vendedlogs/ecs/action-logs/<クラスター名>。/aws/vendedlogs/ プレフィックス付きなら自動作成される(それ以外のパスは事前作成が必要)
  • 「その他の設定」でログレコードに含めるフィールドを取捨選択できる。出力形式は JSON 固定
  • コンソール経由の場合、CloudWatch Logs の保持期間はデフォルト7日

1つ注意があります。このダイアログの「追加」を押した時点で配信設定は即座に作成されます。画面下部の「更新」ボタンを押す必要はありません。クラスター概要へ戻ると、アクションログ欄の表示が「オンになっています」へ変わります。

クラスター概要パネルのアクションログ欄が「オンになっています」へ変わった状態

3-2. CLI から有効化する

Action Logs 専用の ECS API はありません。実体は CloudWatch Logs の vended logs 配信です。delivery source、delivery destination、delivery の3つを aws logs コマンドで作れば完結します。

ACCOUNT_ID=$(aws sts get-caller-identity --query Account --output text)
REGION=ap-northeast-1
CLUSTER_NAME=action-logs-demo
LOG_GROUP=/aws/vendedlogs/ecs/action-logs/${CLUSTER_NAME}

# 1. ログを出す側(ECS クラスター)を delivery source として登録
aws logs put-delivery-source \
  --name ecs-action-logs-demo \
  --resource-arn "arn:aws:ecs:${REGION}:${ACCOUNT_ID}:cluster/${CLUSTER_NAME}" \
  --log-type ACTION_LOGS

# 2. 配信先ロググループを delivery destination として登録
aws logs put-delivery-destination \
  --name ecs-action-logs-demo-cwl \
  --delivery-destination-configuration \
    "destinationResourceArn=arn:aws:logs:${REGION}:${ACCOUNT_ID}:log-group:${LOG_GROUP}:*"

# 3. source と destination を紐付けて配信開始
aws logs create-delivery \
  --delivery-source-name ecs-action-logs-demo \
  --delivery-destination-arn "arn:aws:logs:${REGION}:${ACCOUNT_ID}:delivery-destination:ecs-action-logs-demo-cwl"
  • IAM ロールやリソースポリシーの手動設定は不要(vended logs の仕組みが権限まわりを処理してくれる)
  • 今回の検証ではロググループを事前に作成してから実行(CLI 経由で自動作成されるかは未確認)
  • create-delivery のレスポンスにある recordFields を見ると、配信されるログのフィールド構成が事前に分かる
  • コンソールで有効化すると delivery source が WdDeliverySource-751929393 のような自動生成名になる。名前を管理したいなら CLI からの有効化がおすすめ

なお、2026年7月30日時点では aws logs put-delivery-source help や API リファレンスの log-type 一覧に ECS 用の値が記載されていません。ただしサーバー側は対応済みで、わざと不正な値を投げるとエラーメッセージが正解を教えてくれました。

An error occurred (ValidationException) when calling the PutDeliverySource operation:
Provided LogType is not valid. Supported options are [ACTION_LOGS].

4. 正常デプロイで何が記録されるか

nginx サービスの作成と、タスク定義の更新(環境変数を1つ追加)による再デプロイを行い、Action Logs の中身を見てみます。ロググループにはサービス単位のログストリーム(service/action-logs-demo/web)が作られ、2回のデプロイで6件のイベントが記録されました。

時刻(UTC)Levelイベント名内容
02:30:40INFOSERVICE_DEPLOYMENT_IN_PROGRESSデプロイ1(サービス作成)開始
02:31:08INFOSERVICE_REVISION_STABLEリビジョン1のイメージ解決完了
02:32:31INFOSERVICE_DEPLOYMENT_IN_PROGRESSデプロイ2(更新)開始
02:32:31INFOSERVICE_DEPLOYMENT_STOPPEDデプロイ1が「Replaced by a new service deployment.」で終了
02:32:58INFOSERVICE_REVISION_STABLEリビジョン2のイメージ解決完了
02:35:23INFOSERVICE_DEPLOYMENT_SUCCESSFULデプロイ2完了

デプロイ1に SERVICE_DEPLOYMENT_SUCCESSFUL が無いのは、完了前にデプロイ2を重ねたためです。置き換えられた旧デプロイ側には SERVICE_DEPLOYMENT_STOPPED が記録されます。

実際のログエントリはこのような構造化 JSON です。

{
  "resourceArn": "arn:aws:ecs:ap-northeast-1:123456789012:cluster/action-logs-demo",
  "actionSourceId": "service/action-logs-demo/web",
  "logLevel": "INFO",
  "eventTimestamp": 1785378668343,
  "detail": {
    "statusReason": "Service revision marked stable. Locked to container image(s): public.ecr.aws/nginx/nginx:1.27@sha256:df80ece7fa07f8ed4f3b70e883fe322732954d0287e562f1fdc790018f7d2c66.",
    "serviceRevisionArn": "arn:aws:ecs:ap-northeast-1:123456789012:service-revision/action-logs-demo/web/9826453401691433676",
    "status": "SUCCEEDED",
    "eventName": "SERVICE_REVISION_STABLE"
  }
}

読み取れるポイントを整理します。

  • 各イベントが serviceDeploymentArn や serviceRevisionArn を持つため、複数のデプロイが絡んでも ARN でライフサイクルを追跡できる
  • SERVICE_REVISION_STABLE の statusReason には、イメージタグをダイジェストへ解決して固定した記録が残る。「同じ latest タグなのに中身が変わっていた」という事故の調査で、当時のイメージ実体を後から確認できるのは地味に便利
  • SERVICE_REVISION_STABLE(02:32:58)から SERVICE_DEPLOYMENT_SUCCESSFUL(02:35:23)まで約2.5分の差がある。新リビジョンが安定しても、旧タスクのドレインが完了するまでデプロイ成功にはならない

紛らわしいのは SERVICE_REVISION_STABLE の意味です。この「stable」は「リビジョンのイメージ解決が完了して内容が固定された」という意味で、デプロイが健全に完了したという意味ではありません。後述する失敗デプロイでも、このイベントは普通に記録されます。

なお公式ドキュメントには、ロードバランサー登録やセキュリティグループ設定なども記録対象として挙げられています。ELB を使わない今回の最小構成で観測できたのは、上記のデプロイライフサイクルのイベントのみでした。

コンソールでの確認場所は、サービス詳細の「アクションログ」タブです。テキストやログタイプ、時間範囲でフィルタでき、「CloudWatch で表示」から CloudWatch Logs 側にも飛べます。

サービス詳細のアクションログタブ。Service deployment successful などのエントリが時系列で並ぶ

5. 失敗デプロイで何が記録されるか

起動直後に exit 1 するタスク定義(イメージは正常時と同じ nginx:1.27、コマンドだけ上書き)をデプロイし、サーキットブレーカーによる自動ロールバックを発生させました。

結果として、デプロイ開始からロールバック完了・サービス安定まで約4分で完結しました。Action Logs には8件のイベントが記録されています。

時刻(UTC)Levelイベント名内容
02:40:06INFOSERVICE_DEPLOYMENT_IN_PROGRESS失敗するデプロイの開始
02:40:38INFOSERVICE_REVISION_STABLE壊れたリビジョンのイメージ解決完了(前述のとおり健全性の意味ではない)
02:42:11WARN ×3SERVICE_DEPLOYMENT_ROLLBACKサーキットブレーカー発動、ロールバック開始
02:42:27WARN ×2SERVICE_DEPLOYMENT_ROLLBACK(同一デプロイメント ARN で計5件記録された)
02:42:27INFOSERVICE_DEPLOYMENT_ROLLBACK_SUCCESSFULロールバック完了

statusReason は5件とも同一で、サーキットブレーカーのしきい値超過によるロールバックを示す文言でした。**ポイントは、ロールバックが WARN レベルで記録されることです。**ログレベルのフィルタやメトリクスフィルタを仕込めば、ロールバック検知の仕組みが簡単に作れます。

なお SERVICE_DEPLOYMENT_ROLLBACK が同一 ARN で5件記録された理由はドキュメントに記載が見つからず、観察事実としてそのまま書いておきます。またロールバック後のログの終端は ROLLBACK_SUCCESSFUL で、サービスイベント側にある「安定した」に対応するエントリはありませんでした。

コンソールのアクションログタブでは WARN エントリに警告アイコンが付き、「Amazon Q で検査」ボタンが現れます(Amazon Q については後述します)。導線はこのタブだけではありません。サービス詳細のデプロイタブにも「サーキットブレーカーのしきい値を超えたため、サービスデプロイがロールバックされました」という警告バナーと「アクションログを表示」ボタンが出ます。サービス概要の「デプロイのステータス」も「ロールバックが成功」表示に変わるため、異常に気づいてからログまでの距離が近いです。

アクションログタブに WARN アイコン付きの Service deployment rollback エントリと Amazon Q で検査ボタンが表示される

サーキットブレーカーの発動タイミング

60秒間隔で describe-services をポーリングして観察したところ、failedTasks カウンタが3に達した時点でデプロイが FAILED になり、ロールバックが始まりました。起動を試みたタスクは5個です。

このしきい値3は公式ドキュメントの計算式どおりです。デフォルトでは「50% × desired count を最小3・最大200にクランプ」で、今回は desired 2 なので 0.5 × 2 = 1 → 最小値の3が適用されます。以前はこの最小値が10だったので、「失敗デプロイは10タスク失敗するまでロールバックされない」という古い知識をお持ちの方は要注意です。現在は thresholdConfiguration で固定値や割合のカスタマイズもできるようになっています。

6. 従来のサービスイベントとの比較

同じ失敗デプロイを、従来の DescribeServices のサービスイベントでも記録しました。並べてみます。

02:40:16〜02:41:56  (service web) has started 1 tasks ×5
02:42:11  (service web) (deployment ecs-svc/1213738142338680241) deployment failed: tasks failed to start.
02:42:11  (service web) rolling back to deployment ecs-svc/6449186025545241833.
02:42:17  (service web) stopped 1 pending tasks.
02:44:00  (service web) (deployment ecs-svc/...) deployment completed.
02:44:00  (service web) has reached a steady state.
サービス詳細のイベントタブ。deployment failed や rolling back のメッセージが時系列で並ぶ

「デプロイが失敗してロールバックした」という事実自体はサービスイベントでも分かります。今回のようなシンプルなケースでは、情報の差は思ったより小さいです。それでも Action Logs に優位性があるのは次の4点です。

観点サービスイベントAction Logs
情報の軸タスク単位の増減(started / stopped)デプロイ単位のライフサイクル(開始 / 成功 / ロールバック)
形式英文メッセージ(プレーンテキスト)構造化 JSON(ARN・ステータス・レベル付き)
重要度の判別なしINFO / WARN / ERROR でフィルタ可能
保存最新100件・ECS 内のみCloudWatch Logs 等に永続化(保持期間は自由)
後段の活用都度 API で取得メトリクスフィルタ、Logs Insights、Amazon Q 連携

特に「保存」の差は運用で効きます。サービスイベントは流れて消えますし、停止タスクの詳細(exit code や stoppedReason)もコンソールでは1時間で表示されなくなります。夜間にサーキットブレーカーが発動して朝に調査する場合、従来はもう消えた情報を EventBridge などで別途収集しておく必要がありました。Action Logs なら WARN ログがロググループに残っています。

一方で限界も明確です。タスク個々の失敗理由(exit code など)は、Action Logs とサービスイベントのどちらにも出ません。今回の検証では describe-tasks で停止タスクを見て初めて stopCode: EssentialContainerExited, exitCode: 1 が分かりました。Action Logs は調査の起点であって、停止タスクの describe やアプリケーションログの代替ではありません。

7. Amazon Q でロールバックを分析する

アクションログタブの WARN エントリに付く「Amazon Q で検査」ボタンを押すと、コンソール内で Amazon Q が調査を始めます。東京リージョン・日本語 UI で問題なく動作しました。

面白いのはこの調査がエージェント的に動くところです。ページのコンテキスト取得 → Action Logs の取得 → DescribeServices → CloudWatch メトリクスの確認、と自律的に API を呼びながら分析が進んでいきます。

数分待つと、根本原因分析レポートが出てきました。

Amazon Q の分析結果。設定変更によるクラッシュループが根本原因と結論づけている

分析の精度は予想以上でした。要点を抜粋します。

  • 3つのデプロイのタイムラインを Action Logs から再構成し、失敗したデプロイを特定
  • 「イメージダイジェストが3つのデプロイで同一 → イメージ起因ではなく設定変更が原因」と推論
  • CloudWatch メトリクス(CPU がほぼ0%、タスク数が細かく上下)から「起動直後のクラッシュループ」と判断
  • 原因候補ランキングの1位が「アプリケーションの起動時クラッシュ(設定不備、環境変数の欠落、entrypoint の失敗)」

今回の失敗はコマンド上書きによる exit 1 なので、実質的に正解に到達しています。「タスク定義のリビジョン比較と CloudWatch ログの確認」という次のアクションまで提示されました。

サーキットブレーカーのロールバックは、「発動したこと」は分かっても「なぜ失敗したか」の特定に手間がかかるトラブルの代表格です。WARN ログからワンクリックで根本原因分析まで進める導線は実務で使えると感じました。

8. 後片付け

検証リソースの削除で1点だけ注意があります。Action Logs の配信設定(delivery / delivery source / delivery destination)はクラスターを削除しても残るため、個別に削除が必要です。コンソール有効化の場合は自動生成名になっているので、クラスター ARN から逆引きすると確実です。

# クラスターを参照する delivery source を探して、delivery 一式を削除する
for SRC in $(aws logs describe-delivery-sources \
    --query "deliverySources[?service=='ecs' && contains(resourceArns[0], ':cluster/${CLUSTER_NAME}')].name" \
    --output text); do
  for DEL in $(aws logs describe-deliveries \
      --query "deliveries[?deliverySourceName=='${SRC}'].id" --output text); do
    aws logs delete-delivery --id "$DEL"
  done
  aws logs delete-delivery-source --name "$SRC"
done

さいごに

Amazon ECS Action Logs を有効化から失敗デプロイの分析まで一通り試しました。所感をまとめます。

  • 有効化は簡単。コンソールなら数クリック、CLI でも3コマンドで、IAM の設定は不要。既定の保持期間7日なら料金も軽微なので、デプロイ頻度の高いクラスターでは有効化しておいて損はない
  • 「デプロイ単位のライフサイクルが構造化ログで永続化される」点にいちばん価値がある。シンプルな失敗ならサービスイベントでも追えるが、ログレベルでのアラート設計や、時間が経ってからの調査は Action Logs でないとできない
  • Amazon Q との連携は実務で使える水準。WARN ログからワンクリックで、メトリクスまで横断した根本原因分析が返ってくる
  • 発表直後ならではの粗さもある。CLI ドキュメントへの log-type 未記載(2026年7月30日時点)や、同一イベントの重複記録などは今後の改善に期待

デプロイサーキットブレーカーのしきい値が最小3に変わっていた(以前は10)のは、検証していて気づいた副産物でした。実際に試すと発表文だけでは分からない挙動が見えてくるものですね。

手元で再現したい方は、記事中のコマンドを組み合わせれば同じ構成を作れます。使い捨て前提で試す場合は、最後に配信設定とロググループの削除も忘れずに実施してください。

この記事をシェアする
著者:みやっち
沖縄出身で仙台在住。2000年生まれの。趣味は野球、ゴルフ、サウナ。 2児のパパです。