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

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

Open
#555 0 comments 0 reactions 0 assignees View on GitHub
enhancement observability
Dominant language
TypeScript
Stars
143
Forks
46
Avg merge
3d 9h
Merged PRs (30d)
20

Description

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)

Contributor guide

Open the contributing guide

Research direction

Start with docs/design/OBSERVABILITY.md and the correlation envelope delivered by #245, then locate the outbound Linear, Jira, Slack, and GitHub handlers and their injection points. Resolve the header versus log-only design per integration, document the choices in the source and Starlight sync, and add tests covering the injection points without regressing #209 tenant isolation.

Written by the indexing model from the issue text.

Assessment

Tech stack
github, typescript
Domain
backend-api-design, observability
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.