docs(iorails): Telemetry - content capture docs

[tgasser-nv]

Description

Stacked PR On top of #1972 .

Doc updates for the tracing content-capture feature.

Related Issue(s)

#1972 - Code changes to implement content-capture in tracing

Checklist

• I've read the CONTRIBUTING guidelines.
• I've updated the documentation if applicable.
• I've added tests if applicable.
• @mentions of the person or team responsible for reviewing proposed changes.

[github-actions]

Documentation preview

https://nvidia-nemo.github.io/Guardrails/review/pr-1984

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR adds comprehensive documentation for the Content Capture feature in guardrails tracing. It introduces a new dedicated guide, documents configuration options with defaults, updates existing configuration reference examples, and adds navigation links to integrate the new documentation into the tracing guides.

Changes

Content Capture Tracing Documentation

Layer / File(s)	Summary
Content Capture feature documentation docs/observability/tracing/content-capture.md	New page documents Content Capture as opt-in recording of prompts, responses, and rail inputs on tracing spans, with enablement via config, environment-variable overrides, output format selection (JSON vs legacy span events), span-type capture locations, streaming buffering, engine support (IORails vs LLMRails), and operational considerations including privacy, truncation, semconv evolution, and performance.
Configuration schema and defaults docs/configure-rails/yaml-schema/tracing-configuration.md	Tracing configuration schema documents two new options: span_format (opentelemetry or legacy) and enable_content_capture (false by default, with PII warning). Clarifies that traces capture only metadata by default, and content is recorded only when capture is enabled.
Configuration reference example docs/configure-rails/configuration-reference.md	Configuration reference example shows enable_content_capture: false with inline warning comment about capturing prompts/responses and PII risk, plus reference text directing to content-capture documentation for environment-variable overrides, output formats, and privacy guidance.
Tracing documentation navigation docs/observability/tracing/index.md	Tracing index updates refine Data Privacy guidance to point to content-capture.md, add Content Capture as a new entry in the Contents section and toctree navigation list.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Suggested reviewers

• Pouyanpi
• miyoungc
• cparisien

🚥 Pre-merge checks | ✅ 6

