aws-samples / aws-samples/sample-autonomous-cloud-coding-agents
feat(observability): Claude Code native OTel events + operator runbook
- Vorherrschende Sprache
- TypeScript
- Sterne
- 143
- Forks
- 46
- Ø Merge
- 3 T. 10 Std.
- Gemergte PRs (30 T.)
- 24
Beschreibung
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)
Beitragsleitfaden
Rechercherichtung
Lies zuerst agent/src/runner.py und cdk/src/stacks/agent.ts und überprüfe dann, ob der ADOT-Sidecar OTLP-Logs an die relevante CloudWatch-Loggruppe weiterleitet. Füge docs/guides/CLAUDE_CODE_TELEMETRY.md hinzu und erstelle Querverweise von docs/design/OBSERVABILITY.md und docs/guides/COST_ATTRIBUTION.md; als erledigt gilt die Aufgabe, wenn ein Dry Run abfragbare Ereignisse mit dem Tag task.id zeigt und die dokumentierten Abfragen gegen eine echte Loggruppe funktionieren.
Vom Indexierungsmodell aus dem Issue-Text verfasst.
Bewertung
- Tech-Stack
- aws, python, typescript
- Bereich
- cloud, documentation, observability
- Issue-Typ
- Feature
- Schwierigkeit
- 4/5
- Geschätzter Aufwand
- 3-5 Tage
- Aktivitätsstatus
- Ruhig
- Klarheit
- Größtenteils klar
- Anfängerfreundlichkeit
- 48/100