feat: add tracing to aibridge (#21106)

Adds tracing for AIBridge. Updates github.com/coder/aibridge version from `v0.2.2` to `v0.3.0` Depends on: https://github.com/coder/aibridge/pull/63 Fixes: https://github.com/coder/aibridge/issues/26 --------- Co-authored-by: Danny Kopping <danny@coder.com>
2026-09-24 15:04:27 +08:00 · 2025-12-05 15:59:52 +01:00
parent 259dee2ea8
commit e24cc5e6da
12 changed files with 169 additions and 31 deletions
@@ -60,3 +60,65 @@ 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
+```
+
+### 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
+```