aws-samples / aws-samples/sample-autonomous-cloud-coding-agents

feat(observability): Phase 3 — downstream attribution (GitHub PR + external API correlation)

Offen
#555 0 Kommentare 0 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen
enhancement observability
Vorherrschende Sprache
TypeScript
Sterne
143
Forks
46
Ø Merge
3 T. 10 Std.
Gemergte PRs (30 T.)
24

Beschreibung

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)

Beitragsleitfaden

Beitragsleitfaden öffnen

Rechercherichtung

Beginne mit docs/design/OBSERVABILITY.md und dem durch #245 bereitgestellten Correlation Envelope. Suche dann die ausgehenden Linear-, Jira-, Slack- und GitHub-Handler sowie deren Injection Points. Kläre für jede Integration das Design „Header versus nur Logging“, dokumentiere die Entscheidungen im Source und in der Starlight-Synchronisierung und füge Tests hinzu, die die Injection Points abdecken, ohne die Tenant-Isolation aus #209 zu beeinträchtigen.

Vom Indexierungsmodell aus dem Issue-Text verfasst.

Bewertung

Tech-Stack
github, typescript
Bereich
backend-api-design, observability
Issue-Typ
Feature
Schwierigkeit
5/5
Geschätzter Aufwand
Über eine Woche
Aktivitätsstatus
Ruhig
Klarheit
Größtenteils klar
Anfängerfreundlichkeit
35/100

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.