docs: document OpenTelemetry metadata promotion

[ericevans-nv]

Depends on PR #802. Merge the implementation PR before this documentation PR.

Overview

Adds the OpenTelemetry configuration documentation for promoting selected Event metadata to top-level OpenTelemetry attributes.

The new section explains the opt-in promote_metadata_prefixes setting, its empty default, and how promoted attributes relate to Relay's existing metadata projection.

• I confirm this contribution is my own work, or I have the right to submit it under this project's license.
• I searched existing issues and open pull requests, and this does not duplicate existing work.

Details

• Adds promote_metadata_prefixes = ["nv."] to the trace-endpoint example.
• Documents accepted literal prefix syntax and rejected glob or malformed values.
• Documents supported primitive and homogeneous-array value types.
• Explains Scope-end and Mark promotion behavior.
• Explains collision precedence for projection-owned attributes and configured aliases.
• Clarifies that promotion does not modify the Event or ATOF payload and that static values should use resource_attributes.

The original documentation commit passed the repository documentation link-check hook. The current-main documentation build and link-check run was stopped before completion to publish this draft immediately.

Where should the reviewer start?

Review the new Event Metadata Promotion section in docs/configure-plugins/observability/opentelemetry.mdx and compare it with the implementation in PR #802.

Related Issues: (use one of the action keywords Closes / Fixes / Resolves / Relates to)

• Relates to feat(observability): promote selected Event metadata to OTel attributes #802

Summary by CodeRabbit

• Documentation
  • Updated the OpenTelemetry configuration example with metadata promotion settings.
  • Added guidance on promotion syntax, supported values, precedence, lifecycle behavior, projections, namespace collisions, diagnostics, and payload preservation.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Enterprise

Run ID: d11fd2e3-07f3-4cd8-82ee-8a9ebad9815b

📥 Commits

Reviewing files that changed from the base of the PR and between 41ce0b6 and 136c5bb.

📒 Files selected for processing (1)

• docs/configure-plugins/observability/opentelemetry.mdx

Included review availability: Your plan provides up to 12 included reviews per hour; 11 remain after this review.

📜 Recent review details

🧰 Additional context used

📓 Path-based instructions (10)

**/*.mdx

📄 CodeRabbit inference engine (.agents/skills/review-doc-style/SKILL.md)

MDX top-of-file SPDX comments must use {/* ... */} delimiters instead of HTML comment delimiters (Must-Fix)

**/*.mdx: In MDX files, top-of-file comments must use JSX comment delimiters:
{/* to open and */} to close. Do not use HTML comments for MDX SPDX
headers.
New or regenerated MDX files use {/* ... */} for top-of-file SPDX comments

**/*.mdx: Use just docs for docs-site builds and just docs-linkcheck when links
changed.

Files:

• docs/configure-plugins/observability/opentelemetry.mdx

{docs,examples}/**/*

📄 CodeRabbit inference engine (.agents/skills/rename-surfaces/SKILL.md)

Update docs and examples.

Files:

• docs/configure-plugins/observability/opentelemetry.mdx

**/*.{md,mdx,rst}

📄 CodeRabbit inference engine (.agents/skills/review-doc-style/assets/nvidia-style-technical-docs.md)

**/*.{md,mdx,rst}: Use title case consistently for technical documentation headings and table headers; avoid quotation marks, ampersands, and exclamation marks in headings, while preserving official product, event, research, and whitepaper title case.
Format code elements, commands, parameters, package names, expressions, directories, file names, and paths in monospace; represent path placeholders with angle brackets inside monospace.
Format UI buttons, menus, fields, and labels in bold, and separate consecutive UI navigation labels with >.
Use quotation marks for error messages and strings when appropriate, italics for newly introduced terms and publication titles, and plain text for keyboard shortcuts.
Represent GitHub repositories with owner/repository link text, such as [NVIDIA/NeMo](link), rather than generic repository wording.
Introduce every code block with a complete sentence; do not let a code block complete or interrupt the grammar of surrounding prose; use syntax highlighting when supported.
Keep inline method, function, and class references consistent with nearby documentation; omit empty parentheses in prose when no call is shown.
Use descriptive link text matching the destination title when possible; avoid raw URLs, generic anchors, long-sentence links, and unnecessary links that distract from procedures.
Ensure lists have a complete lead-in sentence, more than one item, no more than two levels, parallel construction, one idea or action per item, and appropriate punctuation; use bullets for unordered items and numbers for ordered tasks.
Format definition lists with a bold term followed by a complete, parallel, punctuated definition.
Use tables for reference information, decision support, compatibility matrices, and comparable choices; flag one-row tables, missing captions or lead-ins, sentence-case headers where title case is expected, unexplained empty cells, and code or links that would be clearer as prose.
Write procedure steps as imperative ...

