aws-samples / aws-samples/sample-autonomous-cloud-coding-agents
feat(observability): Claude Code native OTel events + operator runbook
- Lingua principale
- TypeScript
- Stelle
- 143
- Fork
- 46
- Merge medio
- 3g 10h
- PR unite (30g)
- 24
Descrizione
Child of #245 (suggested sub-deliverable from the issue thread). This is the **per-model-call granularity** layer of the same attribution story: #245's custom harness spans + TaskEvents give task-level correlation; Claude Code's native OTel events add prompt/tool-level cost and token forensics without parsing unstructured logs.
## Background
The harness already wires Claude Code CLI telemetry behind `ENABLE_CLI_TELEMETRY=1` in `agent/src/runner.py` (`CLAUDE_CODE_ENABLE_TELEMETRY`, OTLP logs export, `OTEL_RESOURCE_ATTRIBUTES` with `task.id` / `repo.url` / `agent.model`). CDK leaves it **disabled** today (`ENABLE_CLI_TELEMETRY` commented in `cdk/src/stacks/agent.ts`) pending verification that the ADOT sidecar forwards OTLP **logs**, not just traces.
## Deliverables
1. **Enable + verify** — Turn on `ENABLE_CLI_TELEMETRY` in the AgentCore runtime env after confirming `claude_code.api_request` / `claude_code.tool_result` / `claude_code.tool_decision` records land in CloudWatch (application log group or AgentCore runtime log stream).
2. **Session correlation** — Ensure `task.id` on `OTEL_RESOURCE_ATTRIBUTES` joins to the #245 correlation envelope (`{task_id, user_id, repo, trace_id}`).
3. **Operator runbook** — Add `docs/guides/CLAUDE_CODE_TELEMETRY.md` (sync via Starlight) with:
- Event type reference (`claude_code.api_request` carries `cost_usd`, `input_tokens`, `output_tokens`, `duration_ms`)
- Copy-paste CloudWatch Logs Insights queries: per-task cost rollup, tool histogram, PreToolUse / hook blocks via `claude_code.tool_decision`
- Known limitations: Claude Code emits OTLP **events** (LogRecords), not spans — the Traces tab may be empty while Events/logs are populated; subagent attribution gaps
4. **Docs cross-links** — From `docs/design/OBSERVABILITY.md` and `docs/guides/COST_ATTRIBUTION.md` (complements #215 Bedrock billing tags).
5. **Optional** — Dashboard widgets for `cost_usd` by `task.id` when attributes are present.
## Acceptance criteria
- [ ] One dry-run task produces queryable `claude_code.api_request` records tagged with `task.id`
- [ ] Runbook queries documented and validated against a real log group
- [ ] `ENABLE_CLI_TELEMETRY` default documented (on vs opt-in) with sidecar forwarding notes
- [ ] `task.id` join to the #245 envelope verified
## Related
- Parent: #245 (correlation envelope — provides the `task.id` join key)
- #215 (Bedrock cost attribution), #237 (compliance export)
- Requires: ADOT sidecar OTLP **logs** forwarding (verification gate)
Guida per i contributori
Apri la guida per i contributori
Direzione di ricerca
Leggi prima agent/src/runner.py e cdk/src/stacks/agent.ts, quindi verifica se il sidecar ADOT inoltra i log OTLP al gruppo di log CloudWatch pertinente. Aggiungi docs/guides/CLAUDE_CODE_TELEMETRY.md e collegamenti incrociati da docs/design/OBSERVABILITY.md e docs/guides/COST_ATTRIBUTION.md; il lavoro è completato quando una dry run mostra eventi interrogabili contrassegnati con task.id e le query documentate funzionano su un gruppo di log reale.
Scritto dal modello di indicizzazione a partire dal testo della issue.
Valutazione
- Stack tecnologico
- aws, python, typescript
- Ambito
- cloud, documentation, observability
- Tipo di issue
- Funzionalità
- Difficoltà
- 4/5
- Tempo stimato
- 3-5 giorni
- Stato di attività
- Tranquilla
- Chiarezza
- Abbastanza chiara
- Idoneità per principianti
- 48/100