docs(adr): accept ADR 0071 harness snapshot for agent traces - #5508
Closed
HofniGartner wants to merge 2 commits into
Closed
docs(adr): accept ADR 0071 harness snapshot for agent traces#5508HofniGartner wants to merge 2 commits into
HofniGartner wants to merge 2 commits into
Conversation
Record Level-1 harness-snapshot.json and root-span forge pointers as the run-time join contract; implementation follows in a separate issue. Signed-off-by: Hofni Gartner <hgartner@redhat.com> Co-authored-by: Cursor <cursoragent@cursor.com>
Accept status, add Options, single Decision, bullet Consequences, and Planned callout for harness-snapshot in the tracing guide (fullsend-ai#5449). Signed-off-by: Hofni Gartner <hgartner@redhat.com> Co-authored-by: Cursor <cursoragent@cursor.com>
E2E tests did not runE2E tests run automatically for org/repo members and collaborators on pull requests. For other contributors, a maintainer must add the See E2E testing guide for details. |
|
Thank you for your interest in contributing to fullsend, @HofniGartner. This project uses a vouch system for first-time contributors. Before submitting a pull request, you need to be vouched by a maintainer. To get vouched:
See CONTRIBUTING.md for details. |
PR Summary by QodoDocument ADR 0071 harness snapshot join contract for agent tracing
AI Description
Diagram
High-Level Assessment
Files changed (2)
|
Code Review by Qodo
1. ADR 0071 missing architecture update
|
![qodo-code-review[bot]](https://avatars.githubusercontent.com/in/484649?s=60&v=4){kind=small}
Comment on lines
+1
to
+20
| --- | ||
| title: "71. Harness snapshot and forge pointer correlation for agent traces" | ||
| status: Accepted | ||
| relates_to: | ||
| - operational-observability | ||
| topics: | ||
| - observability | ||
| - telemetry | ||
| - opentelemetry | ||
| - forge | ||
| --- | ||
|
|
||
| # 71. Harness snapshot and forge pointer correlation for agent traces | ||
|
|
||
| Date: 2026-07-22 | ||
|
|
||
| ## Status | ||
|
|
||
| Accepted | ||
|
|
There was a problem hiding this comment.
2. adr 0071 missing architecture update 📜 Skill insight ⚙ Maintainability
This PR adds an Accepted ADR, but docs/architecture.md was not updated with a corresponding decided entry linking to the ADR. This leaves the architecture overview out of sync with the newly accepted decision.
Agent Prompt
## Issue description
`docs/architecture.md` must be updated when an ADR is added/accepted, with a short decided note and a link to the ADR.
## Issue Context
ADR 0071 is marked `Accepted`, but the architecture overview's Observability section does not include this new decided item.
## Fix Focus Areas
- docs/ADRs/0071-forge-pointer-correlation-for-agent-traces.md[1-20]
- docs/architecture.md[254-266]
ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools
Comment on lines
+21
to
+28
| ## Context | ||
|
|
||
| [ADR 0050](0050-distributed-tracing-instrumentation.md) defines how fullsend | ||
| generates traces (OTel Go SDK; Level 1 = `run-telemetry.jsonl`; Level 2 = | ||
| OTLP). [Operational observability](../problems/operational-observability.md) | ||
| requires forge **pointers** (repo + SHA, change id, pipeline run) rather than | ||
| duplicating diffs, and a stable answer to: “what harness/config produced this | ||
| run?” |
There was a problem hiding this comment.
3. adr 0071 context omits adr 0005 📜 Skill insight ⚙ Maintainability
The ADR references ADR 0005 as related, but does not cross-reference it in the Context section as required. This makes the decision harder to interpret in relation to prior forge abstraction decisions.
Agent Prompt
## Issue description
ADR 0071 lists ADR 0005 as related, but the Context section does not include an explicit cross-reference to ADR 0005.
## Issue Context
The compliance requirement is specifically that related ADRs be cross-referenced in the Context section.
## Fix Focus Areas
- docs/ADRs/0071-forge-pointer-correlation-for-agent-traces.md[21-36]
- docs/ADRs/0071-forge-pointer-correlation-for-agent-traces.md[80-84]
ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools
Comment on lines
+80
to
+87
| ## Related | ||
|
|
||
| - [ADR 0050](0050-distributed-tracing-instrumentation.md) | ||
| - [ADR 0005](0005-forge-abstraction-layer.md) | ||
| - Shared join contract: [provenance_forge_pointers.md](https://github.com/RHEcosystemAppEng/ABEvalFlow/blob/main/Docs/provenance_forge_pointers.md) | ||
| - Implementation: [#5449](https://github.com/fullsend-ai/fullsend/issues/5449) | ||
| - [#2368](https://github.com/fullsend-ai/fullsend/issues/2368) | ||
| - [#294](https://github.com/fullsend-ai/fullsend/issues/294) |
There was a problem hiding this comment.
5. adr 0071 not template-exact 📜 Skill insight ⚙ Maintainability
ADR 0071 includes structure that does not match the ADR template exactly (e.g., an extra `## Related` section and missing the template's standard explanatory comment block). This breaks the required uniform ADR format.
Agent Prompt
## Issue description
ADR 0071 does not follow the ADR template in `docs/ADRs/0000-adr-template.md` exactly.
## Issue Context
The template defines the required sections/format. ADR 0071 adds an extra `## Related` section and omits the template's standard comment block.
## Fix Focus Areas
- docs/ADRs/0000-adr-template.md[14-41]
- docs/ADRs/0071-forge-pointer-correlation-for-agent-traces.md[17-24]
- docs/ADRs/0071-forge-pointer-correlation-for-agent-traces.md[80-87]
ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools
Comment on lines
+56
to
+65
| Every `fullsend run` records run-start join keys by writing | ||
| **`harness-snapshot.json`** next to `run-telemetry.jsonl` (after the root span | ||
| exists) **and** setting the same keys on the root `run` span (`vcs.*`, | ||
| `cicd.*`, harness content SHA, forge platform). The file holds pointers and a | ||
| config fingerprint only (harness identity, content hash, forge/CI pointers when | ||
| known, `trace_id` / `traceparent`) — no diffs, prompts, or skill bodies. | ||
| Forge/CI fields are filled at write time (`FULLSEND_*` overrides first, then | ||
| standard CI env). Consumers read the JSON (or stores that ingest it), not | ||
| ambient CI env. `OTEL_SDK_DISABLED=true` suppresses span export but does **not** | ||
| suppress the snapshot file. |
There was a problem hiding this comment.
6. Undefined disabled-mode trace ids 🐞 Bug ≡ Correctness
ADR 0071 requires harness-snapshot.json even when OTEL_SDK_DISABLED=true, while also requiring it be written “after the root span exists” and include trace_id/traceparent. In the current implementation, OTEL_SDK_DISABLED=true returns a noop tracer and does not create run-telemetry.jsonl, so the ADR leaves disabled-mode trace correlation fields underspecified (risking inconsistent future implementation/consumer expectations).
Agent Prompt
## Issue description
ADR 0071 states the snapshot is written after the root span exists and includes `trace_id`/`traceparent`, but also states the snapshot still exists when `OTEL_SDK_DISABLED=true`. In the current code, `OTEL_SDK_DISABLED=true` disables tracing entirely (noop tracer) and prevents `run-telemetry.jsonl` creation, so there may be no usable trace context.
Clarify the contract for disabled mode so implementers and downstream consumers know what to expect.
## Issue Context
Telemetry setup currently short-circuits when `OTEL_SDK_DISABLED=true`.
## Fix Focus Areas
- docs/ADRs/0071-forge-pointer-correlation-for-agent-traces.md[56-65]
## Concrete fix options (pick one and document it explicitly)
1. **Snapshot still written, but trace fields omitted/null:** state `trace_id`/`traceparent` are absent when SDK disabled.
2. **Snapshot includes a separate run ID:** introduce a `run_id` (non-OTel) that always exists; only include `trace_id`/`traceparent` when tracing is enabled.
3. **Generate a synthetic W3C trace context even when SDK disabled:** specify how it’s generated and note it won’t correspond to any exported spans.
Also consider rewording “after the root span exists” to be conditional on tracing being enabled.
ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools
5 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Record ADR 0071: Level-1
harness-snapshot.jsonplus mirrored root-span forge pointers as the run-time join contract. Docs only — implementation remains #5449.Replaces auto-closed #5505 after addressing review feedback (valid ADR status, Options, one Decision, bullet Consequences,
> **Planned:**callout in the tracing guide).Related Issue
Implementation: #5449
Changes
Accepted; Options A–D; single Decision (snapshot file + root-span attrs); Consequences as bullets; thin field description with join-contract linkrun-telemetry.jsonlonly; snapshot under Planned + Implement ADR 0071: harness-snapshot.json + root-span forge pointers #5449Testing
mainat merge (/renumber-adrif needed)Checklist
Made with Cursor