Update OTel docs to match current implementation

[ChrisJBurns]

Summary

• Update observability concept docs to use new OpenTelemetry semantic convention attribute names (http.request.method, mcp.method.name, gen_ai.tool.name, etc.) instead of legacy names
• Add vMCP-specific metrics documentation (backend, workflow, and optimizer metrics) to the vMCP telemetry guide
• Add --otel-use-legacy-attributes flag to CLI telemetry guide and fix default service name
• Add MCP semantic convention metrics (mcp.server.operation.duration, mcp.client.operation.duration) and trace context propagation section to concepts page

Test plan

• Verify the site builds successfully
• Review attribute names against ToolHive source code in pkg/telemetry/
• Confirm vMCP metrics match pkg/vmcp/server/telemetry.go
• Check cross-references between pages resolve correctly

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
docs-website	Ready	Preview, Comment	Mar 11, 2026 2:35pm

[Copilot]

Pull request overview

Updates ToolHive observability documentation to align with the current OpenTelemetry attribute/metric naming scheme, and expands vMCP telemetry guidance so users can more easily interpret traces and metrics across ToolHive and vMCP deployments.

Changes:

• Updated trace attribute examples to use newer OTel semantic convention attribute names (HTTP/MCP/GenAI).
• Added vMCP-specific metrics sections (backend/workflow/optimizer) and expanded distributed tracing details.
• Updated CLI telemetry docs to include --otel-use-legacy-attributes and corrected the documented default service name.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.

File	Description
docs/toolhive/guides-vmcp/telemetry-and-metrics.mdx	Adds vMCP metric inventories and tracing span naming/attributes; updates sampling example.
docs/toolhive/guides-cli/telemetry-and-metrics.mdx	Documents default service name, adds --otel-use-legacy-attributes flag to usage + table.
docs/toolhive/concepts/observability.mdx	Refreshes trace/attribute examples, adds MCP semantic-convention metrics + trace context propagation section.

[danbarr]

Two accuracy issues to address before merge:

1. mcp.is_batch: false in trace example

In concepts/observability.mdx, the MCP protocol details code block shows mcp.is_batch: false. The code only emits this attribute when IsBatch == true (middleware.go:358-359) — it won't appear in typical traces. Remove it from the example or add a note that it only appears for batch requests.

2. initialize span: mcp.client.name silently dropped

The PR replaces mcp.client.name with mcp.protocol.version in the method-specific attributes for initialize spans. But mcp.client.name is always emitted for initialize spans — it is not gated by UseLegacyAttributes (middleware.go:436-439). The operator docs from #3784 still list it. Either keep mcp.client.name alongside mcp.protocol.version, or clarify that it is a ToolHive-specific attribute that is always emitted.

🤖 Generated with Claude Code