Datadog을 Claude Code에 연결하고 첫 증거자료를 수집하기

AI 장애 분석 포스트모템 시리즈 2/9

Datadog API Key와 Application Key를 환경변수에 붙였습니다. /api/v1/validate는 바로 200을 돌려줬습니다. 인증 자체는 성공이었습니다.

하지만 같은 key로 metric query를 던졌을 때 답이 달랐습니다.

GET /api/v1/query               -> 403
POST /api/v2/query/timeseries   -> 403
GET /api/v1/hosts               -> 403

APM trace search와 logs search, events, monitors는 열려 있었습니다. metric timeseries와 host inventory는 막혀 있었습니다.

인증 성공은 분석 가능이 아니었습니다

이 상태에서도 AI에게 조사를 시킬 수는 있었습니다. 다만 trace와 log 안에서 그럴듯한 결론이 나올 수 있었습니다. /heartbeat 30초 span에 끌려 DB pool이나 GC를 원인으로 못박을 가능성이 컸습니다.

문제는 그 결론을 반박할 수 있는 metric을 조회할 수 없었다는 점이었습니다. major GC count가 0이었는지, request count가 언제부터 튀었는지, host 단위 CPU가 어땠는지를 볼 수 없으면 Old Gen 증가는 원인 후보인 채로 남습니다. 증거 없는 결론을 만들 수 있는 상태와 검증 가능한 상태는 달랐습니다.

처음 만든 Application Key와 실제 필요한 scope

처음 만든 Application Key는 spans, logs, events 조회는 됐지만 metric query와 host 조회에서 403이 났습니다. 최종적으로 열어둔 read-only scope는 아래와 같습니다.

apm_read
dashboards_read
error_tracking_read
events_read
hosts_read
logs_read_data
metrics_read
monitors_read
timeseries_query

각 scope의 용도는 다음과 같습니다.

Scope	용도
apm_read	APM trace/span 조회
logs_read_data	애플리케이션 로그 조회
metrics_read	metric metadata와 metric 조회
timeseries_query	JVM/CPU/request count 같은 시계열 조회
hosts_read	host 또는 task inventory 조회
events_read	deploy, ECS, Watchdog, system event 조회
monitors_read	monitor 상태 조회
dashboards_read	기존 dashboard 구성 확인
error_tracking_read	error grouping과 추세 확인

반대로 아래 계열은 장애 분석용 read key에 넣지 않았습니다.

api_keys_read
application_keys_read
*_write
*_manage
*_delete
*_publish
*_settings_write

api_keys_read는 이름에 read가 들어가지만 조직의 API key 값을 볼 수 있는 권한이라 제외했습니다. scope를 보완한 뒤 metric query와 hosts API는 200으로 바뀌었습니다. 다만 Fargate 서비스는 Datadog host inventory에 일반 host로 나타나지 않아 task tag 기준으로 봐야 했습니다.

이 차이도 미리 한 번 호출해보지 않았으면 조사 중에 다시 막혔을 지점입니다.

MCP는 붙이는 부담을 줄여줬지, 검증을 대신하지는 않았습니다

Cursor에서 Datadog MCP를 이메일 인증으로 붙여봤습니다. API Key와 Application Key를 직접 다루지 않아도 됐습니다. 붙는 건 빨랐습니다.

다만 붙었다는 화면이 그대로 분석 가능한 상태를 보장하지는 않았습니다. MCP로 붙였을 때도 아래는 다시 확인했습니다.

• APM span search가 되는가
• log search가 되는가
• metric timeseries가 되는가
• JVM metric을 볼 수 있는가
• ECS/Fargate task 단위 tag를 볼 수 있는가
• 비용 분석에 필요한 사용량 신호를 볼 수 있는가

Cursor 쪽에서는 여기에 확장이 하나 붙었습니다. RDS와 ECS Fargate 사용량을 비용 관점으로 정리해달라고 하자 Datadog에서 조회한 운영 데이터를 근거로 보고서 형식 문서가 바로 나왔습니다. 같은 연결 방식이 장애 RCA와 비용 리포트 양쪽으로 확장될 수 있다는 걸 그때 확인했습니다.

AWS와 GitLab도 미리 호출해봤습니다

AWS는 CloudWatch, RDS, X-Ray, ECS/EC2 read-only를 조합했습니다. profile 이름과 region을 먼저 정한 뒤 조사에 들어갔습니다.

aws sts get-caller-identity --profile readonly-prod
aws cloudwatch list-metrics --namespace AWS/RDS --profile readonly-prod

GitLab은 Repository, Merge requests, Pipelines, Deployments read 정도를 붙였습니다. 배포가 GitLab Pipeline인지 별도 CD 도구인지, production deployment event가 GitLab에 남는지를 먼저 확인했습니다.

curl -s --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
  "$GITLAB_URL/api/v4/projects/$GITLAB_PROJECT_ID/deployments?per_page=20"

curl -s --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
  "$GITLAB_URL/api/v4/projects/$GITLAB_PROJECT_ID/merge_requests?state=merged&per_page=20"

인증만 확인하지 않고 실제로 조회할 API를 한 번씩 던져봤습니다. 이 단계에서 막히는 자리를 미리 발견하는 편이 조사 중에 발견하는 것보다 비용이 낮았습니다.

조사 조건은 고정해서 넣었습니다

권한이 열린 뒤에도 AI에게 매번 다른 지시를 주지 않았습니다. 같은 형식으로 조건을 고정했습니다.

You are investigating a production incident.

Use only read-only commands.
Do not change infrastructure, deployments, database records, secrets, or code.
When evidence is missing, say it is missing.
Separate facts from assumptions.
Show every external command before using its result in the RCA.

Incident:
- Time range: 2026-06-12 13:00~14:00 KST
- Known clue: a Datadog screenshot shows GET /heartbeat around 30s and JVM Old Gen increasing near that time
- Do not assume this endpoint is the root cause
- Search for broader correlated signals before selecting root cause candidates

Collect:
- Datadog APM traces and latency across suspicious resources
- Datadog JVM heap, old gen, new gen, survivor, non-heap metrics
- Datadog logs, errors, warnings, monitors, and deployment events
- AWS RDS metrics around connection count, CPU, latency, locks
- AWS CloudWatch logs if available
- GitLab deployment, pipeline, and merged MR history around the incident

Output:
1. Timeline
2. Signals discovered
3. Confirmed facts
4. Root cause candidates
5. Evidence for and against each candidate
6. Missing evidence
7. Recommended changes

프롬프트 자체보다 이 형식이 결과를 안정시켰습니다.

오늘부터 미리 하는 것

Application Key를 새로 만들 때 validate 200만 보고 조사에 들어가지 않습니다. 실제 조사에 쓸 API를 먼저 한 번씩 호출합니다.

• GET /api/v1/query
• POST /api/v2/query/timeseries
• GET /api/v1/hosts
• 필요 시 event, monitor, dashboards

403이 나면 그 자리에서 scope를 보완합니다. 조사 도중이 아니라 조사 전에 발견해야 하는 자리입니다. 다음 편에서는 이렇게 열어둔 상태의 Datadog을 놓고 AI에게 이상 징후를 먼저 찾게 만든 흐름을 정리합니다.