Claude Code × AWS CloudWatch実践ガイド：ログ分析・メトリクス・アラームを運用に落とし込む

本番で障害が起きたときに一番つらいのは、ログがないことではありません。ログは大量にあるのに、どこを見ればよいかわからないことです。CloudWatchにはLogs、Metrics、Alarms、Dashboards、Logs Insightsがそろっていますが、設計せずに使うと「検索はできるが判断できない」状態になります。

この記事では、Claude CodeをAWS CloudWatch運用の相棒として使い、Lambda、ECS、API Gateway、ALB、RDSをまとめて観測する実装手順を紹介します。単なる設定一覧ではなく、構造化JSONログ、Logs Insightsクエリ、メトリックフィルター、CloudFormation/SAMのアラーム、ダッシュボード、IAM最小権限、インシデントレビュー用プロンプトまで、コピペして検証できる形にします。

用語も先にそろえます。構造化ログとは、文章ではなくJSONのような決まった形で出すログです。メトリクスとは、リクエスト数や5xx数のようにグラフ化できる数値です。アラームは、数値がしきい値を超えたときの通知ルールです。ランブックは、障害時に誰が何を確認するかを書いた手順書です。IAM最小権限は、Claude CodeやCIに必要なAWS操作だけを許可する考え方です。

全体像

flowchart LR
  App["Lambda / ECS / API Gateway"] --> Logs["CloudWatch Logs"]
  App --> Metrics["CloudWatch Metrics"]
  Logs --> Insights["Logs Insights queries"]
  Logs --> Filter["Metric filters"]
  Metrics --> Alarms["CloudWatch Alarms"]
  Metrics --> Dash["Dashboards"]
  Insights --> Claude["Claude Code incident review"]
  Alarms --> Runbook["SNS / PagerDuty / runbook"]

Claude Codeに任せるのは「AWSを魔法のように直すこと」ではありません。ログ形式、調査観点、アラーム条件、ダッシュボードの目的を文章で渡し、CLIやIaCに落とす作業を速くすることです。判断の責任は運用者に残し、繰り返し作業を減らします。

使いどころ3例

1つ目はLambdaのバッチ失敗です。REPORT行だけでは原因が見えないので、ジョブID、外部API名、リトライ回数、例外名をJSONログに入れます。Claude Codeには直近2時間のエラーを読ませ、失敗が特定取引先、特定時間帯、特定デプロイ後に偏っているかを要約させます。

2つ目はECS APIの5xx増加です。ALBのHTTPCode_Target_5XX_Countだけを見ると「増えた」ことしかわかりません。CloudWatch Logs Insightsでendpoint、status_code、duration_msを集計し、Claude Codeに「5xxの多い順、遅い順、直前のデプロイとの差分」を出させます。

3つ目はAPI Gatewayの体感遅延です。LatencyとIntegrationLatencyを分けて見ると、API Gateway側の待ち時間なのか、LambdaやECS側の処理時間なのかを切り分けられます。ダッシュボードにP95/P99を置き、アラームは平均ではなく高パーセンタイルで検討します。

4つ目はアラーム疲れの解消です。WarningとCriticalを分け、夜間はCriticalだけ通知する、同じ原因のアラームを複合アラームにまとめる、treatMissingDataを明示する、といった調整をClaude Codeにレビューさせます。

構造化JSONログを出す

まずログを読める形にします。次のNode.jsロガーはLambdaでもECSでも動きます。requestId、service、route、durationMs、statusCodeを常に同じキーで出すのがポイントです。

// logger.mjs
export function logEvent(level, message, fields = {}) {
  const entry = {
    timestamp: new Date().toISOString(),
    level,
    message,
    service: process.env.SERVICE_NAME || "checkout-api",
    env: process.env.NODE_ENV || "development",
    requestId: fields.requestId || "unknown",
    route: fields.route,
    statusCode: fields.statusCode,
    durationMs: fields.durationMs,
    userId: fields.userId,
    errorName: fields.error?.name,
    errorMessage: fields.error?.message,
  };

  console.log(JSON.stringify(entry));
}

logEvent("ERROR", "payment authorization failed", {
  requestId: "req-123",
  route: "POST /checkout",
  statusCode: 502,
  durationMs: 842,
  userId: "user-456",
  error: new Error("upstream timeout"),
});

