feat(observability): carry the client's trace through a turn

A `traceparent` sent with a prompt is bound to the session's turn and
forwarded to the Altimate gateways (`traceparent`, `x-request-id`),
stamped on log lines (`trace=`) and on App Insights events
(`ai.operation.id`). Subagents inherit it.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

Author: saravmajestic

packages/opencode/src/altimate/observability/trace-context.ts

@@ -0,0 +1,52 @@
+/**
+ * W3C trace context for a session's current turn.
+ *
+ * A client (the VS Code extension) sends `traceparent` with a prompt. The trace is bound to the
+ * session for that turn and:
+ *   - forwarded to the Altimate gateways (`traceparent` + `x-request-id`), whose Azure Monitor
+ *     instrumentation adopts it as the request's `operation_Id`;
+ *   - stamped on this process's log lines (`trace=<id>`) and App Insights events
+ *     (`ai.operation.id`).
+ * One id then joins the client's, altimate-code's and the backend's records of a failure.
+ *
+ * The prompt is handled asynchronously (`prompt_async` returns before the turn runs), so the
+ * binding is per session rather than per async context.
+ */
+export namespace TraceContext {
+  const TRACEPARENT = /^00-([0-9a-f]{32})-([0-9a-f]{16})-[0-9a-f]{2}$/
+  /** Bound on remembered sessions; the oldest binding is dropped first. */
+  const MAX_SESSIONS = 500
+  /** Providers served by Altimate's backend — the only ones that record the trace. */
+  const ALTIMATE_PROVIDERS = new Set(["altimate-backend", "altimate-free"])
+
+  const bySession = new Map<string, { traceparent: string; traceId: string }>()
+
+  /**
+   * Binds the trace a client sent with a prompt to the session's turn. A prompt without a valid
+   * `traceparent` clears the binding, so a later untraced turn is not filed under an old trace.
+   */
+  export function bind(sessionID: string, traceparent: string | undefined) {
+    bySession.delete(sessionID)
+    const match = traceparent ? TRACEPARENT.exec(traceparent.trim().toLowerCase()) : null
+    if (!match) return
+    bySession.set(sessionID, { traceparent: match[0], traceId: match[1] })
+    if (bySession.size > MAX_SESSIONS) bySession.delete(bySession.keys().next().value!)
+  }
+
+  /** A subagent session runs as part of its parent's turn. */
+  export function inherit(childSessionID: string, parentSessionID: string) {
+    const parent = bySession.get(parentSessionID)
+    if (parent) bySession.set(childSessionID, parent)
+  }
+
+  export function traceId(sessionID: string): string | undefined {
+    return bySession.get(sessionID)?.traceId
+  }
+
+  /** Outgoing request headers for the session's trace; empty for non-Altimate providers. */
+  export function headers(sessionID: string, providerID: string): Record<string, string> {
+    const trace = bySession.get(sessionID)
+    if (!trace || !ALTIMATE_PROVIDERS.has(providerID)) return {}
+    return { traceparent: trace.traceparent, "x-request-id": trace.traceId }
+  }
+}

packages/opencode/src/altimate/telemetry/index.ts

@@ -3,6 +3,7 @@ import { Config } from "@/config/config"
 import { Flag } from "@/flag/flag"
 import { InstallationVersion } from "@opencode-ai/core/installation/version"
 import { Log } from "@/altimate/util/log"
+import { TraceContext } from "@/altimate/observability/trace-context"
 // altimate_change — shared machine-id helper (race-safe, UUID-validated, size-capped)
 import { getOrCreateMachineId } from "@/altimate/util/machine-id"
 import { createHash, randomUUID } from "crypto"
