Claude Code × AWS CloudWatch 实战：日志、指标、告警、仪表盘与事故复盘

生产故障最麻烦的往往不是“没有日志”，而是日志太多、字段不统一、告警太吵，值班同学不知道先看哪里。AWS CloudWatch 提供 Logs、Metrics、Alarms、Dashboards 和 Logs Insights，但如果没有设计，最后只会变成一个很大的搜索框。

这篇文章介绍如何用 Claude Code 把 CloudWatch 监控做成可执行流程：Lambda、ECS、API Gateway、ALB 的结构化 JSON 日志，Logs Insights 查询，Metric Filter，CloudFormation/SAM 告警，Dashboard JSON，IAM 最小权限，以及事故复盘提示词。这里的目标不是让 AI 自动改生产，而是让它帮你更快生成和审查 IaC、查询语句和排障清单。

先解释几个词。结构化日志就是用固定字段输出的 JSON 日志。指标是请求数、5xx 数、P95 延迟这类可以画成时间序列的数字。告警是指标超过阈值后的通知规则。Runbook 是事故发生时按步骤执行的操作手册。最小权限是只给 Claude Code 或 CI 需要的读取权限，不默认开放写权限。

整体架构

flowchart LR
  App["Lambda / ECS / API Gateway"] --> Logs["CloudWatch Logs"]
  App --> Metrics["CloudWatch Metrics"]
  Logs --> Insights["Logs Insights 查询"]
  Logs --> Filter["Metric filters"]
  Metrics --> Alarms["CloudWatch Alarms"]
  Metrics --> Dash["Dashboards"]
  Insights --> Claude["Claude Code 事故复盘"]
  Alarms --> Runbook["SNS / PagerDuty / runbook"]

Claude Code 最适合处理明确输入：日志格式、时间范围、服务名称、告警意图和允许执行的命令。它可以生成查询和配置，但是否上线仍应由工程师评审。

真实使用场景

第一个场景是 Lambda 批处理失败。只看 REPORT 行无法定位业务原因，所以要把 jobId、外部接口名、重试次数、异常名写入 JSON 日志。然后让 Claude Code 总结最近两小时的失败是否集中在某个供应商、某个部署版本或某个输入类型。

第二个场景是 ECS API 的 5xx 上升。ALB 的 HTTPCode_Target_5XX_Count 只能说明目标返回了错误。配合 Logs Insights 按 route、statusCode、durationMs 聚合后，Claude Code 可以列出最吵的接口、最慢的 P95 接口，以及部署后才出现的新错误。

第三个场景是 API Gateway 延迟。把 Latency 和 IntegrationLatency 分开看，可以判断问题在网关、授权器，还是后端 Lambda/ECS。仪表盘上应放 P95/P99，而不是只看平均值。

第四个场景是告警疲劳。Warning 发到 Slack，Critical 才进 PagerDuty；同一根因引起的多个告警可以用 Composite Alarm 降噪；TreatMissingData 必须显式设置。

输出结构化 JSON 日志

下面的 Node.js 例子可以在 Lambda 或 ECS 中使用。关键是字段名稳定，方便 Logs Insights 查询。

// 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 有数据保护能力，但更好的做法是在应用层就避免输出敏感信息。

让 Claude Code 生成 Logs Insights 查询

不要只说“帮我写 CloudWatch 查询”。把日志 schema 和分析目的说清楚。

claude -p "
请生成 CloudWatch Logs Insights 查询。
日志是 JSON，字段包括 timestamp, level, message, service, route, statusCode, durationMs, requestId, userId。
目标:
1. 最近1小时 route 维度 5xx 数量 Top 10
2. P95 延迟最高的 route
3. 按 requestId 追踪完整时间线
4. 部署后增加的 errorName
只输出查询，并为每段查询加一句用途注释。
"

可直接使用的查询如下：

-- 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 按扫描数据量计费，排障时要缩小时间窗口，只选择必要的 log group。

Metric Filter 与 SAM 告警

业务错误可以从日志转成指标。下面的 CloudFormation/SAM 片段会创建日志组、Metric Filter 和告警。

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: Ten minutes with five or more payment failures
      Namespace: MyApp/Business
      MetricName: PaymentFailure
      Statistic: Sum
      Period: 300
      EvaluationPeriods: 2
      DatapointsToAlarm: 2
      Threshold: 5
      ComparisonOperator: GreaterThanOrEqualToThreshold
      TreatMissingData: notBreaching
      AlarmActions:
        - arn:aws:sns:ap-southeast-1:123456789012:prod-alerts

EvaluationPeriods 表示评估几个周期，DatapointsToAlarm 表示其中几个周期超过阈值才告警。一个周期太容易误报，周期太多又会发现太晚。

用 JSON 管理 Dashboard

仪表盘不要只在控制台手工点。先把 JSON 放进仓库，再让 Claude Code 增加 Lambda、ECS、API Gateway、ALB 和业务指标行。

{
  "widgets": [
    {
      "type": "metric",
      "x": 0,
      "y": 0,
      "width": 12,
      "height": 6,
      "properties": {
        "region": "ap-southeast-1",
        "title": "API health: requests, 5xx, latency",
        "view": "timeSeries",
        "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

事故复盘提示词与 IAM

排障时要限制范围和命令。

claude -p "
请复盘生产事故，明确区分事实和假设。
范围:
- log groups: /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
输出: 时间线、影响范围、根因假设Top3、立即缓解、预防措施、缺失告警。
"

建议先使用只读 IAM：

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

常见坑

告警疲劳是第一大坑。不要让 CPU 小波动直接叫醒人，优先选择 5xx、P95 延迟、队列积压、支付失败等更接近用户影响的指标。

日志保留期是第二大坑。Lambda 和 ECS log group 如果无限保留，测试环境也会持续产生费用。默认先设 30 天，需要审计的日志再单独延长。

高基数指标也很危险。不要把 userId 和 requestId 放进 metric dimension。细节放日志，聚合放指标。

最后，不要把大量原始日志直接贴给 Claude Code。先查询、缩小时间范围、脱敏，再要求它给出有证据的结论。

下一步

先选一个关键 API，落地 JSON 日志、5xx 查询、P95 查询、一个 Critical 告警和一行仪表盘。然后结合 Claude Code × AWS ECS/Fargate 指南 与 Claude Code × AWS IAM 指南 把部署、权限、监控串起来。

本文的动手验证：我用 jq 检查了 Node logger 的 JSON 输出；SAM 片段按标准 CloudFormation 结构编写，替换 log group、区域、账号和 SNS ARN 后可放入现有模板。正式告警前请先在测试账号中调阈值。

官方资料

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