ローカル確認は以下でできます。

node logger.mjs | jq .

ログにカード番号、メールアドレス、アクセストークンをそのまま出してはいけません。CloudWatch Logsにはデータ保護機能もありますが、まずアプリ側でPIIを出さない設計にします。

Logs Insightsクエリを運用テンプレート化する

CloudWatch Logs Insightsは、ログをSQLに近い感覚で検索する機能です。Claude Codeには「何を知りたいか」とログ形式を渡すと、初期クエリを作らせやすくなります。

claude -p "
CloudWatch Logs Insightsのクエリを作ってください。
ログはJSONで、フィールドは timestamp, level, message, service, route, statusCode, durationMs, requestId, userId です。
目的:
1. 直近1時間のroute別5xx件数トップ10
2. P95レイテンシが高いroute
3. requestIdを指定した時系列追跡
4. デプロイ後30分だけで増えたエラー名
出力はクエリだけ。各クエリに短い用途コメントを付けてください。
"

実際に使うクエリ例です。

-- route別5xx件数
fields @timestamp, route, statusCode, requestId
| filter statusCode >= 500
| stats count(*) as errors by route
| sort errors desc
| limit 10

-- route別P95レイテンシ
fields route, durationMs
| filter ispresent(durationMs)
| stats pct(durationMs, 95) as p95, count(*) as requests by route
| sort p95 desc
| limit 20

-- requestIdで時系列追跡
fields @timestamp, level, message, route, statusCode, durationMs
| filter requestId = "req-123"
| sort @timestamp asc

-- エラー名の増加
fields @timestamp, errorName, route
| filter level = "ERROR" and ispresent(errorName)
| stats count(*) as count by errorName, route
| sort count desc
| limit 20

コスト面の落とし穴は、時間範囲を広げすぎることです。Logs Insightsはスキャン量に応じて課金されます。調査時は必ず時間範囲を狭め、ロググループも必要なものだけ選びます。

メトリックフィルターとSAMアラームを作る

ログから「決済失敗数」のようなビジネス指標を作るには、メトリックフィルターが便利です。以下はCloudFormation/SAMテンプレートに入れられる例です。

Resources:
  CheckoutLogGroup:
    Type: AWS::Logs::LogGroup
    Properties:
      LogGroupName: /aws/lambda/checkout-api
      RetentionInDays: 30

  PaymentFailureMetricFilter:
    Type: AWS::Logs::MetricFilter
    Properties:
      LogGroupName: !Ref CheckoutLogGroup
      FilterPattern: '{ $.level = "ERROR" && $.message = "payment authorization failed" }'
      MetricTransformations:
        - MetricNamespace: MyApp/Business
          MetricName: PaymentFailure
          MetricValue: "1"
          DefaultValue: 0

  PaymentFailureAlarm:
    Type: AWS::CloudWatch::Alarm
    Properties:
      AlarmName: prod-payment-failure-critical
      AlarmDescription: 決済失敗が10分で5件以上発生
      Namespace: MyApp/Business
      MetricName: PaymentFailure
      Statistic: Sum
      Period: 300
      EvaluationPeriods: 2
      DatapointsToAlarm: 2
      Threshold: 5
      ComparisonOperator: GreaterThanOrEqualToThreshold
      TreatMissingData: notBreaching
      AlarmActions:
        - arn:aws:sns:ap-northeast-1:123456789012:prod-alerts

EvaluationPeriodsは何回連続で見るか、DatapointsToAlarmはそのうち何回しきい値を超えたら鳴らすかです。1回だけで鳴らすと一瞬のスパイクで通知が増えます。逆に長くしすぎると検知が遅れます。本番APIなら「5分×2回」、バッチなら「15分×1回」など、業務影響に合わせます。

ダッシュボードをJSONで管理する

ダッシュボードはコンソールで手作業すると属人化します。まずJSONで1枚作り、Claude Codeに「Lambda、ECS、API Gateway、ALBの行を追加して」と依頼すると拡張しやすくなります。

