[DOCS] Document W3C trace context propagation to subprocesses and OTLP span ingestion

[edenreich]

Summary

inference-gateway/cli#909 (closes inference-gateway/cli#904) makes subprocess and remote-agent tracing cooperative and open-standard. The propagation contract is user-facing and undocumented.

Behavior to document (all gated on telemetry.enabled: true):

• Env vars for subprocesses: the Bash tool (and therefore skill scripts) and headless subagents receive TRACEPARENT/TRACESTATE (W3C Trace Context, parented on the current execute_tool span) and BAGGAGE (W3C Baggage: infer.session.id, infer.tool.call.id). Nothing is set when telemetry is disabled.
• Span reporting is standard OTLP, chosen automatically:
  • telemetry.otlp.endpoint configured: the endpoint and headers are passed through to the child env (OTEL_EXPORTER_OTLP_ENDPOINT/OTEL_EXPORTER_OTLP_HEADERS) so child spans stitch in the remote backend.
  • No endpoint (the default): the CLI runs an ephemeral localhost OTLP/HTTP receiver per session and points children at it; received spans are persisted into the local per-session trace store and appear in infer traces / /traces nested under the tool span.
• Any OTel-instrumented tool works with zero custom code. Example with otel-cli inside a Bash tool call:

otel-cli exec --name "go test" -- go test ./...

The resulting span shows up as a child of execute_tool Bash in infer traces.

• Subagents: infer agent honors an inherited TRACEPARENT, so a subagent session nests under the caller's execute_tool Agent span - one cross-process trace:

session (standard, success)            152ms
|-- execute_tool Agent                  89ms
|   `-- session (readonly, success)     52ms
|       `-- chat openai/gpt-4o          13ms

• Remote A2A agents: outbound A2A requests carry traceparent/tracestate/baggage HTTP headers. Context-out only: remote spans stitch via a shared collector, not the local store.
• Limitations worth stating: interactive (tmux-pane) subagents are not stitched; detached background shells that outlive the CLI lose late spans.

Affected pages:

• Telemetry/observability page: the propagation contract, the env vars, the local-first/remote-optional sink selection, the otel-cli and OTel SDK examples.
• Agent/subagent docs: cross-process trace nesting.
• infer traces reference (see [DOCS] Document infer traces command and /traces shortcut #390): mention that ingested child spans appear in the tree.

Source: inference-gateway/cli#909, inference-gateway/cli#904. Related: #390.

Acceptance Criteria

• The telemetry docs document TRACEPARENT/TRACESTATE/BAGGAGE propagation to subprocesses and the OTLP sink selection (configured endpoint passthrough vs local ephemeral receiver).
• An otel-cli example and an OTel SDK note show third-party spans landing in infer traces.
• Subagent trace nesting and the A2A HTTP header propagation are documented, including the shared-collector requirement for remote spans.

[edenreich]

@claude Can you work on this?

[inference-gateway-maintainer]

Claude finished @edenreich's task in 10m 4s —— View job • docs/issue-391-20260714-1200 • [Create PR ➔](https://github.com/inference-gateway/docs/compare/main...docs/issue-391-20260714-1200?quick_pull=1&title=Issue%20%23391%3A%20Changes%20from%20Claude&body=This%20PR%20addresses%20issue%20%23391%0A%0AGenerated%20with%20%5BClaude%20Code%5D(https%3A%2F%2Fclaude.ai%2Fcode)

---

Done

Documented the W3C trace context propagation contract and OTLP span ingestion (from inference-gateway/cli#909) across the CLI and Observability docs.

• Gather context: read observability, CLI/traces, and agent/subagent docs
• Understand the propagation contract from the issue
• Document TRACEPARENT/TRACESTATE/BAGGAGE propagation + OTLP sink selection (CLI Telemetry)
• Add otel-cli example and OTel SDK note (spans landing in infer traces)
• Document subagent trace nesting + A2A HTTP header propagation (shared-collector requirement)
• Cross-reference infer traces output showing ingested child spans
• Summarize the propagation contract on the Observability page
• Lint/format/build checks
• Commit and open PR

PR: #394

What changed

cli.md (Telemetry reference - the authoritative CLI telemetry home):

• New Trace context propagation to subprocesses section covering:
  • The TRACEPARENT/TRACESTATE/BAGGAGE env vars set for the Bash tool, skill scripts, and headless subagents (with a table), gated on telemetry.enabled: true.
  • Automatic OTLP sink selection - configured telemetry.otlp.endpoint passthrough (OTEL_EXPORTER_OTLP_ENDPOINT/OTEL_EXPORTER_OTLP_HEADERS) vs. the default local ephemeral OTLP/HTTP receiver that persists child spans into the per-session trace store.
  • An otel-cli exec example plus an OTel SDK note showing third-party spans nest under execute_tool Bash in infer traces.
  • Subagent cross-process nesting, A2A traceparent/tracestate/baggage HTTP headers with the shared-collector requirement for remote spans, and the tmux/detached-shell limitations.
• Notes added to the Traces, Viewing traces, and Local Subagents subsections so ingested subprocess/subagent spans are cross-referenced where readers already look.

observability.md (CLI Telemetry section):

• Condensed summary of the same contract, linking to the full CLI reference.

Verification

bun run format:check, bun run lint:md, and bun run build all pass. All new internal anchors resolve.

Notes

• Content lives primarily in cli.md because that is the authoritative CLI telemetry reference (it also hosts infer traces and the Local Subagents docs), with a concise pointer summary on the Observability page. No provider-generated regions were touched.
• Roadmap board (project [TASK] Please update the docs with the latest features of the Inference Gateway #7) moved to QA.
  | Branch: docs/issue-391-20260714-1200 | PR #394