Skip to content

Explain how the reference Guardian produces a trace, with diagrams - #280

Merged
rocklambros merged 2 commits into
integrationfrom
docs/trace-export-guide
Oct 15, 2026
Merged

rocklambros merged 2 commits into
integrationfrom
docs/trace-export-guide

Conversation

@rocklambros

Copy link
Copy Markdown
Collaborator

What changed

This explains how the reference Guardian produces a trace, now that the exporter (PR #244), the decision events (PR #275), the sample and walkthrough (PR #277) and the proxy fixes (PR #279) have landed. It adds five mermaid diagrams, and it doesn't change the specification.

  • Trace with OpenTelemetry (docs site) gains "How the reference Guardian produces a trace":
    • the two streams, the Guardian's own and the host's audit log through the converter, and how a reader joins them on acs.session.id plus acs.request_id;
    • one tool call followed through a sequence diagram, including who reports a failure;
    • what each output file is for;
    • what service.name and acs.failure.reported_by do not prove.
  • Trace overview (docs site) gains a short orientation with a diagram of where Trace sits.
  • The walkthrough ("Produce a trace") gains a diagram of which step and process writes each file under .acs/.
  • The Guardian README gains a diagram of the exporter's internals and a Troubleshooting list. The list quotes the exact messages a reader may see, disabled after failure, the loopback proxy warning and the converter's refusal, and says what each one means.
  • The root README gets one sentence pointing at the new section, and a correction: the host adapter, not the Guardian, writes the audit log.

Which issue does this implement

Refs #266
Refs #91

How it was checked

  • uv run mkdocs build --strict passes, and uv run pytest gives 918 passed. That includes the docs-example test, the doc-link tests and the hook-taxonomy guard.
  • bun test test/collector-config.test.ts test/readme-captures.test.ts passes, so every walkthrough sentence those tests pin is unchanged.
  • All 15 new links and anchors were resolved against the tree by script. Links to main that point at files only on integration (the collector config and the sample) start working when integration is promoted, like the page's existing sample link.
  • All five diagrams parse in mermaid 11.4.1. A broken diagram was rejected by the same check.
  • Every claim was checked against the exporter, the converter and the committed sample.

Base branch

  • integration, because this touches the specification, schemas, a reference
    implementation, an adapter, tests, or CI

Type of change

  • Documentation

I tested this

  • I synced my branch with the base branch before opening this
  • uv run pytest -v passes on my machine
  • uv run mkdocs build --strict passes on my machine

Checklist

  • Commits are signed off with git commit -s (required by the DCO)
  • Prose follows STYLE.md
  • No secrets, tokens, or internal URLs in the diff

Security

  • This change has no security impact

Signed-off-by: rocklambros <rock@rockcyber.com>
Signed-off-by: rocklambros <rock@rockcyber.com>
@rocklambros

Copy link
Copy Markdown
Collaborator Author

Admin-merged on the project lead's call, so the 0.1.4 release carries the explanation of the trace pipeline. Every check is green, and the description says how each claim and link was checked. @afogel @bar-capsule, comments after the fact are welcome, and anything you find goes in a follow-up.

@rocklambros
rocklambros merged commit 685367d into integration Oct 15, 2026
10 checks passed
@github-project-automation github-project-automation Bot moved this from Needs triage to Done in ACS Project Tracker Oct 15, 2026
This was referenced Oct 15, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: Done

Development

Successfully merging this pull request may close these issues.

1 participant