✅ Passed checks (6 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Test Results For Major Changes	✅ Passed	PR contains documentation-only changes with no code modifications or functional impacts. Documentation updates are minor changes not requiring test results per check criteria.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely summarizes the main change: adding documentation about content capture for telemetry/observability in IORails, which aligns with the four documentation files updated.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/iorails-otel-content-capture

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/observability/tracing/content-capture.md`:
- Around line 121-122: The sentence implying spans can be correlated "by name
alone" is misleading; update the line referencing `gen_ai.*` attributes and
event names to state that names are insufficient for correlation and that
backends should use trace/span context (trace_id/span_id or propagated context)
to link the outer request span with inner LLM spans, while noting shared
attributes/events can assist but must not be relied on as the primary
correlation mechanism.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: e5cadf72-82a8-43f6-9b5a-724e1ea0087d

📥 Commits

Reviewing files that changed from the base of the PR and between 48bbcc1 and def204a.

📒 Files selected for processing (4)

• docs/configure-rails/configuration-reference.md
• docs/configure-rails/yaml-schema/tracing-configuration.md
• docs/observability/tracing/content-capture.md
• docs/observability/tracing/index.md

[tgasser-nv]

@greptile-apps Review this PR

[greptile-apps]

Greptile Summary

This docs-only PR adds a new content-capture.md reference page and updates cross-references in the tracing configuration and index pages to document the opt-in content-capture feature introduced in PR #1972.

• New page (content-capture.md): Covers enabling content capture via enable_content_capture, the OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT env-var override, dual output formats (JSON span attributes vs legacy span events gated on OTEL_SEMCONV_STABILITY_OPT_IN), per-span capture locations, streaming behaviour, and an engine support matrix clearly scoping IORails-only controls.
• tracing-configuration.md: Adds span_format and enable_content_capture rows to the options table, and a note clarifying that only metadata is captured by default — but the existing LLM Calls table row still says "prompts, and responses," which contradicts that note.
• configuration-reference.md / index.md: Minor additions of inline PII comments and cross-reference links to the new page.

Confidence Score: 5/5

Documentation-only change; safe to merge with one minor table-row inconsistency to clean up.

All changes are documentation. The new content-capture page is accurate and well-structured. The only inconsistency is the LLM Calls row in the Trace Information table still describing prompt/response capture as always-on, which the note immediately below contradicts — a quick one-line fix.

docs/configure-rails/yaml-schema/tracing-configuration.md — the LLM Calls row in the Trace Information table.

Important Files Changed

Filename	Overview
docs/observability/tracing/content-capture.md	New how-to page documenting content-capture: env-var override, dual output formats (JSON attributes vs legacy events), per-span capture locations, streaming behaviour, and engine support matrix. Well-structured with appropriate IORails-only scope notes and privacy warnings.
docs/configure-rails/yaml-schema/tracing-configuration.md	Adds span_format and enable_content_capture rows to the options table and a clarifying note below the Trace Information table; the LLM Calls row still says 'prompts, and responses' which contradicts the new default-metadata-only note.
docs/configure-rails/configuration-reference.md	Adds an inline PII comment to the enable_content_capture example and a cross-reference link to the new content-capture page. Change is accurate and unambiguous.
docs/observability/tracing/index.md	Updates the Data Privacy risk bullet to point to content-capture.md and adds the new page to the related-links and toctree. Clean, accurate updates.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Guardrails Request] --> B{enable_content_capture?}
    B -- "false (default)" --> C[Metadata only\ntiming, token counts, finish reasons]
    B -- true --> D{OTEL_INSTRUMENTATION_GENAI\n_CAPTURE_MESSAGE_CONTENT}
    D -- "false / 0" --> C
    D -- "true / 1 or unset" --> E{OTEL_SEMCONV_STABILITY\n_OPT_IN contains\ngen_ai_latest_experimental?}
    E -- Yes --> F[JSON Span Attributes\ngen_ai.input.messages\ngen_ai.output.messages\ngen_ai.system_instructions]
    E -- No/unset --> G[Legacy Span Events\ngen_ai.system.message\ngen_ai.user.message\ngen_ai.choice ...]
    F --> H[guardrails.request span\nguardrails.rail span\ngen_ai LLM spans]
    G --> H

Loading

Prompt To Fix All With AI

Fix the following 1 code review issue. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 1
docs/configure-rails/yaml-schema/tracing-configuration.md:120
The "LLM Calls" table row says it captures "prompts, and responses," but the note added directly below the table says that, by default, "traces capture only metadata" and "Prompt and response content is recorded only when content capture is enabled." A reader who scans the table but not the note will incorrectly believe prompts and responses are always recorded. The row should be updated to describe what is *always* captured (invocation metadata), leaving the prompt/response detail to the note below.

```suggestion
| **LLM Calls** | LLM invocations and performance metadata (token counts, latency, model) |
```

_{Reviews (7): Last reviewed commit: "Update docs to reflect final merged stat..." | Re-trigger Greptile}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[Pouyanpi]

is it a doc fix?

[Pouyanpi]

is this really necessary? it is a field and we briefly mention what it does. We can refer users go GenAI SemConv to understand the risk etc. IMO, the two other changes are sufficient.

Also IORails deserves to be discoverable! Right now the docs are kind of mixed, sometimes we are talking about IORails, sometimes LLMRails, sometimes both... I think we should do something about it.

[github-actions]

PR merge guidance

@tgasser-nv thanks for the PR. GitHub is currently blocking merge for one or more repository requirements:

• This branch has merge conflicts with develop. Please rebase your branch on the latest develop, resolve the conflicts locally, and force-push the updated branch.

Relevant guide:

• Signed commits: https://github.com/NVIDIA-NeMo/Guardrails/blob/develop/CONTRIBUTING.md#commit-signing
• Contribution guide: https://github.com/NVIDIA-NeMo/Guardrails/blob/develop/CONTRIBUTING.md