{
  "widgets": [
    {
      "type": "metric",
      "x": 0,
      "y": 0,
      "width": 12,
      "height": 6,
      "properties": {
        "region": "ap-northeast-1",
        "title": "API health: requests, 5xx, latency",
        "view": "timeSeries",
        "stacked": false,
        "metrics": [
          ["AWS/ApplicationELB", "RequestCount", "LoadBalancer", "app/myapp/abc", { "stat": "Sum" }],
          [".", "HTTPCode_Target_5XX_Count", ".", ".", { "stat": "Sum", "yAxis": "right" }],
          ["AWS/ApiGateway", "Latency", "ApiName", "checkout-api", "Stage", "prod", { "stat": "p95" }]
        ],
        "period": 60
      }
    }
  ]
}

反映例です。

aws cloudwatch put-dashboard \
  --dashboard-name myapp-production \
  --dashboard-body file://dashboard.json

Claude Code用インシデントレビュー・プロンプト

調査時は、Claude CodeにAWS CLIを無制限に実行させるのではなく、読み取り系コマンドと対象ロググループを明示します。

claude -p "
本番インシデントをレビューしてください。推測と事実を分けて書いてください。

対象:
- log group: /aws/lambda/checkout-api, /ecs/checkout-api
- window: 2026-06-02T10:00:00+09:00 から 2026-06-02T11:00:00+09:00
- 直前の変更: checkout-api v1.42.0 deploy

実行してよい読み取りコマンド:
- aws logs start-query / get-query-results
- aws cloudwatch get-metric-data
- aws cloudwatch describe-alarms

出力:
1. タイムライン
2. 影響範囲
3. 根本原因の仮説トップ3
4. すぐ戻すべき変更
5. 再発防止アクション
6. 追加すべきアラームとダッシュボード
"

IAMは読み取りに絞ります。必要になってからPutMetricAlarmやPutDashboardを別ロールで許可します。

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "logs:StartQuery",
        "logs:GetQueryResults",
        "logs:FilterLogEvents",
        "cloudwatch:GetMetricData",
        "cloudwatch:DescribeAlarms",
        "cloudwatch:GetDashboard"
      ],
      "Resource": "*"
    }
  ]
}

失敗例と落とし穴

アラーム疲れは最もよくある失敗です。CPU 70%で毎晩通知するより、5xx、P95レイテンシ、キュー滞留、決済失敗のようにユーザー影響に近いメトリクスを優先します。WarningはSlack、CriticalはPagerDutyのように経路を分けます。

ログ保持期間の未設定も危険です。Lambdaのロググループを無期限にすると、検証環境のログまで積み上がります。まず30日、監査が必要なものだけ長期保持にします。

高カーディナリティのメトリクスにも注意します。userIdやrequestIdをCloudWatchメトリクスのディメンションにすると、系列数が爆発して費用と見通しが悪化します。詳細追跡はログ、集計はメトリクスに分けます。

Claude Codeにログを貼りすぎるのも失敗です。必要な時間窓、ロググループ、クエリ結果だけに絞ります。機密情報が混じる場合は、貼る前にマスクします。

次にやること

まず1つの重要APIを選び、JSONログ、5xxクエリ、P95クエリ、Criticalアラーム、ダッシュボード1枚を作ってください。そのうえで、Claude Code × AWS ECS/FargateガイドやClaude Code × AWS IAMガイドと合わせて、デプロイ、権限、監視をつなげると運用が安定します。

実運用に入れる前に、ランブックも1ページだけ作っておきます。アラーム名、確認するDashboard、最初に実行するLogs Insightsクエリ、切り戻し判断の基準、連絡先を並べるだけで十分です。Claude Codeには「このアラームが鳴ったら、5分以内に確認すべき事実だけをチェックリスト化して」と依頼すると、夜間対応でも迷いにくい手順になります。

この記事の内容を試した結果、ローカルではlogger.mjsのJSON出力をjqで確認し、SAMテンプレート断片は既存のCloudFormation構文に合わせてリソース名とARNを置き換えれば使えることを確認しました。実AWS環境では、必ず検証用アカウントでログ量、アラームしきい値、通知先を調整してから本番に入れてください。

公式ドキュメント

• Amazon CloudWatch Logs
• CloudWatch Logs Insights query syntax
• Using Amazon CloudWatch alarms
• Using Amazon CloudWatch dashboards
• Identity and access management for Amazon CloudWatch