Skip to content

docs(#9398): align tracing guides and comments with the code - #9400

Open
fullsend-ai-coder[bot] wants to merge 1 commit into
mainfrom
agent/9398-tracing-docs-match-code
Open

fullsend-ai-coder[bot] wants to merge 1 commit into
mainfrom
agent/9398-tracing-docs-match-code

Conversation

@fullsend-ai-coder

Copy link
Copy Markdown
Contributor

Summary

Changes the tracing guides and two code comments so they say what the code does. Only wording changes; behaviour stays the same.

Changes

  • docs/guides/infrastructure/distributed-tracing.md
    • The attribute table row and the cost section now name the cache token attributes the runner emits (gen_ai.usage.cache_creation.input_tokens, gen_ai.usage.cache_read.input_tokens, see internal/cli/run.go), replacing the underscore shorthand.
    • The eval-measurements paragraph no longer says "once Level 3 is implemented". Level 3 capture already exists (internal/cli/content_collector.go), and the paragraph now links to the guide's own "Content capture (Level 3)" section.
  • docs/guides/infrastructure/eval-measurements.md: the Level 3 row now links to that content capture section instead of the closed docs(adr): specify Level 3 content capture activation and sandbox env denylist #5947 draft, and no longer says "once L3 is implemented".
  • docs/guides/dev/tracing.md: the package layout now lists content.go, content_test.go and tracecontext/ (ADR 0154).
  • internal/cli/tool_spans_test.go: the comment now says codex emits ToolUseEvents with no id and no results. Pi does emit ids and results (internal/runtime/pi_progress.go). It leaves the id off only when it never saw a call's start line.
  • internal/telemetry/telemetry.go: the Setup doc comment now splits the two cases. The noop tracer is returned only when OTEL_SDK_DISABLED is set or the telemetry file can't be opened. A failed OTLP endpoint check, header check or exporter setup prints a warning and keeps the file exporter.

Testing

  • pre-commit couldn't fetch its remote hook repos in the sandbox (TLS certificate failure), so I ran the local hooks directly. gofmt, go vet, lint-docs-links, lint-broken-symlinks and lychee --offline --include-fragments (which checks the new anchor links) all pass. The remote hooks (trailing whitespace, end-of-file, gitleaks) did not run. scan-secrets and gitlint pass.
  • go test ./internal/telemetry/ and go test ./internal/cli/ -run TestToolSpanTracker pass.
  • No behavioural test was added because nothing behaves differently.

Context

Open PR #7553 edits the same table row and keeps the underscore shorthand. Whichever PR merges second will need a rebase.

🤖 Generated with Claude Code


Closes #9398

Post-script verification

  • Branch is not main/master (agent/9398-tracing-docs-match-code)
  • Secret scan passed (gitleaks — 280cab9d401024acc7e824c9555804b7981a7c88..HEAD)
  • PR body secret scan passed (gitleaks — no-git)
  • Final PR description secret scan passed (gitleaks — no-git)

The tracing guides and two code comments described behaviour the code
does not have. Wording only; no behaviour changes.

- distributed-tracing.md: name the cache token attributes as emitted
  (gen_ai.usage.cache_creation.input_tokens and
  gen_ai.usage.cache_read.input_tokens, run.go) instead of the
  underscore shorthand; drop "once Level 3 is implemented", since
  Level 3 capture exists (content_collector.go), and link its section.
- eval-measurements.md: point the Level 3 row at the content capture
  section instead of the closed #5947 draft; drop "once L3 is
  implemented".
- dev/tracing.md: add content.go, content_test.go and tracecontext/
  to the package layout.
- tool_spans_test.go: codex emits id-less ToolUseEvents and no
  results; pi emits ids and results, leaving the id off only when it
  never saw the call's start line.
- telemetry.go: Setup returns a noop tracer only when
  OTEL_SDK_DISABLED is true or the telemetry file cannot be opened;
  OTLP endpoint/header/exporter failures warn and keep the file
  exporter.

Note: pre-commit could not fetch remote hook repos (TLS failure in
the sandbox). Ran local hooks directly: gofmt, go vet,
lint-docs-links, lint-broken-symlinks and lychee all pass.

Closes #9398

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@fullsend-ai-coder
fullsend-ai-coder Bot requested a review from a team as a code owner November 12, 2026 23:45
@fullsend-ai-coder fullsend-ai-coder Bot added the ready-for-review Triggers review agent dispatch label Nov 12, 2026
@dhshah13 dhshah13 added the ok-to-test Allow e2e CI to run after maintainer review (must be re-applied after each push) label Nov 12, 2026
@github-actions

Copy link
Copy Markdown

Site preview

Preview: https://c1c17451-site.fullsend-ai.workers.dev

Commit: fd50493664f4d4f70cda9f61b5941e857415fc6c

@fullsend-ai-review

fullsend-ai-review Bot commented Nov 12, 2026 •

Copy link
Copy Markdown

🤖 Finished Review · ✅ Success · Started 11:52 PM UTC · Completed 11:59 PM UTC

Commit: fd50493 · View workflow run →

Runtime: pi · Model: sonnet → claude-sonnet-5-5 · Effort: high · Cost: $1.34

@fullsend-ai-review fullsend-ai-review Bot added the risk/moderate PR risk: moderate label Nov 12, 2026
@fullsend-ai-review

Copy link
Copy Markdown

Risk Assessment: moderate (2/5)

Details

Small documentation and comment alignment by a bot with well-scoped issue context is elevated to moderate risk due to high recent churn and coupling in active tracing documentation files.

@fullsend-ai-review

Copy link
Copy Markdown

Looks good to me


Labels: PR updates user-facing tracing documentation.

@fullsend-ai-review fullsend-ai-review Bot added ready-for-merge All reviewers approved — ready to merge component/docs User-facing documentation labels Nov 12, 2026
@codecov

codecov Bot commented Nov 13, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

This branch was successfully deployed

1 active and 1 inactive deployments
site-preview — fd504936 Deployed Nov 12, 2026 by github-actions[bot]
dev — fd504936 Deployed Nov 12, 2026 by fullsend-ai-coder[bot] via behaviour #20022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

component/docs User-facing documentation ok-to-test Allow e2e CI to run after maintainer review (must be re-applied after each push) ready-for-merge All reviewers approved — ready to merge ready-for-review Triggers review agent dispatch risk/moderate PR risk: moderate

Projects

None yet

Development

Successfully merging this pull request may close these issues.

docs: tracing guides do not match the code

1 participant