docs: document traceparent propagation

[Kilerd]

Summary

• Add a standalone API observability page for W3C traceparent support across Fish Audio inference APIs.
• Document how to bind business-side and inference-side traces with the same trace ID.
• Mark enterprise-only trace-based performance analysis in an Info callout.
• Keep concrete endpoint API reference pages free of tracing callouts; the API reference navigation and introduction point to the standalone page.
• Update the raw API skill with a single link to the standalone tracing page.

Validation

• npm run check:openapi
• git diff --check
• npx prettier --check api-reference/observability.mdx
• npx mint broken-links (fails on pre-existing skill/temp links unrelated to this PR)

Summary by CodeRabbit

Documentation

• Added distributed tracing documentation for inference APIs
• Documents support for W3C traceparent header to correlate Fish Audio spans with application traces
• Includes end-to-end instructions with examples for REST, OpenTelemetry (Python and Node.js), and WebSocket
• Added enterprise trace-based performance analysis capabilities

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
hanabiaiinc	🟢 Ready	View Preview	Jun 17, 2026, 3:47 AM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds a new api-reference/observability.mdx documentation page covering W3C traceparent header support for Fish Audio REST and WebSocket inference APIs, including OpenTelemetry examples for Python and Node.js and an enterprise tracing section. The page is registered in docs.json navigation, cross-referenced from api-reference/introduction.mdx, and noted in the Mintlify skill file.

Changes

Distributed Tracing Documentation

Layer / File(s)	Summary
Navigation and cross-references docs.json, api-reference/introduction.mdx, .mintlify/skills/fish-audio-api/SKILL.md	Registers api-reference/observability in the API Reference navigation tab, adds a "Distributed Tracing" section in the introduction page linking to the new page, and appends a global-facts note about optional distributed tracing in the skill file.
Observability page: overview, header format, and integration guide api-reference/observability.mdx	Defines page frontmatter, documents supported REST/WebSocket endpoints and traceparent fallback behavior (missing/invalid → new trace), specifies the W3C traceparent header format with a concrete example, and provides step-by-step instructions for binding application traces across multiple calls while refreshing span/parent IDs per request.
Observability page: code examples and enterprise section api-reference/observability.mdx	Adds a REST curl example for POST /v1/tts, OpenTelemetry examples in Python and Node.js using context propagation/injection, WebSocket upgrade header usage with a browser-limitation note, and an enterprise performance analysis section with guidance on avoiding sensitive data in trace IDs and span names.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~5 minutes

Possibly related PRs

• fishaudio/docs#70: Modifies the same .mintlify/skills/fish-audio-api/SKILL.md file; this PR adds a distributed-tracing global-facts line on top of the skill content established in that earlier PR.

Poem

🐇 A traceparent header, oh what a delight,
Spans hopping through REST and WebSocket at night,
From Python to Node.js, the context flows free,
Each inference call traced for the devs to see,
No sensitive data, the bunny says "beware!" 🐾

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately and concisely summarizes the main change—adding documentation for traceparent propagation support across Fish Audio APIs.
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
• Commit unit tests in branch codex/document-traceparent-support

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[coderabbitai]

🧹 Nitpick comments (1)

api-reference/observability.mdx (1)

8-22: ⚡ Quick win

Consider adding an explicit prerequisites section for clarity.

The documentation assumes readers have an active distributed trace setup and understand trace context propagation. While the integration instructions (lines 47–60) implicitly cover this, adding a short prerequisites or "Before you begin" section would help users quickly assess whether this feature applies to their use case.

Example:

• You have a distributed tracing system in place (e.g., OpenTelemetry, Datadog, Jaeger, etc.)
• Your application already creates and maintains a trace context for workflows
• You use an OpenTelemetry SDK or similar instrumentation

🤖 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 `@api-reference/observability.mdx` around lines 8 - 22, Add a new
"Prerequisites" or "Before you begin" section to the documentation after the
introductory paragraph and before the "Supported inference surfaces" list. This
section should explicitly outline the requirements for using trace context
propagation, including that users need a distributed tracing system in place
(such as OpenTelemetry, Datadog, or Jaeger), their application must already
create and maintain trace context for workflows, and they should be using an
OpenTelemetry SDK or similar instrumentation. This will help users quickly
determine if this feature is applicable to their setup without having to read
through the integration examples.

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

Nitpick comments:
In `@api-reference/observability.mdx`:
- Around line 8-22: Add a new "Prerequisites" or "Before you begin" section to
the documentation after the introductory paragraph and before the "Supported
inference surfaces" list. This section should explicitly outline the
requirements for using trace context propagation, including that users need a
distributed tracing system in place (such as OpenTelemetry, Datadog, or Jaeger),
their application must already create and maintain trace context for workflows,
and they should be using an OpenTelemetry SDK or similar instrumentation. This
will help users quickly determine if this feature is applicable to their setup
without having to read through the integration examples.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: c5dff377-293e-46f6-b67c-92c25e860a8f

📥 Commits

Reviewing files that changed from the base of the PR and between ea2caf8 and 9d1b1fb.

📒 Files selected for processing (4)

• .mintlify/skills/fish-audio-api/SKILL.md
• api-reference/introduction.mdx
• api-reference/observability.mdx
• docs.json