aws-samples / aws-samples/sample-autonomous-cloud-coding-agents
feat(observability): Phase 3 — downstream attribution (GitHub PR + external API correlation)
- 主要言語
- TypeScript
- スター
- 146
- フォーク
- 46
- 平均マージ
- 3日 10時間
- マージ済み PR(30日)
- 24
説明
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)
コントリビューションガイド
調査の方向性
docs/design/OBSERVABILITY.md と #245 で提供された correlation envelope から始め、次に外向きの Linear、Jira、Slack、GitHub の handler とその injection point を特定します。各 integration について header を付ける設計と log のみの設計のどちらにするかを決め、その選択を source と Starlight sync に記録し、#209 の tenant isolation を後退させることなく injection point をカバーするテストを追加します。
索引モデルが issue の本文から書いたものです。
評価
- 技術スタック
- github, typescript
- 領域
- backend-api-design, observability
- issue の種類
- 機能追加
- 難易度
- 5/5
- 見積もり時間
- 1週間以上
- 活発さ
- 静か
- 明瞭さ
- おおむね明確
- 初心者へのやさしさ
- 35/100