Claude Code × AWS CloudWatch: log, metrik, alarm, dashboard, dan review insiden

Dalam insiden produksi, masalahnya tidak selalu karena log tidak ada. Sering kali log terlalu banyak, field tidak konsisten, alarm terlalu berisik, dan tim tidak punya jalur jelas dari gejala ke keputusan. AWS CloudWatch menyediakan Logs, Metrics, Alarms, Dashboards, dan Logs Insights, tetapi semua itu baru berguna jika aplikasi mengirim data terstruktur dan tim memiliki query serta runbook yang bisa diulang.

Panduan ini menunjukkan cara memakai Claude Code untuk membuat workflow observability CloudWatch yang praktis untuk Lambda, ECS, API Gateway, ALB, dan metrik bisnis. Tujuannya bukan membiarkan agent mengubah produksi tanpa kontrol. Tujuannya adalah mempercepat bagian yang repetitif: format log JSON, query Logs Insights, metric filter, alarm CloudFormation/SAM, widget dashboard, IAM read-only, dan prompt review insiden.

Istilah sederhana: log terstruktur adalah log dengan field stabil, biasanya JSON. Metrik adalah angka yang bisa digrafikkan, seperti jumlah request, 5xx, atau latensi p95. Alarm adalah aturan threshold pada metrik. Runbook adalah checklist respons insiden. Least privilege berarti Claude Code hanya mendapat izin yang diperlukan, dimulai dari akses baca.

Arsitektur

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

Claude Code bekerja paling baik ketika inputnya jelas: format log, rentang waktu, nama service, tujuan alarm, dan command yang boleh dijalankan.

Use case nyata

Pertama, batch Lambda gagal. Baris REPORT tidak cukup untuk mencari akar masalah bisnis. Tambahkan jobId, nama API eksternal, jumlah retry, dan nama exception ke log JSON. Setelah itu minta Claude Code memeriksa apakah kegagalan dua jam terakhir terkait satu partner, satu versi deploy, atau satu jenis input.

Kedua, 5xx pada API ECS meningkat. Metrik ALB HTTPCode_Target_5XX_Count hanya memberi tahu bahwa target error. Dengan Logs Insights yang mengelompokkan route, statusCode, dan durationMs, Claude Code bisa merangkum route paling bermasalah, p95 tertinggi, dan error baru setelah deploy.

Ketiga, latensi API Gateway. Bandingkan Latency dan IntegrationLatency untuk membedakan masalah di gateway, authorizer, atau backend Lambda/ECS. Dashboard sebaiknya menampilkan p95 dan p99, bukan hanya rata-rata.

Keempat, alarm fatigue. Warning bisa masuk Slack, Critical bisa masuk PagerDuty. Beberapa alarm dengan akar masalah sama bisa dikurangi dengan composite alarm. TreatMissingData harus ditentukan secara eksplisit.

Log JSON terstruktur

Logger Node.js ini bisa dipakai di Lambda maupun ECS. Kuncinya adalah field yang konsisten.

// 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"),
});

Uji lokal:

node logger.mjs | jq .

Jangan log nomor kartu, token, atau email mentah. CloudWatch Logs punya fitur perlindungan data, tetapi desain terbaik adalah tidak mengirim nilai sensitif sejak awal.

Query Logs Insights

Berikan schema log dan pertanyaan operasional kepada Claude Code.

claude -p "
Buat query CloudWatch Logs Insights.
Log berbentuk JSON dengan field timestamp, level, message, service, route, statusCode, durationMs, requestId, userId.
Saya butuh:
1. Top 10 route berdasarkan 5xx dalam 1 jam terakhir
2. Route dengan latensi p95 tertinggi
3. Timeline untuk satu requestId
4. errorName yang naik setelah deploy
Kembalikan query saja dengan komentar singkat.
"

Starter query:

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

-- p95 latency per route
fields route, durationMs
| filter ispresent(durationMs)
| stats pct(durationMs, 95) as p95, count(*) as requests by route
| sort p95 desc
| limit 20

-- timeline requestId
fields @timestamp, level, message, route, statusCode, durationMs
| filter requestId = "req-123"
| sort @timestamp asc

-- nama error
fields @timestamp, errorName, route
| filter level = "ERROR" and ispresent(errorName)
| stats count(*) as count by errorName, route
| sort count desc
| limit 20

Jebakan biaya terbesar adalah scan data terlalu luas. Batasi waktu dan pilih hanya log group yang diperlukan.

Metric Filter dan alarm SAM

Gunakan Metric Filter ketika event log perlu menjadi metrik.

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: Five or more payment failures in ten minutes
      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 menentukan berapa periode yang dievaluasi. DatapointsToAlarm menentukan berapa periode yang harus melewati threshold.

Dashboard sebagai JSON

Dashboard yang dibuat manual di console sulit direplikasi.

{
  "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

Prompt review insiden dan IAM

Batasi scope dan command.

claude -p "
Review insiden produksi ini. Pisahkan fakta dan hipotesis.
Scope:
- log groups: /aws/lambda/checkout-api, /ecs/checkout-api
- window: 2026-06-02T10:00:00+09:00 to 2026-06-02T11:00:00+09:00
- recent change: checkout-api v1.42.0 deploy
Command read-only yang boleh:
- aws logs start-query / get-query-results
- aws cloudwatch get-metric-data
- aws cloudwatch describe-alarms
Output: timeline, dampak, top 3 hipotesis, mitigasi segera, pencegahan, alarm yang kurang.
"

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

Jebakan umum

Alarm fatigue muncul saat setiap gejala teknis membangunkan orang. Prioritaskan metrik dekat pengguna: 5xx, p95, queue backlog, checkout failure, dan job gagal.

Retensi log tanpa batas menjadi biaya diam-diam. Atur retensi Lambda dan ECS, lalu perpanjang hanya untuk log yang wajib audit.

Metrik high-cardinality mahal. Jangan gunakan userId atau requestId sebagai dimension. Detail tetap di log, agregasi di metrik.

Jangan tempel log mentah terlalu banyak ke Claude Code. Query dulu, persempit waktu, mask data sensitif, lalu minta kesimpulan berbasis bukti.

Langkah berikutnya

Pilih satu API kritis dan terapkan lima hal: log JSON, query 5xx, query p95, satu alarm Critical, dan satu baris dashboard. Setelah itu hubungkan dengan Claude Code × AWS ECS/Fargate dan Claude Code × AWS IAM.

Verifikasi praktik: output logger diuji lokal dengan jq, dan potongan SAM disusun agar bisa dipasang ke template setelah mengganti nama, region, account, dan ARN SNS. Kalibrasi threshold di akun test sebelum menghubungi responder sungguhan.

Referensi resmi

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