@@ -1938,7 +1939,7 @@ export namespace Telemetry {
       const measurements: Record<string, number> = {}
 
       for (const [k, v] of Object.entries(fields)) {
-        if (k === "session_id" || k === "project_id" || k === "_retried") continue
+        if (k === "session_id" || k === "project_id" || k === "_retried" || k === "_operation_id") continue
         if (typeof v === "number") {
           measurements[k] = v
         } else if (v !== undefined && v !== null) {
@@ -1961,6 +1962,7 @@ export namespace Telemetry {
           // altimate_change end
           "ai.cloud.role": "altimate",
           "ai.application.ver": InstallationVersion,
+          ...(fields._operation_id && { "ai.operation.id": fields._operation_id }),
         },
         data: {
           baseType: "EventData",
@@ -2228,6 +2230,13 @@ export namespace Telemetry {
     // Before init completes: buffer (flushed once init enables, or cleared if disabled).
     // After init completed and disabled telemetry: drop silently.
     if (initDone && !enabled) return
+    // altimate_change start — stamp the client's trace for this session's turn now: the event is
+    // serialised at flush time, when the session may already be on its next turn. Becomes the
+    // envelope's `ai.operation.id`, joining it to the extension's and backend's records.
+    const traceSession = (event as any).session_id ?? sessionId
+    const operationId = traceSession ? TraceContext.traceId(traceSession) : undefined
+    if (operationId) (event as any)._operation_id = operationId
+    // altimate_change end
     buffer.push(event)
     if (buffer.length > MAX_BUFFER_SIZE) {
       buffer.shift()

packages/opencode/src/server/routes/session.ts

@@ -17,6 +17,9 @@ import { Todo } from "../../session/todo"
 import { Agent } from "../../agent/agent"
 import { Snapshot } from "@/snapshot"
 import { Log } from "../../util/log"
+// altimate_change start — client trace propagation
+import { TraceContext } from "@/altimate/observability/trace-context"
+// altimate_change end
 // altimate_change start — upstream_fix: bridge merge wired routes to Effect-TS Permission, but the runtime
 // asks come from PermissionNext. Use PermissionNext here so this deprecated reply route hits the same
 // pending map. See packages/opencode/src/server/routes/permission.ts for the full explanation.
@@ -922,6 +925,9 @@ export const SessionRoutes = lazy(() =>
         return stream(c, async (stream) => {
           const sessionID = c.req.valid("param").sessionID
           const body = c.req.valid("json")
+          // altimate_change start — bind the client's trace to this turn (see TraceContext)
+          TraceContext.bind(sessionID, c.req.header("traceparent"))
+          // altimate_change end
           const msg = await SessionPrompt.prompt({ ...body, sessionID })
           stream.write(JSON.stringify(msg))
         })
@@ -954,6 +960,9 @@ export const SessionRoutes = lazy(() =>
         return stream(c, async () => {
           const sessionID = c.req.valid("param").sessionID
           const body = c.req.valid("json")
+          // altimate_change start — bind the client's trace to this turn (see TraceContext)
+          TraceContext.bind(sessionID, c.req.header("traceparent"))
+          // altimate_change end
           SessionPrompt.prompt({ ...body, sessionID }).catch((err) => {
             log.error("prompt_async failed", { sessionID, error: err })
             Bus.publish(Session.Event.Error, {
@@ -997,6 +1006,9 @@ export const SessionRoutes = lazy(() =>
       async (c) => {
         const sessionID = c.req.valid("param").sessionID
         const body = c.req.valid("json")
+        // altimate_change start — bind the client's trace to this turn (see TraceContext)
+        TraceContext.bind(sessionID, c.req.header("traceparent"))
+        // altimate_change end
         const msg = await SessionPrompt.command({ ...body, sessionID })
         return c.json(msg)
       },

packages/opencode/src/session/llm.ts

@@ -39,6 +39,7 @@ import { Context, Effect, Layer, Stream } from "effect"
 import { LayerNode } from "@opencode-ai/core/effect/layer-node"
 import type { LLMEvent } from "@opencode-ai/llm"
 import { LLMAISDK } from "./llm/ai-sdk"
+import { TraceContext } from "@/altimate/observability/trace-context"
 // altimate_change end
 
 export namespace LLM {
@@ -84,6 +85,10 @@ export namespace LLM {
       .tag("small", (input.small ?? false).toString())
       .tag("agent", input.agent.name)
       .tag("mode", input.agent.mode)
+    // altimate_change start — stamp the turn's client trace on this request's log lines
+    const traceId = TraceContext.traceId(input.sessionID)
+    if (traceId) l.tag("trace", traceId)
+    // altimate_change end
     l.info("stream", {
       modelID: input.model.id,
       providerID: input.model.providerID,
@@ -203,6 +208,9 @@ export namespace LLM {
               "User-Agent": `altimate-code/${Installation.VERSION}`,
             }
           : undefined,
+      // altimate_change start — forward the turn's trace to the Altimate gateways
+      TraceContext.headers(input.sessionID, input.model.providerID),
+      // altimate_change end
       input.model.headers,
       headers,
     )

packages/opencode/src/session/processor.ts

@@ -1,5 +1,8 @@
 import { MessageV2 } from "./message-v2"
 import { Log } from "@/util/log"
+// altimate_change start — client trace propagation
+import { TraceContext } from "@/altimate/observability/trace-context"
+// altimate_change end
 import { Session } from "."
 import { Agent } from "@/agent/agent"
 import { Snapshot } from "@/snapshot"
@@ -1163,6 +1166,9 @@ export namespace SessionProcessor {
             log.error("process", {
               error: e,
               stack: JSON.stringify(e.stack),
+              // altimate_change start — join this failure to the client's trace
+              ...(TraceContext.traceId(input.sessionID) && { trace: TraceContext.traceId(input.sessionID) }),
+              // altimate_change end
             })
             const error = MessageV2.fromError(e, { providerID: input.model.providerID })
             if (MessageV2.ContextOverflowError.isInstance(error)) {

packages/opencode/src/tool/task.ts

@@ -17,6 +17,9 @@ import { Config } from "../config/config"
 import { PermissionNext } from "@/permission/next"
 // altimate_change start — log unhandled cancel rejections
 import { Log } from "@/util/log"
+// altimate_change start — client trace propagation
+import { TraceContext } from "@/altimate/observability/trace-context"
+// altimate_change end
 // re-brand core (ModelV2/ProviderV2) IDs to the provider/schema brands SessionPrompt expects
 import { ModelID, ProviderID } from "@/provider/schema"
 import { Effect } from "effect"
@@ -182,6 +185,9 @@ export const TaskTool = Tool.define("task", async (ctx) => {
       })
 
       const messageID = MessageID.ascending()
+      // altimate_change start — the subagent's LLM calls belong to the parent turn's trace
+      TraceContext.inherit(session.id, ctx.sessionID)
+      // altimate_change end
       const promptOps = ctx.extra?.promptOps as TaskPromptOps | undefined
 
       function cancel() {

packages/opencode/test/altimate/trace-context.test.ts

@@ -0,0 +1,50 @@
+/**
+ * TraceContext binds the trace a client sends with a prompt to the session's turn, so the turn's
+ * gateway calls, log lines and telemetry share one id with the client and the backend.
+ */
+import { describe, expect, test } from "bun:test"
+import { TraceContext } from "../../src/altimate/observability/trace-context"
+import { LLM } from "../../src/session/llm"
+
+const TRACE_ID = "0af7651916cd43dd8448eb211c80319c"
+const TRACEPARENT = `00-${TRACE_ID}-b7ad6b7169203331-01`
+
+describe("TraceContext", () => {
+  test("binds a valid traceparent to the session", () => {
+    TraceContext.bind("ses_bind", TRACEPARENT)
+    expect(TraceContext.traceId("ses_bind")).toBe(TRACE_ID)
+  })
+
+  test("ignores a malformed traceparent and clears the previous turn's trace", () => {
+    TraceContext.bind("ses_clear", TRACEPARENT)
+    TraceContext.bind("ses_clear", "not-a-traceparent")
+    expect(TraceContext.traceId("ses_clear")).toBeUndefined()
+    TraceContext.bind("ses_clear", TRACEPARENT)
+    TraceContext.bind("ses_clear", undefined)
+    expect(TraceContext.traceId("ses_clear")).toBeUndefined()
+  })
+
+  test("sends trace headers only to Altimate providers", () => {
+    TraceContext.bind("ses_headers", TRACEPARENT)
+    const expected = { traceparent: TRACEPARENT, "x-request-id": TRACE_ID }
+    expect(TraceContext.headers("ses_headers", "altimate-backend")).toEqual(expected)
+    expect(TraceContext.headers("ses_headers", "altimate-free")).toEqual(expected)
+    expect(TraceContext.headers("ses_headers", "anthropic")).toEqual({})
+    expect(TraceContext.headers("ses_untraced", "altimate-backend")).toEqual({})
+  })
+
+  test("a subagent session inherits its parent's trace", () => {
+    TraceContext.bind("ses_parent", TRACEPARENT)
+    TraceContext.inherit("ses_child", "ses_parent")
+    expect(TraceContext.traceId("ses_child")).toBe(TRACE_ID)
+  })
+
+  test("the Altimate Base session header does not displace the trace headers", () => {
+    TraceContext.bind("ses_base", TRACEPARENT)
+    const headers = LLM.withManagedSessionHeaders("altimate-free", "ses_base", {
+      ...TraceContext.headers("ses_base", "altimate-free"),
+    })
+    expect(headers.traceparent).toBe(TRACEPARENT)
+    expect(headers["X-Session-Id"]).toBe("ses_base")
+  })
+})