aws-samples / aws-samples/sample-autonomous-cloud-coding-agents
feat(observability): Phase 3 — downstream attribution (GitHub PR + external API correlation)
- Lingua principale
- TypeScript
- Stelle
- 143
- Fork
- 46
- Merge medio
- 3g 10h
- PR unite (30g)
- 24
Descrizione
Child of #245. Phase 3 (**Downstream attribution**) was deferred from the #245 core delivery (Phases 0–2 shipped the correlation envelope across orchestrator logs, TaskEvents, and agent OTel). This issue extends the same `{task_id, user_id, repo, trace_id}` envelope to the platform's **outbound** edges — where ABCA talks to the outside world.
## Context: what #245 already delivered
- **Correlation contract** documented in `docs/design/OBSERVABILITY.md` ("Correlation envelope" + "Join model").
- **Orchestrator logs** carry `{task_id, user_id, repo}` on admission→terminal transitions (via `logger.child`).
- **TaskEvents** (orchestrator + agent) stamp `user_id`/`repo`, and agent events stamp `trace_id` — so the event stream joins to the X-Ray trace.
- **Agent OTel** root span + baggage carry the envelope.
- Git commits already carry `Task-Id:` / `Prompt-Version:` trailers (pre-existing).
Phase 3 is what's left: attribution at the **external-integration boundary**, which is separable and lower value than the in-platform join.
## Scope
### 1. GitHub PR-level attribution (extend existing trailers)
- Stamp task/user metadata onto **PR bodies and PR comments** (not just commit trailers), so a human reading a PR — or a reviewer reading a comment — can trace it back to the originating `{task_id, user_id}` without leaving GitHub.
- Ensure the GitHub **actor** identity ABCA acts as is attributable back to the platform `user_id` that triggered the task.
### 2. External webhook / API call correlation
Handlers that call *out* (Linear, Jira, Slack, GitHub API, arbitrary webhooks) carry no correlation today. Add one of:
- an outbound correlation **header** (e.g. `X-ABCA-Task-Id`, or a W3C `traceparent`) on requests where the receiver can use it, and/or
- structured **log fields** `{task_id, user_id, trace_id}` at each outbound call site,
so a failure in an external integration can be tied back to the task that caused it.
## Out of scope
- Delegation chain propagation (cryptographically signed `user_id → orchestrator → agent`) — tracked separately in #249.
- The in-platform envelope work (done in #245).
## Acceptance criteria
- [ ] PR body/comments include task + actor attribution; documented in `docs/design/OBSERVABILITY.md` (source + Starlight sync).
- [ ] Outbound calls from Linear/Jira/Slack/GitHub handlers carry correlation (header and/or structured log fields) — pick and document the mechanism per integration.
- [ ] Tests for the injection points.
- [ ] No regression to #209 SessionRole tenant isolation.
## Design questions to resolve first
- Header format: bespoke `X-ABCA-*` vs W3C `traceparent`? (W3C composes with #245's OTel plane but only some receivers honor it.)
- Which integrations propagate outbound vs log-only?
## Related
- Parent: #245 (correlation envelope — Phases 0–2)
- #209 (per-session IAM), #215 (Bedrock cost attribution), #237 (compliance export), #249 (delegation chain)
Guida per i contributori
Apri la guida per i contributori
Direzione di ricerca
Inizia da docs/design/OBSERVABILITY.md e dal correlation envelope fornito da #245, quindi individua gli handler in uscita di Linear, Jira, Slack e GitHub e i relativi punti di injection. Risolvi, per ogni integrazione, il design tra header e solo log, documenta le scelte nel source e nella sincronizzazione di Starlight, quindi aggiungi test che coprano i punti di injection senza causare regressioni nell’isolamento dei tenant di #209.
Scritto dal modello di indicizzazione a partire dal testo della issue.
Valutazione
- Stack tecnologico
- github, typescript
- Ambito
- backend-api-design, observability
- Tipo di issue
- Funzionalità
- Difficoltà
- 5/5
- Tempo stimato
- Più di una settimana
- Stato di attività
- Tranquilla
- Chiarezza
- Abbastanza chiara
- Idoneità per principianti
- 35/100