docs: add trace incident runbook

[mnajafian-nv]

Overview

Adds a production incident runbook for diagnosing NeMo Relay trace and telemetry issues.

• 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 a symptom-first runbook for missing traces, partial traces, wrong scope parentage, exporter failures, duplicate events, and sensitive telemetry.
• Links the runbook from the troubleshooting guide, observability docs, and docs index.
• Keeps production escalation guidance limited to sanitized event samples.

Where should the reviewer start?

docs/troubleshooting/production-incident-runbook.md

Related Issues

Summary by CodeRabbit

• Documentation
  • Added comprehensive Trace Incident Runbook for troubleshooting missing traces, scope attachment issues, export failures, duplicate events, and sensitive telemetry concerns
  • Enhanced navigation and guidance directing users to trace troubleshooting resources
  • Includes symptom diagnosis tables, step-by-step verification checks, and escalation procedures with security-focused data collection guidelines

[coderabbitai]

Walkthrough

This PR adds a comprehensive trace incident runbook for NeMo Relay applications, enabling self-service troubleshooting of telemetry issues (missing traces, scope problems, export failures, duplicates, sensitive data). The runbook is integrated into documentation navigation, observability guides, and the troubleshooting index with cross-references and quick links.

Changes

Production Incident Runbook

Layer / File(s)	Summary
Trace Incident Runbook Content docs/troubleshooting/trace-incident-runbook.md	New runbook document with symptom-based triage table mapping observable issues to verification steps, including sections for instrumentation boundaries, active scope/root-scope validation, managed tool/LLM call lifecycles, subscriber/exporter registration timing, exporter setup (file/trajectory vs. OpenTelemetry/OpenInference), duplicate event source diagnosis, sanitization-before-export procedure, and escalation capture checklist with data-protection guidance.
Documentation Navigation and References docs/index.md, docs/plugins/observability/about.md, docs/troubleshooting/troubleshooting-guide.md	Updated navigation: added "Debug trace incidents" quick link and toctree entry in index.md; added observability guide pointer to runbook for production trace scenarios; amended troubleshooting guide to direct users to the runbook as first step for trace/scope/export/duplication/sensitive-telemetry incidents.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	Title follows Conventional Commits format with 'docs' type and concise imperative summary, is under 72 characters, and accurately describes the main change of adding a trace incident runbook.
Description check	✅ Passed	Description includes all required sections with substantive content: Overview, Details, and Where should the reviewer start. Both confirmation checkboxes are marked complete, though Related Issues section lacks a specific issue number.
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.

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

