add tracing information to AIBridge documentation

coder · pawbana · Dec 5, 2025 · Dec 2, 2025 · Dec 5, 2025 · Dec 5, 2025
commit a4d05956ab9fd970a0e113ff08085ed175e8e328
diff --git a/docs/ai-coder/ai-bridge/monitoring.md b/docs/ai-coder/ai-bridge/monitoring.md
@@ -60,3 +60,68 @@ needs.
 
 For configuration options and details, see [Data Retention](./setup.md#data-retention)
 in the AI Bridge setup guide.
+
+## Tracing
+
+AI Bridge supports tracing via [OpenTelemetry](https://opentelemetry.io/),
+providing visibility into request processing, upstream API calls, and MCP server
+interactions.
+
+### Enabling Tracing
+
+AI Bridge tracing is enabled when tracing is enabled for the Coder server.
+To enable tracing set `CODER_TRACE_ENABLE` environment variable or
+[--trace](https://coder.com/docs/reference/cli/server#--trace) CLI flag:
+
+```sh
+export CODER_TRACE_ENABLE=true
+```
+
+```sh
+coder server --trace
+```
+
+Open Telemetry configuration must be provided by environment variables.
+See: https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/protocol/exporter.md.
+
+### What is Traced
+
+AI Bridge creates spans for the following operations:
+
+| Span Name                                   | Description                                          |
+|---------------------------------------------|------------------------------------------------------|
+| `CachedBridgePool.Acquire`                  | Acquiring a request bridge instance from the pool    |
+| `Intercept`                                 | Top-level span for processing an intercepted request |
+| `Intercept.CreateInterceptor`               | Creating the request interceptor                     |
+| `Intercept.ProcessRequest`                  | Processing the request through the bridge            |
+| `Intercept.ProcessRequest.Upstream`         | Forwarding the request to the upstream AI provider   |
+| `Intercept.ProcessRequest.ToolCall`         | Executing a tool call requested by the AI model      |
+| `Intercept.RecordInterception`              | Recording creating interception record               |
+| `Intercept.RecordPromptUsage`               | Recording prompt/message data                        |
+| `Intercept.RecordTokenUsage`                | Recording token consumption                          |
+| `Intercept.RecordToolUsage`                 | Recording tool/function calls                        |
+| `Intercept.RecordInterceptionEnded`         | Recording the interception as completed              |
+| `ServerProxyManager.Init`                   | Initializing MCP server proxy connections            |
+| `StreamableHTTPServerProxy.Init`            | Setting up HTTP-based MCP server proxies             |
+| `StreamableHTTPServerProxy.Init.fetchTools` | Fetching available tools from MCP servers            |
+
+Example trace of an interception using Jaeger backend:
+
+![Trace of interception](../../images/aibridge/jaeger_interception_trace.png)
+
+### Capturing Logs in Traces
+
+> **Note:** Enabling log capture may generate a large volume of trace events.
+
+To include log messages as trace events, enable trace log capture
+by setting `CODER_TRACE_LOGS` environment variable or using
+[--trace-logs](https://coder.com/docs/reference/cli/server#--trace-logs) flag:
+
+```sh
+export CODER_TRACE_ENABLE=true
+export CODER_TRACE_LOGS=true
+```
+
+```sh
+coder server --trace --trace-logs
+```
diff --git a/docs/images/aibridge/jaeger_interception_trace.png b/docs/images/aibridge/jaeger_interception_trace.png