Add vMCP observability guide

Document how to enable OpenTelemetry traces and metrics for Virtual MCP
Server, including configuration options and an example for exporting to
an OpenTelemetry Collector.

Closes #380

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: jerm-dro

docs/toolhive/guides-vmcp/observability.mdx

@@ -0,0 +1,120 @@
+---
+title: Observability
+description:
+  How to enable OpenTelemetry traces and metrics for Virtual MCP Server.
+---
+
+Virtual MCP Server (vMCP) provides comprehensive observability through
+OpenTelemetry instrumentation. You can export traces and metrics to monitor
+backend operations and workflow executions.
+
+## Telemetry types
+
+vMCP supports two types of telemetry:
+
+- **Traces**: Track requests across vMCP and its backends, showing the full path
+  of tool calls, resource reads, and workflow executions
+- **Metrics**: Counters and histograms for backend request rates, error rates,
+  and latency distributions
+
+For general ToolHive observability concepts including trace structure and
+metrics, see the [observability overview](../concepts/observability.mdx).
+
+## Enable telemetry
+
+Configure telemetry in the VirtualMCPServer resource using the
+`spec.config.telemetry` field:
+
+```yaml
+apiVersion: toolhive.stacklok.dev/v1alpha1
+kind: VirtualMCPServer
+metadata:
+  name: my-vmcp
+  namespace: toolhive-system
+spec:
+  config:
+    groupRef: my-group
+    # highlight-start
+    telemetry:
+      endpoint: 'otel-collector:4317'
+      serviceName: 'my-vmcp'
+      insecure: true
+      tracingEnabled: true
+      samplingRate: '0.1'
+      metricsEnabled: true
+      enablePrometheusMetricsPath: true
+    # highlight-end
+  incomingAuth:
+    type: anonymous
+```
+
+### Configuration options
+
+| Field                         | Description                             | Default               |
+| ----------------------------- | --------------------------------------- | --------------------- |
+| `endpoint`                    | OTLP collector endpoint (hostname:port) | -                     |
+| `serviceName`                 | Service name in traces and metrics      | VirtualMCPServer name |
+| `tracingEnabled`              | Enable tracing                          | `false`               |
+| `metricsEnabled`              | Enable OTLP metrics export              | `false`               |
+| `samplingRate`                | Trace sampling rate (0.0-1.0)           | `"0.05"`              |
+| `insecure`                    | Use HTTP instead of HTTPS               | `false`               |
+| `enablePrometheusMetricsPath` | Expose `/metrics` endpoint              | `false`               |
+
+## Export to observability backends
+
+### Export to Jaeger via OpenTelemetry Collector
+
+Deploy an OpenTelemetry Collector configured to export to Jaeger:
+
+```yaml title="otel-collector-config.yaml"
+config:
+  receivers:
+    otlp:
+      protocols:
+        grpc:
+          endpoint: 0.0.0.0:4317
+        http:
+          endpoint: 0.0.0.0:4318
+
+  exporters:
+    otlp/jaeger:
+      endpoint: http://jaeger-collector:4317
+
+  service:
+    pipelines:
+      traces:
+        receivers: [otlp]
+        processors: [batch]
+        exporters: [otlp/jaeger]
+      metrics:
+        receivers: [otlp]
+        processors: [batch]
+        exporters: [prometheus]
+```
+
+Then configure vMCP to send telemetry to the collector:
+
+```yaml
+spec:
+  config:
+    telemetry:
+      endpoint: 'otel-collector:4317'
+      serviceName: 'production-vmcp'
+      tracingEnabled: true
+      metricsEnabled: true
+      insecure: true
+```
+
+## Prometheus metrics
+
+Enable Prometheus scraping by setting `enablePrometheusMetricsPath: true`.
+Metrics are exposed on the vMCP service port (4483) at `/metrics`.
+
+## Related information
+
+- [Observability concepts](../concepts/observability.mdx) - Overview of
+  ToolHive's observability architecture
+- [Kubernetes telemetry guide](../guides-k8s/telemetry-and-metrics.mdx) -
+  Telemetry for MCPServer resources
+- [OpenTelemetry tutorial](../tutorials/opentelemetry.mdx) - Set up a local
+  observability stack

sidebars.ts

@@ -181,6 +181,7 @@ const sidebars: SidebarsConfig = {
         'toolhive/guides-vmcp/authentication',
         'toolhive/guides-vmcp/tool-aggregation',
         'toolhive/guides-vmcp/composite-tools',
+        'toolhive/guides-vmcp/observability',
       ],
     },