Files:

• docs/configure-plugins/observability/opentelemetry.mdx

docs/**/*.mdx

📄 CodeRabbit inference engine (.agents/skills/test-python-binding/SKILL.md)

For documentation-only changes, prefer contribute-docs plus targeted command checks.

Files:

• docs/configure-plugins/observability/opentelemetry.mdx

**/*.{md,mdx}

📄 CodeRabbit inference engine (AGENTS.md)

Keep stable public wrappers at the scripts/ root in docs and examples. Reference namespaced helper paths only when documenting internal maintenance work.

**/*.{md,mdx}: Prefer the documented public API, not internal shortcuts
Keep package names, repo references, and build commands current
When documenting contribution workflow, require an issue before external contribution PRs and note that NVIDIA contributors may use a GitHub or Linear issue.
Update entry-point docs when examples or reading paths change
Keep release-process and release-notes guidance in repo-maintainer docs such as
RELEASING.md, not as user-facing docs pages or CHANGELOG.md
Keep stable user-facing wrappers at scripts/ root in docs and examples;
only point at namespaced helper paths when documenting internal maintenance
work
When detailed dynamic plugin guides exist, keep Rust native plugin examples,
Python worker plugin examples, and grpc-v1 protocol details on separate
pages.
Relevant getting-started or reference docs updated
Example commands still match current package names and paths
Dynamic plugin entry pages link to native, worker, Rust example, Python
example, and protocol pages when those pages exist
Images, diagrams, tables, and custom visual content remain legible and
fully accessible at representative desktop and narrow page widths
Release-policy docs still point to GitHub Releases as the only release-history source of truth

Files:

• docs/configure-plugins/observability/opentelemetry.mdx

**/*.{rs,py,go,js,ts,html,md,mdx,toml}

📄 CodeRabbit inference engine (CONTRIBUTING.md)

All source files must include an SPDX license header.

Files:

• docs/configure-plugins/observability/opentelemetry.mdx

**/*

📄 CodeRabbit inference engine (CONTRIBUTING.md)

**/*: Every commit in a pull request must include a Developer Certificate of Origin sign-off.
CI must pass before merging.
Use SONAR_IGNORE_START / SONAR_IGNORE_END only for documented false
positives that cannot be resolved in code or by improving the analyzer
configuration.
Keep the ignored block as small as possible, add a brief comment
explaining why the suppression is needed, and call it out in the PR description
so reviewers can explicitly sign off on it.
Keep the first line under 72 characters. Use the body for additional context when the change is not self-explanatory.

**/*: - [ ] Branch scope is coherent and reviewable

• Relevant tests passed under validate-change

• Docs and examples updated for any public behavior changes

• Pull request title follows Conventional Commit style and uses the correct
  type
  Use Conventional Commit style for PR titles:
  Only check the contribution confirmation boxes when they are true. If either
  confirmation cannot be made, stop before opening the PR and surface the blocker.

• SPDX license header on any new files

**/*: Tool execution callbacks and each execution-intercept next continuation
return the canonical ToolExecutionResult { result, annotation }. A forwarding
intercept must preserve both fields in ToolExecutionInterceptOutcome; Relay
retains pending_marks separately.
Tool sanitize-response guardrails receive
only result.

• Registration and duplicate-name behavior
• Deregistration and no-op missing-name behavior
• Ordering by priority
• Callback failure policy, including fail-open behavior when required
• Scope-local registration, inheritance, and cleanup on pop
• Parity coverage in every affected binding

**/*: Keep NeMo Relay optional
Use stable, documented framework or plugin APIs
Wrap tool and LLM paths at the correct framework boundary
Preserve the framework's original behavior when NeMo Relay is absent
Integration uses public framework or plugin A...

