|
| 1 | +/** |
| 2 | + * W3C trace context for a prompt turn. |
| 3 | + * |
| 4 | + * A client (the VS Code extension) sends `traceparent` with a prompt. The trace is bound to the |
| 5 | + * user message that prompt creates — the turn — not to the session, so overlapping prompts on a |
| 6 | + * busy session each keep their own trace and nothing outlives its turn. For that turn: |
| 7 | + * - calls to the Altimate gateways carry `traceparent` (a fresh child span per call) and |
| 8 | + * `x-request-id` (`<trace id>-<span id>`); the backend's Azure Monitor instrumentation adopts |
| 9 | + * the trace as the request's `operation_Id`; |
| 10 | + * - this process's log lines are tagged `trace=<id>` and its App Insights events get |
| 11 | + * `ai.operation.id`. |
| 12 | + * One id then joins the client's, altimate-code's and the backend's records of a failure. |
| 13 | + * |
| 14 | + * Lifecycle: routes bind the turn's message id before prompting; the prompt loop marks the turn |
| 15 | + * it is running as the session's active one (for telemetry), lets an automatic compaction or a |
| 16 | + * subagent inherit it, and releases every binding it processed when its generation ends. |
| 17 | + */ |
| 18 | + |
| 19 | +/** `version-traceid-parentid-flags`, lower-case hex only, as W3C Trace Context requires. */ |
| 20 | +const TRACEPARENT = /^00-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})$/ |
| 21 | +const ZERO_TRACE_ID = "0".repeat(32) |
| 22 | +const ZERO_SPAN_ID = "0".repeat(16) |
| 23 | +/** Bound on remembered turns; the oldest binding is dropped first. */ |
| 24 | +const MAX_BINDINGS = 500 |
| 25 | +/** Providers served by Altimate's backend — the only ones that receive the trace. */ |
| 26 | +const ALTIMATE_PROVIDERS = new Set(["altimate-backend", "altimate-free"]) |
| 27 | + |
| 28 | +export interface Trace { |
| 29 | + traceId: string |
| 30 | + flags: string |
| 31 | +} |
| 32 | + |
| 33 | +const byMessage = new Map<string, Trace>() |
| 34 | +/** The turn each session is running right now, and its trace, for telemetry. */ |
| 35 | +const activeBySession = new Map<string, { messageID: string; traceId: string }>() |
| 36 | + |
| 37 | +/** |
| 38 | + * Parses a `traceparent` header. Returns undefined for anything W3C says to ignore: a malformed |
| 39 | + * header, upper-case hex, or an all-zero trace or parent id. |
| 40 | + */ |
| 41 | +export function parse(header: string | undefined): Trace | undefined { |
| 42 | + const match = header ? TRACEPARENT.exec(header.trim()) : null |
| 43 | + if (!match || match[1] === ZERO_TRACE_ID || match[2] === ZERO_SPAN_ID) return undefined |
| 44 | + return { traceId: match[1], flags: match[3] } |
| 45 | +} |
| 46 | + |
| 47 | +/** Binds the trace a client sent with a prompt to the user message that prompt creates. */ |
| 48 | +export function bind(messageID: string, traceparent: string | undefined) { |
| 49 | + const trace = parse(traceparent) |
| 50 | + if (trace) remember(messageID, trace) |
| 51 | + else byMessage.delete(messageID) |
| 52 | +} |
| 53 | + |
| 54 | +/** |
| 55 | + * Gives `childMessageID` the trace of `parentMessageID`'s turn — a subagent's prompt, or an |
| 56 | + * automatic compaction inside the turn — or none, when that turn is untraced. Always replaces |
| 57 | + * the child's binding, so a resumed subagent never keeps an earlier turn's trace. |
| 58 | + */ |
| 59 | +export function inherit(childMessageID: string, parentMessageID: string) { |
| 60 | + const parent = byMessage.get(parentMessageID) |
| 61 | + if (parent) remember(childMessageID, parent) |
| 62 | + else byMessage.delete(childMessageID) |
| 63 | +} |
| 64 | + |
| 65 | +export function forMessage(messageID: string): Trace | undefined { |
| 66 | + return byMessage.get(messageID) |
| 67 | +} |
| 68 | + |
| 69 | +export function traceId(messageID: string): string | undefined { |
| 70 | + return byMessage.get(messageID)?.traceId |
| 71 | +} |
| 72 | + |
| 73 | +/** Marks `messageID`'s turn as the one `sessionID` is running now (or none, if untraced). */ |
| 74 | +export function activate(sessionID: string, messageID: string) { |
| 75 | + const trace = byMessage.get(messageID) |
| 76 | + if (trace) activeBySession.set(sessionID, { messageID, traceId: trace.traceId }) |
| 77 | + else activeBySession.delete(sessionID) |
| 78 | +} |
| 79 | + |
| 80 | +/** The trace of the turn `sessionID` is running now. */ |
| 81 | +export function activeTraceId(sessionID: string): string | undefined { |
| 82 | + return activeBySession.get(sessionID)?.traceId |
| 83 | +} |
| 84 | + |
| 85 | +/** |
| 86 | + * Releases a finished prompt-loop generation: the bindings of exactly the turns it processed |
| 87 | + * (a prompt that arrives meanwhile keeps its own), and the session's active turn if it is one of |
| 88 | + * them (a newer generation's active turn is left alone). |
| 89 | + */ |
| 90 | +export function release(sessionID: string, messageIDs: Iterable<string>) { |
| 91 | + const released = new Set(messageIDs) |
| 92 | + for (const messageID of released) byMessage.delete(messageID) |
| 93 | + const active = activeBySession.get(sessionID) |
| 94 | + if (active && released.has(active.messageID)) activeBySession.delete(sessionID) |
| 95 | +} |
| 96 | + |
| 97 | +/** |
| 98 | + * Adds the turn's trace headers to an outgoing request for an Altimate provider. The two headers |
| 99 | + * are a unit: if the request headers (model config, plugins) or the provider's configured headers |
| 100 | + * already set either, neither is added — the SDK lets per-call headers override provider ones, so |
| 101 | + * both must be checked. Each call gets a fresh span id, so the backend can tell its requests |
| 102 | + * apart while joining them on the trace. |
| 103 | + */ |
| 104 | +export function withHeaders( |
| 105 | + headers: Record<string, string>, |
| 106 | + trace: Trace | undefined, |
| 107 | + providerID: string, |
| 108 | + providerHeaders?: unknown, |
| 109 | +): Record<string, string> { |
| 110 | + if (!trace || !ALTIMATE_PROVIDERS.has(providerID)) return headers |
| 111 | + const configured = providerHeaders && typeof providerHeaders === "object" ? Object.keys(providerHeaders) : [] |
| 112 | + const existing = [...Object.keys(headers), ...configured].map((key) => key.toLowerCase()) |
| 113 | + if (existing.includes("traceparent") || existing.includes("x-request-id")) return headers |
| 114 | + const spanId = randomSpanId() |
| 115 | + return { |
| 116 | + ...headers, |
| 117 | + traceparent: `00-${trace.traceId}-${spanId}-${trace.flags}`, |
| 118 | + "x-request-id": `${trace.traceId}-${spanId}`, |
| 119 | + } |
| 120 | +} |
| 121 | + |
| 122 | +/** Number of turns currently bound (for tests and diagnostics). */ |
| 123 | +export function size(): number { |
| 124 | + return byMessage.size |
| 125 | +} |
| 126 | + |
| 127 | +/** One insertion path for every binding: replace, then evict the oldest past the bound. */ |
| 128 | +function remember(messageID: string, trace: Trace) { |
| 129 | + byMessage.delete(messageID) |
| 130 | + byMessage.set(messageID, trace) |
| 131 | + while (byMessage.size > MAX_BINDINGS) byMessage.delete(byMessage.keys().next().value!) |
| 132 | +} |
| 133 | + |
| 134 | +function randomSpanId(): string { |
| 135 | + const bytes = crypto.getRandomValues(new Uint8Array(8)) |
| 136 | + const id = Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("") |
| 137 | + return id === ZERO_SPAN_ID ? randomSpanId() : id |
| 138 | +} |
| 139 | + |
| 140 | +export * as TraceContext from "./trace-context" |
0 commit comments