_{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/troubleshooting/production-incident-runbook.md`:
- Around line 1-4: The SPDX header in production-incident-runbook.md is split
across lines and must be replaced with the exact single-line SPDX comment
required; update the top of the file to use the single-line header string <!--
SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All
rights reserved. SPDX-License-Identifier: Apache-2.0 --> exactly (including
spacing and punctuation) as the first line so it matches the project lint rule
for Markdown/HTML files.

🪄 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: ASSERTIVE

Plan: Enterprise

Run ID: b7b6f1c5-b846-48ac-ac8c-62539556933b

📥 Commits

Reviewing files that changed from the base of the PR and between 8a04939 and 512d5da.

📒 Files selected for processing (4)

• docs/index.md
• docs/plugins/observability/about.md
• docs/troubleshooting/production-incident-runbook.md
• docs/troubleshooting/troubleshooting-guide.md

📜 Review details

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)

• GitHub Check: Check / Run

🧰 Additional context used

📓 Path-based instructions (19)

**/*.{md,rst,html,txt}

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

**/*.{md,rst,html,txt}: Always spell NVIDIA in all caps. Do not use Nvidia, nvidia, nVidia, nVIDIA, or NV.
Use an NVIDIA before a noun because the name starts with an 'en' sound.
Do not add a registered trademark symbol after NVIDIA when referring to the company.
Use trademark symbols with product names only when the document type or legal guidance requires them.
Verify official capitalization, spacing, and hyphenation for product names.
Precede NVIDIA product names with NVIDIA on first mention when it is natural and accurate.
Do not rewrite product names for grammar or title-case rules.
Preserve third-party product names according to the owner's spelling.
Include the company name and full model qualifier on first use when it helps identify the model.
Preserve the official capitalization and punctuation of model names.
Use shorter family names only after the full name is established.
Spell out a term on first use and put the acronym in parentheses unless the acronym is widely understood by the intended audience.
Use the acronym on later mentions after it has been defined.
For long documents, reintroduce the full term if readers might lose context.
Form plurals of acronyms with s, not an apostrophe, such as GPUs.
In headings, common acronyms can remain abbreviated. Spell out the term in the first or second sentence of the body.
Common terms such as CPU, GPU, PC, API, and UI usually do not need to be spelled out for developer audiences.

Files:

• docs/plugins/observability/about.md
• docs/troubleshooting/troubleshooting-guide.md
• docs/index.md
• docs/troubleshooting/production-incident-runbook.md

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

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

Link the first mention of a product name when the destination helps the reader.

Files:

• docs/plugins/observability/about.md
• docs/troubleshooting/troubleshooting-guide.md
• docs/index.md
• docs/troubleshooting/production-incident-runbook.md

**/*.{html,md}

📄 CodeRabbit inference engine (CONTRIBUTING.md)

Include SPDX license header with format: <!-- SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. SPDX-License-Identifier: Apache-2.0 --> in HTML and Markdown files

Files:

• docs/plugins/observability/about.md
• docs/troubleshooting/troubleshooting-guide.md
• docs/index.md
• docs/troubleshooting/production-incident-runbook.md

**/*.md

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

Documentation must be updated if activation or usage changed

**/*.md: Use title case consistently in technical documentation headings
Avoid quotation marks, ampersands, and exclamation marks in headings
Keep product, event, research, and whitepaper names in their official title case
Use title case for table headers
Do not force social-media sentence case into technical docs
Format code elements, commands, parameters, package names, and expressions in monospace
Format directories, file names, and paths in monospace using backticks
Use angle brackets inside monospace for variables inside paths, such as /home/<username>/.login
Format error messages and strings in quotation marks, keeping literal code strings in code formatting when clearer
Format UI buttons, menus, fields, and labels in bold
Use angle brackets between UI labels for menu paths, such as File > Save As
Use italics for new terms on first use, sparingly and only when introducing the term
Use italics for publication titles
Format keyboard shortcuts in plain text, such as Press Ctrl+Alt+Delete
Use owner/repo link text for GitHub repositories, preferring [NVIDIA/NeMo](link) over prose references like 'the GitHub repo'
Introduce every code block with a complete sentence
Do not make a code block complete the grammar of the previous sentence
Do not continue a sentence after a code block
Use syntax highlighting when the format supports it for code blocks
Avoid the word 'snippet' unless the surrounding docs already use it as a term of art
Keep inline method, function, and class references consistent with nearby docs, omitting empty parentheses for prose readability when no call is shown
Use descriptive anchor text that matches the destination title when possible for links
Avoid raw URLs in running text
Avoid generic anchor text such as 'here,' 'this page,' and 'read more'
Include acronyms in link text when a linked term includes an acronym
Do not link long sentences or multiple sentences
Avoid links ...

Files:

• docs/plugins/observability/about.md
• docs/troubleshooting/troubleshooting-guide.md
• docs/index.md
• docs/troubleshooting/production-incident-runbook.md

{CHANGELOG.md,RELEASING.md,docs/**/*.md}

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

Release history and release notes must reference GitHub Releases, not CHANGELOG.md or docs pages

Files:

• docs/plugins/observability/about.md
• docs/troubleshooting/troubleshooting-guide.md
• docs/index.md
• docs/troubleshooting/production-incident-runbook.md

**/{docs,examples,**/*.md,*.patch,*.diff,.github,*.sh,*.yaml,*.yml}

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

Update documentation, examples, CI configuration, and patch artifacts when performing rename operations

Files:

• docs/plugins/observability/about.md
• docs/troubleshooting/troubleshooting-guide.md
• docs/index.md
• docs/troubleshooting/production-incident-runbook.md

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

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

{**/*.md,**/*.rst,**/*.txt}: Commands, package names, file paths, or APIs must be correct and not stale in documentation
Do not claim support for bindings, features, or workflows in documentation that the repo no longer provides
Examples and procedures must not fail as written in documentation
User-facing naming must be consistent with current repo terminology throughout documentation
NVIDIA must be capitalized correctly in all documentation
Prefer active voice, present tense, and short sentences in documentation
Prefer 'after' over 'once' for temporal references in documentation
Use 'can' instead of 'may' when describing possibility rather than permission in documentation

Files:

• docs/plugins/observability/about.md
• docs/troubleshooting/troubleshooting-guide.md
• docs/index.md
• docs/troubleshooting/production-incident-runbook.md

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

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

{**/*.md,**/*.rst}: Code, commands, paths, and filenames must be formatted as inline code in documentation
Headings in technical documentation must use title case consistently
Code blocks, tables, and lists must be introduced with complete lead-in sentences in documentation
Use descriptive anchor text in links rather than bare URLs or weak labels such as 'here' in documentation
Procedures must use imperative voice and parallel structure in documentation

Files:

• docs/plugins/observability/about.md
• docs/troubleshooting/troubleshooting-guide.md
• docs/index.md
• docs/troubleshooting/production-incident-runbook.md

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

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

Spell NVIDIA in all caps. Do not use Nvidia, nvidia, or NV.

Files:

• docs/plugins/observability/about.md
• docs/troubleshooting/troubleshooting-guide.md
• docs/index.md
• docs/troubleshooting/production-incident-runbook.md

**/*.{md,rst}

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

**/*.{md,rst}: Format commands, code elements, expressions, package names, file names, and paths as inline code.
Use descriptive link text. Avoid raw URLs and weak anchors such as "here" or "read more."
Use title case consistently for technical documentation headings.
Introduce code blocks, lists, tables, and images with complete sentences.
Write procedures as imperative steps. Keep steps parallel and split long procedures into smaller tasks.
Prefer active voice, present tense, short sentences, contractions, and plain English.
Use can for possibility and reserve may for permission.
Use after for temporal relationships instead of once.
Prefer refer to over see when the wording points readers to another resource.
Avoid culture-specific idioms, unnecessary Latinisms, jokes, and marketing exaggeration in technical docs.
Spell out months in body text, avoid ordinal dates, and use clear time zones.
Spell out whole numbers from zero through nine unless they are technical values, parameters, versions, or UI values.
Use numerals for 10 or greater and include commas in thousands.
Do not add trademark symbols to learning-oriented docs unless the source, platform, or legal guidance explicitly requires them.

Files:

• docs/plugins/observability/about.md
• docs/troubleshooting/troubleshooting-guide.md
• docs/index.md
• docs/troubleshooting/production-incident-runbook.md

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

📄 CodeRabbit inference engine (.agents/skills/validate-change/SKILL.md)

{docs/**,README.md,CONTRIBUTING.md}: For docs-only changes, run targeted checks only if commands, package names, or examples changed. Use just docs for docs-site builds and just docs-linkcheck when links changed
Run docs site build with just docs

Files:

• docs/plugins/observability/about.md
• docs/troubleshooting/troubleshooting-guide.md
• docs/index.md
• docs/troubleshooting/production-incident-runbook.md

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

📄 CodeRabbit inference engine (.agents/skills/validate-change/SKILL.md)

Run docs link validation with just docs-linkcheck when links change

Files:

• docs/plugins/observability/about.md
• docs/troubleshooting/troubleshooting-guide.md
• docs/index.md
• docs/troubleshooting/production-incident-runbook.md

{docs/**,README.md}

📄 CodeRabbit inference engine (.agents/skills/validate-change/SKILL.md)

Verify README and docs entry points still match current package names and paths for large or public-facing changes

Files:

• docs/plugins/observability/about.md
• docs/troubleshooting/troubleshooting-guide.md
• docs/index.md
• docs/troubleshooting/production-incident-runbook.md

{docs/**,examples/**,README.md}

📄 CodeRabbit inference engine (.agents/skills/validate-change/SKILL.md)

Verify examples still run with documented commands for large or public-facing changes

Files:

• docs/plugins/observability/about.md
• docs/troubleshooting/troubleshooting-guide.md
• docs/index.md
• docs/troubleshooting/production-incident-runbook.md

{docs/**,README.md,**/Cargo.toml,**/package.json,**/*.md}

📄 CodeRabbit inference engine (.agents/skills/validate-change/SKILL.md)

Ensure renamed public surfaces are reflected consistently in manifests and docs for large or public-facing changes

Files:

• docs/plugins/observability/about.md
• docs/troubleshooting/troubleshooting-guide.md
• docs/index.md
• docs/troubleshooting/production-incident-runbook.md

**/*.{rs,py,js,ts,tsx,jsx,go,sh,bash,yml,yaml,toml,json,md,mjs,cjs}

📄 CodeRabbit inference engine (AGENTS.md)

Keep SPDX headers on source, docs, scripts, and configuration files. The project is Apache-2.0.

Files:

• docs/plugins/observability/about.md
• docs/troubleshooting/troubleshooting-guide.md
• docs/index.md
• docs/troubleshooting/production-incident-runbook.md

{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/plugins/observability/about.md
• docs/troubleshooting/troubleshooting-guide.md
• docs/index.md
• docs/troubleshooting/production-incident-runbook.md

{README.md,docs/index.md}

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

{README.md,docs/index.md}: Update entry-point docs when examples or reading paths change
README.md or docs/index.md must be updated when entry points change

Files:

• docs/index.md

{README.md,docs/index.md,**/README.md,python/*/README.md,crates/*/README.md}

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

Update entry-point documentation including README.md, docs/index.md, package or crate READMEs, and binding-level source READMEs when public behavior changes

Files:

• docs/index.md

🪛 LanguageTool

docs/troubleshooting/production-incident-runbook.md

[style] ~52-~52: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...tive scope and root scope ownership. 3. Confirm managed tool and LLM calls. 4. Confirm ...

(ENGLISH_WORD_REPEAT_BEGINNING_RULE)

---

[style] ~53-~53: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ... Confirm managed tool and LLM calls. 4. Confirm subscriber or exporter registration tim...

(ENGLISH_WORD_REPEAT_BEGINNING_RULE)

---

[style] ~54-~54: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...ber or exporter registration timing. 5. Confirm exporter endpoint, environment, and flu...

(ENGLISH_WORD_REPEAT_BEGINNING_RULE)

---

[style] ~55-~55: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...nt, environment, and flush behavior. 6. Confirm sanitization before export. ## Confirm...

(ENGLISH_WORD_REPEAT_BEGINNING_RULE)

---

[style] ~57-~57: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...Confirm sanitization before export. ## Confirm Instrumentation Boundary Start with th...

(ENGLISH_WORD_REPEAT_BEGINNING_RULE)

🔇 Additional comments (4)

docs/troubleshooting/production-incident-runbook.md (1)

6-211: LGTM!

docs/index.md (1)

71-71: LGTM!

Also applies to: 274-274

docs/plugins/observability/about.md (1)

63-65: LGTM!

docs/troubleshooting/troubleshooting-guide.md (1)

10-12: LGTM!

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (3)

docs/index.md (1)

1-4: ⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Use The Required Single-Line SPDX Header

Replace the multi-line SPDX comment with the exact single-line header format required for Markdown files.

Proposed fix

-<!--
-SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
-SPDX-License-Identifier: Apache-2.0
--->
+<!-- SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. SPDX-License-Identifier: Apache-2.0 -->

As per coding guidelines, "**/*.{html,md}: Include SPDX license header with format: <!-- SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. SPDX-License-Identifier: Apache-2.0 --> in HTML and Markdown files."

🤖 Prompt for 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.

In `@docs/index.md` around lines 1 - 4, Replace the existing multi-line SPDX
comment block containing "SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA
CORPORATION & AFFILIATES. All rights reserved." and "SPDX-License-Identifier:
Apache-2.0" with the single-line SPDX header required for Markdown: <!--
SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All
rights reserved. SPDX-License-Identifier: Apache-2.0 -->; ensure this exact
string replaces the multi-line block in the file (search for the multi-line SPDX
comment to locate the spot).

docs/troubleshooting/troubleshooting-guide.md (1)

1-4: ⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Use The Required Single-Line SPDX Header

This Markdown file still uses a multi-line SPDX block instead of the required single-line form.

Proposed fix

-<!--
-SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
-SPDX-License-Identifier: Apache-2.0
--->
+<!-- SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. SPDX-License-Identifier: Apache-2.0 -->

As per coding guidelines, "**/*.{html,md}: Include SPDX license header with format: <!-- SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. SPDX-License-Identifier: Apache-2.0 --> in HTML and Markdown files."

🤖 Prompt for 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.

In `@docs/troubleshooting/troubleshooting-guide.md` around lines 1 - 4, The file
currently contains a multi-line SPDX comment block; replace it with the required
single-line SPDX header comment exactly as specified: <!--
SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All
rights reserved. SPDX-License-Identifier: Apache-2.0 --> so the Markdown file
uses the single-line SPDX header format; update the top of the document to
remove the multi-line block and insert that single-line header.

docs/plugins/observability/about.md (1)

1-4: ⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Use The Required Single-Line SPDX Header

The SPDX header is currently multi-line; this file needs the mandated single-line SPDX comment.

Proposed fix

-<!--
-SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
-SPDX-License-Identifier: Apache-2.0
--->
+<!-- SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. SPDX-License-Identifier: Apache-2.0 -->

As per coding guidelines, "**/*.{html,md}: Include SPDX license header with format: <!-- SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. SPDX-License-Identifier: Apache-2.0 --> in HTML and Markdown files."

🤖 Prompt for 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.

In `@docs/plugins/observability/about.md` around lines 1 - 4, Replace the current
multi-line SPDX comment at the top of docs/plugins/observability/about.md with
the single-line SPDX header required by policy: ensure the file begins with a
single HTML/Markdown comment containing both the SPDX-FileCopyrightText and
SPDX-License-Identifier on one line (the exact text should match the org policy:
"SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES.
All rights reserved. SPDX-License-Identifier: Apache-2.0").

🤖 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.

Outside diff comments:
In `@docs/index.md`:
- Around line 1-4: Replace the existing multi-line SPDX comment block containing
"SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES.
All rights reserved." and "SPDX-License-Identifier: Apache-2.0" with the
single-line SPDX header required for Markdown: <!-- SPDX-FileCopyrightText:
Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
SPDX-License-Identifier: Apache-2.0 -->; ensure this exact string replaces the
multi-line block in the file (search for the multi-line SPDX comment to locate
the spot).

In `@docs/plugins/observability/about.md`:
- Around line 1-4: Replace the current multi-line SPDX comment at the top of
docs/plugins/observability/about.md with the single-line SPDX header required by
policy: ensure the file begins with a single HTML/Markdown comment containing
both the SPDX-FileCopyrightText and SPDX-License-Identifier on one line (the
exact text should match the org policy: "SPDX-FileCopyrightText: Copyright (c)
2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
SPDX-License-Identifier: Apache-2.0").

In `@docs/troubleshooting/troubleshooting-guide.md`:
- Around line 1-4: The file currently contains a multi-line SPDX comment block;
replace it with the required single-line SPDX header comment exactly as
specified: <!-- SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION &
AFFILIATES. All rights reserved. SPDX-License-Identifier: Apache-2.0 --> so the
Markdown file uses the single-line SPDX header format; update the top of the
document to remove the multi-line block and insert that single-line header.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Enterprise

Run ID: 1e96840d-0051-43c6-ae0a-9bc4962199c5

📥 Commits

Reviewing files that changed from the base of the PR and between 512d5da and bcf1d44.

📒 Files selected for processing (4)

• docs/index.md
• docs/plugins/observability/about.md
• docs/troubleshooting/trace-incident-runbook.md
• docs/troubleshooting/troubleshooting-guide.md

📜 Review details

🧰 Additional context used

📓 Path-based instructions (19)

**/*.{md,rst,html,txt}

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

**/*.{md,rst,html,txt}: Always spell NVIDIA in all caps. Do not use Nvidia, nvidia, nVidia, nVIDIA, or NV.
Use an NVIDIA before a noun because the name starts with an 'en' sound.
Do not add a registered trademark symbol after NVIDIA when referring to the company.
Use trademark symbols with product names only when the document type or legal guidance requires them.
Verify official capitalization, spacing, and hyphenation for product names.
Precede NVIDIA product names with NVIDIA on first mention when it is natural and accurate.
Do not rewrite product names for grammar or title-case rules.
Preserve third-party product names according to the owner's spelling.
Include the company name and full model qualifier on first use when it helps identify the model.
Preserve the official capitalization and punctuation of model names.
Use shorter family names only after the full name is established.
Spell out a term on first use and put the acronym in parentheses unless the acronym is widely understood by the intended audience.
Use the acronym on later mentions after it has been defined.
For long documents, reintroduce the full term if readers might lose context.
Form plurals of acronyms with s, not an apostrophe, such as GPUs.
In headings, common acronyms can remain abbreviated. Spell out the term in the first or second sentence of the body.
Common terms such as CPU, GPU, PC, API, and UI usually do not need to be spelled out for developer audiences.

Files:

• docs/plugins/observability/about.md
• docs/index.md
• docs/troubleshooting/trace-incident-runbook.md
• docs/troubleshooting/troubleshooting-guide.md

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

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

Link the first mention of a product name when the destination helps the reader.

Files:

• docs/plugins/observability/about.md
• docs/index.md
• docs/troubleshooting/trace-incident-runbook.md
• docs/troubleshooting/troubleshooting-guide.md

**/*.{html,md}

📄 CodeRabbit inference engine (CONTRIBUTING.md)

Include SPDX license header with format: <!-- SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. SPDX-License-Identifier: Apache-2.0 --> in HTML and Markdown files

Files:

• docs/plugins/observability/about.md
• docs/index.md
• docs/troubleshooting/trace-incident-runbook.md
• docs/troubleshooting/troubleshooting-guide.md

**/*.md

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

Documentation must be updated if activation or usage changed

**/*.md: Use title case consistently in technical documentation headings
Avoid quotation marks, ampersands, and exclamation marks in headings
Keep product, event, research, and whitepaper names in their official title case
Use title case for table headers
Do not force social-media sentence case into technical docs
Format code elements, commands, parameters, package names, and expressions in monospace
Format directories, file names, and paths in monospace using backticks
Use angle brackets inside monospace for variables inside paths, such as /home/<username>/.login
Format error messages and strings in quotation marks, keeping literal code strings in code formatting when clearer
Format UI buttons, menus, fields, and labels in bold
Use angle brackets between UI labels for menu paths, such as File > Save As
Use italics for new terms on first use, sparingly and only when introducing the term
Use italics for publication titles
Format keyboard shortcuts in plain text, such as Press Ctrl+Alt+Delete
Use owner/repo link text for GitHub repositories, preferring [NVIDIA/NeMo](link) over prose references like 'the GitHub repo'
Introduce every code block with a complete sentence
Do not make a code block complete the grammar of the previous sentence
Do not continue a sentence after a code block
Use syntax highlighting when the format supports it for code blocks
Avoid the word 'snippet' unless the surrounding docs already use it as a term of art
Keep inline method, function, and class references consistent with nearby docs, omitting empty parentheses for prose readability when no call is shown
Use descriptive anchor text that matches the destination title when possible for links
Avoid raw URLs in running text
Avoid generic anchor text such as 'here,' 'this page,' and 'read more'
Include acronyms in link text when a linked term includes an acronym
Do not link long sentences or multiple sentences
Avoid links ...

Files:

• docs/plugins/observability/about.md
• docs/index.md
• docs/troubleshooting/trace-incident-runbook.md
• docs/troubleshooting/troubleshooting-guide.md

{CHANGELOG.md,RELEASING.md,docs/**/*.md}

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

Release history and release notes must reference GitHub Releases, not CHANGELOG.md or docs pages

Files:

• docs/plugins/observability/about.md
• docs/index.md
• docs/troubleshooting/trace-incident-runbook.md
• docs/troubleshooting/troubleshooting-guide.md

**/{docs,examples,**/*.md,*.patch,*.diff,.github,*.sh,*.yaml,*.yml}

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

Update documentation, examples, CI configuration, and patch artifacts when performing rename operations

Files:

• docs/plugins/observability/about.md
• docs/index.md
• docs/troubleshooting/trace-incident-runbook.md
• docs/troubleshooting/troubleshooting-guide.md

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

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

{**/*.md,**/*.rst,**/*.txt}: Commands, package names, file paths, or APIs must be correct and not stale in documentation
Do not claim support for bindings, features, or workflows in documentation that the repo no longer provides
Examples and procedures must not fail as written in documentation
User-facing naming must be consistent with current repo terminology throughout documentation
NVIDIA must be capitalized correctly in all documentation
Prefer active voice, present tense, and short sentences in documentation
Prefer 'after' over 'once' for temporal references in documentation
Use 'can' instead of 'may' when describing possibility rather than permission in documentation

Files:

• docs/plugins/observability/about.md
• docs/index.md
• docs/troubleshooting/trace-incident-runbook.md
• docs/troubleshooting/troubleshooting-guide.md

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

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

{**/*.md,**/*.rst}: Code, commands, paths, and filenames must be formatted as inline code in documentation
Headings in technical documentation must use title case consistently
Code blocks, tables, and lists must be introduced with complete lead-in sentences in documentation
Use descriptive anchor text in links rather than bare URLs or weak labels such as 'here' in documentation
Procedures must use imperative voice and parallel structure in documentation

Files:

• docs/plugins/observability/about.md
• docs/index.md
• docs/troubleshooting/trace-incident-runbook.md
• docs/troubleshooting/troubleshooting-guide.md

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

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

Spell NVIDIA in all caps. Do not use Nvidia, nvidia, or NV.

Files:

• docs/plugins/observability/about.md
• docs/index.md
• docs/troubleshooting/trace-incident-runbook.md
• docs/troubleshooting/troubleshooting-guide.md

**/*.{md,rst}

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

**/*.{md,rst}: Format commands, code elements, expressions, package names, file names, and paths as inline code.
Use descriptive link text. Avoid raw URLs and weak anchors such as "here" or "read more."
Use title case consistently for technical documentation headings.
Introduce code blocks, lists, tables, and images with complete sentences.
Write procedures as imperative steps. Keep steps parallel and split long procedures into smaller tasks.
Prefer active voice, present tense, short sentences, contractions, and plain English.
Use can for possibility and reserve may for permission.
Use after for temporal relationships instead of once.
Prefer refer to over see when the wording points readers to another resource.
Avoid culture-specific idioms, unnecessary Latinisms, jokes, and marketing exaggeration in technical docs.
Spell out months in body text, avoid ordinal dates, and use clear time zones.
Spell out whole numbers from zero through nine unless they are technical values, parameters, versions, or UI values.
Use numerals for 10 or greater and include commas in thousands.
Do not add trademark symbols to learning-oriented docs unless the source, platform, or legal guidance explicitly requires them.

Files:

• docs/plugins/observability/about.md
• docs/index.md
• docs/troubleshooting/trace-incident-runbook.md
• docs/troubleshooting/troubleshooting-guide.md

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

📄 CodeRabbit inference engine (.agents/skills/validate-change/SKILL.md)

{docs/**,README.md,CONTRIBUTING.md}: For docs-only changes, run targeted checks only if commands, package names, or examples changed. Use just docs for docs-site builds and just docs-linkcheck when links changed
Run docs site build with just docs

Files:

• docs/plugins/observability/about.md
• docs/index.md
• docs/troubleshooting/trace-incident-runbook.md
• docs/troubleshooting/troubleshooting-guide.md

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

📄 CodeRabbit inference engine (.agents/skills/validate-change/SKILL.md)

Run docs link validation with just docs-linkcheck when links change

Files:

• docs/plugins/observability/about.md
• docs/index.md
• docs/troubleshooting/trace-incident-runbook.md
• docs/troubleshooting/troubleshooting-guide.md

{docs/**,README.md}

📄 CodeRabbit inference engine (.agents/skills/validate-change/SKILL.md)

Verify README and docs entry points still match current package names and paths for large or public-facing changes

Files:

• docs/plugins/observability/about.md
• docs/index.md
• docs/troubleshooting/trace-incident-runbook.md
• docs/troubleshooting/troubleshooting-guide.md

{docs/**,examples/**,README.md}

📄 CodeRabbit inference engine (.agents/skills/validate-change/SKILL.md)

Verify examples still run with documented commands for large or public-facing changes

Files:

• docs/plugins/observability/about.md
• docs/index.md
• docs/troubleshooting/trace-incident-runbook.md
• docs/troubleshooting/troubleshooting-guide.md

{docs/**,README.md,**/Cargo.toml,**/package.json,**/*.md}

📄 CodeRabbit inference engine (.agents/skills/validate-change/SKILL.md)

Ensure renamed public surfaces are reflected consistently in manifests and docs for large or public-facing changes

Files:

• docs/plugins/observability/about.md
• docs/index.md
• docs/troubleshooting/trace-incident-runbook.md
• docs/troubleshooting/troubleshooting-guide.md

**/*.{rs,py,js,ts,tsx,jsx,go,sh,bash,yml,yaml,toml,json,md,mjs,cjs}

📄 CodeRabbit inference engine (AGENTS.md)

Keep SPDX headers on source, docs, scripts, and configuration files. The project is Apache-2.0.

Files:

• docs/plugins/observability/about.md
• docs/index.md
• docs/troubleshooting/trace-incident-runbook.md
• docs/troubleshooting/troubleshooting-guide.md

{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/plugins/observability/about.md
• docs/index.md
• docs/troubleshooting/trace-incident-runbook.md
• docs/troubleshooting/troubleshooting-guide.md

{README.md,docs/index.md}

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

{README.md,docs/index.md}: Update entry-point docs when examples or reading paths change
README.md or docs/index.md must be updated when entry points change

Files:

• docs/index.md

{README.md,docs/index.md,**/README.md,python/*/README.md,crates/*/README.md}

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

Update entry-point documentation including README.md, docs/index.md, package or crate READMEs, and binding-level source READMEs when public behavior changes

Files:

• docs/index.md

🔇 Additional comments (1)

docs/troubleshooting/trace-incident-runbook.md (1)

1-4: SPDX Header Format Is Still Non-Compliant

This is still using a multi-line SPDX block instead of the required single-line header and was already reported earlier.

[willkill07]

/merge