Files:

• docs/configure-plugins/observability/opentelemetry.mdx

docs/**

📄 CodeRabbit inference engine (.agents/skills/contribute-docs/SKILL.md)

Run just docs when the docs site changed; ./scripts/build-docs.sh html remains the compatibility wrapper

Files:

• docs/configure-plugins/observability/opentelemetry.mdx

**/*.{md,mdx,rs,py,go,js,ts}

📄 CodeRabbit inference engine (.agents/skills/maintain-observability/SKILL.md)

• Update docs and examples in the same branch.

Files:

• docs/configure-plugins/observability/opentelemetry.mdx

{docs/**,README.md,CONTRIBUTING.md,RELEASING.md,SECURITY.md}

⚙️ CodeRabbit configuration file

{docs/**,README.md,CONTRIBUTING.md,RELEASING.md,SECURITY.md}: Review documentation for technical accuracy against the current API, command correctness, and consistency across language bindings.
Flag stale examples, missing SPDX headers where required, and instructions that no longer match CI or pre-commit behavior.

Files:

• docs/configure-plugins/observability/opentelemetry.mdx

🧠 Learnings (1)

📚 Learning: 2026-07-14T02:53:59.997Z

Learnt from: willkill07
Repo: NVIDIA/NeMo-Relay PR: 415
File: docs/configure-plugins/observability/opentelemetry.mdx:98-113
Timestamp: 2026-07-14T02:53:59.997Z
Learning: In NeMo-Relay’s OpenTelemetry/OpenInference observability projection docs under docs/configure-plugins/observability/, document the projected-attribute contract as follows: (1) emit scalar top-level `data`/`metadata` fields as typed dotted OTLP attributes (for example, `nemo_relay.start.metadata.tenant`); (2) keep nested objects/arrays as JSON strings at their top-level OTLP attribute (rather than expanding them into nested OTLP attributes); and (3) do not reference the legacy `*_json` payload attributes (e.g., `data_json`, `metadata_json`, `input_json`) because they were intentionally removed as a breaking change.

Applied to files:

• docs/configure-plugins/observability/opentelemetry.mdx

🔇 Additional comments (2)

docs/configure-plugins/observability/opentelemetry.mdx (2)

94-94: LGTM!

---

147-196: 📐 Maintainability & Code Quality

Verify the docs-site build.

Run just docs before handoff. The changed ranges add no links, so just docs-linkcheck is not required for this change.

As per coding guidelines, "Use just docs for docs-site builds and just docs-linkcheck when links changed."

Source: Coding guidelines

---

Walkthrough

The OpenTelemetry documentation adds the promote_metadata_prefixes configuration example and documents metadata promotion syntax, precedence, lifecycle, collision handling, diagnostics, and payload immutability.

Changes

OpenTelemetry metadata promotion

Layer / File(s)	Summary
Document metadata promotion configuration and behavior docs/configure-plugins/observability/opentelemetry.mdx	The trace endpoint example enables promotion for metadata keys beginning with nv.. The documentation defines matching rules, accepted values, injector and scope precedence, protected keys, rejected-value diagnostics, and payload immutability.

Estimated code review effort: 2 (Simple) | ~10 minutes

Merge Risk: ⚪ Minimal · up to 136c5

This is a localized documentation-only change with no actionable merge-blocking risk remaining after the normal documentation build check.

Possibly related PRs

• NVIDIA/NeMo-Relay#802: Introduces the promote_metadata_prefixes feature documented by this change.
• NVIDIA/NeMo-Relay#795: Also updates the OpenTelemetry configuration documentation for related OTLP behavior.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description check	✅ Passed	The description includes all required sections, completed contribution checks, detailed changes, reviewer guidance, and a valid related issue reference.
Title check	✅ Passed	The title follows Conventional Commits format, uses an allowed lowercase type, states the documentation change, and meets the length and punctuation rules.
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.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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

[github-actions]

Fern docs preview: https://nvidia-preview-pull-request-803.docs.buildwithfern.com/nemo/relay/dev