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

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

オープン
#555 コメント 0 件 リアクション 0 件 担当者 0 名 GitHub で見る
enhancement observability
主要言語
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

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。