The Open Framework for Building Agents
fix: propagate model trace context to gateway (#4599)
Jeremy4bf1efaf35eb
diff --git a/.changeset/gateway-model-traceparent.md b/.changeset/gateway-model-traceparent.mdnew file mode 100644index 000000000..9f3d93f7d--- /dev/null+++ b/.changeset/gateway-model-traceparent.md@@ -0,0 +1,5 @@+---+"eve": patch+---++Propagate configured trace context at each AI Gateway model request.diff --git a/docs/guides/instrumentation/otel.mdx b/docs/guides/instrumentation/otel.mdxindex 33a885475..8814a36e2 100644--- a/docs/guides/instrumentation/otel.mdx+++ b/docs/guides/instrumentation/otel.mdx@@ -174,6 +174,9 @@ each turn. Remote requests carry the conversation ID in W3C Baggage.`trustedForwarders` controls whether the receiver accepts parent session dataand the trace-content policy. See[Remote agents](../guides/remote-agents#preserving-trace-content).+Gateway-routed model calls propagate the configured OpenTelemetry context at+each provider request. Eve-owned baggage is removed before forwarding. Gateway+controls whether its spans are sampled and which destinations receive them.## Local tracesdiff --git a/packages/eve/src/harness/compaction/step.ts b/packages/eve/src/harness/compaction/step.tsindex 40217f479..004b671ec 100644--- a/packages/eve/src/harness/compaction/step.ts+++ b/packages/eve/src/harness/compaction/step.ts@@ -23,6 +23,7 @@ import { stepStartedForResolvers } from "#harness/session-machine/resolver-eventimport {buildGatewayAttributionHeaders,resolveEffectiveRuntimeModel,+ withGatewayTraceContext,} from "#harness/model-call/model.js";import { canonicalizeMemoryRecords, shouldCanonicalizeMemory } from "#shared/memory-state.js";import {@@ -100,6 +101,7 @@ export async function compactHistory(step: Step): Promise<StepResult> {runtimeIdentity: config.runtimeIdentity,session: step.session,telemetry: step.instrumentation?.telemetry(),+ traceContextHeaders: step.instrumentation?.gatewayTraceContextHeaders,});step.session = compacted.session;if (compacted.failure !== undefined) throw compacted.failure.error;@@ -156,6 +158,7 @@ export async function maybeCompact(input: {readonly runtimeIdentity?: ToolLoopHarnessConfig["runtimeIdentity"];readonly session: HarnessSession;readonly telemetry?: TelemetryOptions;+ readonly traceContextHeaders?: () => Record<string, string> | undefined;}): Promise<{readonly compacted: boolean;/** The summary failed; `session` still counts the summary calls that finished. */@@ -200,7 +203,7 @@ export async function maybeCompact(input: {const call = {abortSignal: input.abortSignal,headers: buildGatewayAttributionHeaders(profile, input.runtimeIdentity),- model,+ model: withGatewayTraceContext(model, profile, input.traceContextHeaders),providerOptions,telemetry: input.telemetry && { ...input.telemetry, functionId: "eve.compaction" },};diff --git a/packages/eve/src/harness/model-call/call.ts b/packages/eve/src/harness/model-call/call.tsindex a9630403d..19278c9dc 100644--- a/packages/eve/src/harness/model-call/call.ts+++ b/packages/eve/src/harness/model-call/call.ts@@ -53,7 +53,7 @@ import { requireSessionModelReference, type StepResult } from "#harness/types.jsimport type { InstrumentationAttempt } from "#instrumentation/runtime.js";import { createLogger, logError } from "#internal/logging.js";import { maybeCompact } from "#harness/compaction/step.js";-import { buildGatewayAttributionHeaders } from "./model.js";+import { buildGatewayAttributionHeaders, withGatewayTraceContext } from "./model.js";import { isEmptyModelResponse, rethrowNoOutputAsEmptyResponse } from "./recovery.js";import {modelInstructions,@@ -277,6 +277,7 @@ export class ModelCaller {runtimeIdentity: config.runtimeIdentity,session: step.session,telemetry: step.instrumentation?.telemetry(),+ traceContextHeaders: step.instrumentation?.gatewayTraceContextHeaders,});if (compaction.failure !== undefined) throw compaction.failure.error;} catch (error) {@@ -352,7 +353,11 @@ export class ModelCaller {const settings = {headers: this.attributionHeaders,instructions,- model,+ model: withGatewayTraceContext(+ model,+ this.profile,+ this.step.instrumentation?.gatewayTraceContextHeaders,+ ),onLanguageModelCallEnd: (event: LanguageModelCallEndEvent) => {if (generation.interrupted) return;this.interruptedUsage = extractTokenUsageDelta({diff --git a/packages/eve/src/harness/model-call/model.ts b/packages/eve/src/harness/model-call/model.tsindex 95bb0f3c8..a142efd08 100644--- a/packages/eve/src/harness/model-call/model.ts+++ b/packages/eve/src/harness/model-call/model.ts@@ -1,4 +1,4 @@-import type { LanguageModel } from "ai";+import { gateway, type LanguageModel, type LanguageModelMiddleware, wrapLanguageModel } from "ai";import type { CompactionConfig, HarnessSession, ToolLoopHarnessConfig } from "#harness/types.js";import type { RuntimeModelReference } from "#runtime/agent/bootstrap.js";@@ -27,6 +27,28 @@ export function buildGatewayAttributionHeaders(return headers;}+/** Injects the active model-call context when a Gateway request reaches the provider boundary. */+export function withGatewayTraceContext(+ model: LanguageModel,+ profile: ModelProfile,+ createTraceContextHeaders?: () => Record<string, string> | undefined,+): LanguageModel {+ if (!profile.gateway || createTraceContextHeaders === undefined) return model;+ const provider = globalThis.AI_SDK_DEFAULT_PROVIDER ?? gateway;+ if (typeof model === "string" && typeof provider.languageModel !== "function") return model;+ const gatewayModel = typeof model === "string" ? provider.languageModel(model) : model;+ if (gatewayModel.provider.split(".")[0] !== "gateway") return model;+ const middleware: LanguageModelMiddleware = {+ async transformParams({ params }) {+ const traceHeaders = createTraceContextHeaders();+ return traceHeaders === undefined+ ? params+ : { ...params, headers: { ...params.headers, ...traceHeaders } };+ },+ };+ return wrapLanguageModel({ model: gatewayModel, middleware });+}+export async function resolveEffectiveRuntimeModel(input: {readonly config: ToolLoopHarnessConfig;readonly ctx: ReturnType<typeof contextStorage.getStore>;diff --git a/packages/eve/src/instrumentation/runtime.ts b/packages/eve/src/instrumentation/runtime.tsindex 03b9939c9..4a32adf0e 100644--- a/packages/eve/src/instrumentation/runtime.ts+++ b/packages/eve/src/instrumentation/runtime.ts@@ -70,6 +70,7 @@ import {} from "#instrumentation/runtime-global.js";import { initializeSessionInstrumentation } from "#instrumentation/session-init.js";import { ensureAiSdkWarningLogger } from "#instrumentation/ai-sdk-warnings.js";+import { createGatewayTraceContextHeaders } from "#tracing/eve/gateway.js";export { getInstrumentationRuntime, registerInstrumentationRuntime };export { initializeSessionInstrumentation };@@ -83,6 +84,7 @@ interface InstrumentedStepSession {}export interface InstrumentationStepScope<TSession> {+ readonly gatewayTraceContextHeaders?: () => Record<string, string> | undefined;readonly createHandleEvent: (input: Omit<CreateInstrumentationHandleEventInput,@@ -415,6 +417,7 @@ export function bindInstrumentationRuntime(};const run = () =>execute({+ gatewayTraceContextHeaders: createGatewayTraceContextHeaders,createHandleEvent: (eventInput) =>createInstrumentationHandleEvent({...eventInput,diff --git a/packages/eve/src/internal/gateway-trace-propagation.test.ts b/packages/eve/src/internal/gateway-trace-propagation.test.tsnew file mode 100644index 000000000..f15831270--- /dev/null+++ b/packages/eve/src/internal/gateway-trace-propagation.test.ts@@ -0,0 +1,168 @@+import {+ context as apiContext,+ propagation as apiPropagation,+ ROOT_CONTEXT,+ trace as apiTrace,+ type Context,+} from "@opentelemetry/api";+import type { LanguageModelV4, LanguageModelV4CallOptions } from "@ai-sdk/provider";+import { AsyncLocalStorageContextManager } from "@opentelemetry/context-async-hooks";+import {+ CompositePropagator,+ suppressTracing,+ W3CBaggagePropagator,+ W3CTraceContextPropagator,+} from "@opentelemetry/core";+import { createGateway } from "ai";+import { MockLanguageModelV3 } from "ai/test";+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";+import { withGatewayTraceContext } from "#harness/model-call/model.js";+import { resolveModelProfile } from "#harness/model-profile.js";+import { createGatewayTraceContextHeaders } from "#tracing/eve/gateway.js";++const TRACE_ID = "1".repeat(32);++describe("Gateway trace propagation", () => {+ beforeEach(() => {+ apiContext.setGlobalContextManager(new AsyncLocalStorageContextManager().enable());+ apiPropagation.setGlobalPropagator(+ new CompositePropagator({+ propagators: [new W3CTraceContextPropagator(), new W3CBaggagePropagator()],+ }),+ );+ });++ afterEach(() => {+ apiPropagation.disable();+ apiContext.disable();+ vi.unstubAllGlobals();+ });++ it("injects the active call context for each generate and stream request", async () => {+ const requestHeaders: Headers[] = [];+ const fetcher = vi.fn<typeof globalThis.fetch>().mockImplementation(async (_url, init) => {+ requestHeaders.push(new Headers(init?.headers));+ if (requestHeaders.length === 3) {+ return new Response("data: [DONE]\n\n", {+ headers: { "content-type": "text/event-stream" },+ });+ }+ return new Response("{}", { headers: { "content-type": "application/json" } });+ });+ const gatewayProvider = createGateway({ apiKey: "gateway-test", fetch: fetcher });+ vi.stubGlobal("AI_SDK_DEFAULT_PROVIDER", gatewayProvider);+ const model = gatewayProvider.languageModel("anthropic/claude-sonnet-4-5") as LanguageModelV4;+ const tracedModel = withGatewayTraceContext(+ model,+ resolveModelProfile(model),+ createGatewayTraceContextHeaders,+ ) as LanguageModelV4;+ const callOptions: LanguageModelV4CallOptions = {+ headers: { "x-eve-test": "preserved" },+ prompt: [{ content: [{ text: "hello", type: "text" }], role: "user" }],+ };+ const baggage = apiPropagation.createBaggage({+ "eve.audience": { value: "private" },+ "eve.conversation.id": { value: "conversation-1" },+ "eve.parent_session": { value: "parent-1" },+ "vendor.request": { value: "keep" },+ });+ const contextFor = (spanId: string) =>+ apiPropagation.setBaggage(+ apiTrace.setSpan(+ ROOT_CONTEXT,+ apiTrace.wrapSpanContext({+ isRemote: true,+ spanId,+ traceFlags: 1,+ traceId: TRACE_ID,+ }),+ ),+ baggage,+ );++ await apiContext.with(contextFor("2".repeat(16)), () => tracedModel.doGenerate(callOptions));+ await apiContext.with(contextFor("3".repeat(16)), () => tracedModel.doGenerate(callOptions));+ const stream = await apiContext.with(contextFor("4".repeat(16)), () =>+ tracedModel.doStream(callOptions),+ );+ await stream.stream.cancel();++ expect(requestHeaders.map((headers) => headers.get("traceparent"))).toEqual([+ `00-${TRACE_ID}-${"2".repeat(16)}-01`,+ `00-${TRACE_ID}-${"3".repeat(16)}-01`,+ `00-${TRACE_ID}-${"4".repeat(16)}-01`,+ ]);+ expect(requestHeaders[0]?.get("x-eve-test")).toBe("preserved");+ expect(requestHeaders[0]?.get("baggage")).toBe("vendor.request=keep");+ });++ it("does not inject context when tracing is suppressed", async () => {+ const requestHeaders: Headers[] = [];+ const fetcher = vi.fn<typeof globalThis.fetch>().mockImplementation(async (_url, init) => {+ requestHeaders.push(new Headers(init?.headers));+ return new Response("{}", { headers: { "content-type": "application/json" } });+ });+ const model = createGateway({ apiKey: "gateway-test", fetch: fetcher }).languageModel(+ "anthropic/claude-sonnet-4-5",+ ) as LanguageModelV4;+ const tracedModel = withGatewayTraceContext(+ model,+ resolveModelProfile(model),+ createGatewayTraceContextHeaders,+ ) as LanguageModelV4;+ const activeContext = apiTrace.setSpan(+ ROOT_CONTEXT,+ apiTrace.wrapSpanContext({+ isRemote: true,+ spanId: "5".repeat(16),+ traceFlags: 1,+ traceId: TRACE_ID,+ }),+ );++ await apiContext.with(suppressTracing(activeContext) as Context, () =>+ tracedModel.doGenerate({+ prompt: [{ content: [{ text: "hello", type: "text" }], role: "user" }],+ }),+ );++ expect(requestHeaders).toHaveLength(1);+ expect(requestHeaders[0]?.get("traceparent")).toBeNull();+ });++ it("wraps bare Gateway ids without a configured default provider", () => {+ vi.stubGlobal("AI_SDK_DEFAULT_PROVIDER", undefined);++ const model = withGatewayTraceContext(+ "anthropic/claude-sonnet-4-5",+ resolveModelProfile("anthropic/claude-sonnet-4-5"),+ createGatewayTraceContextHeaders,+ );++ expect(typeof model).not.toBe("string");+ expect(typeof model === "string" ? undefined : model.provider).toBe("gateway");+ });++ it("leaves direct-provider models and custom defaults unchanged", () => {+ const directModel = new MockLanguageModelV3({ provider: "anthropic" });+ vi.stubGlobal("AI_SDK_DEFAULT_PROVIDER", {+ languageModel: vi.fn(() => directModel),+ });++ expect(+ withGatewayTraceContext(+ directModel,+ resolveModelProfile(directModel),+ createGatewayTraceContextHeaders,+ ),+ ).toBe(directModel);+ expect(+ withGatewayTraceContext(+ "anthropic/claude-sonnet-4-5",+ resolveModelProfile("anthropic/claude-sonnet-4-5"),+ createGatewayTraceContextHeaders,+ ),+ ).toBe("anthropic/claude-sonnet-4-5");+ });+});diff --git a/packages/eve/src/protocol/baggage.test.ts b/packages/eve/src/protocol/baggage.test.tsindex 13f75ae0a..964d923b4 100644--- a/packages/eve/src/protocol/baggage.test.ts+++ b/packages/eve/src/protocol/baggage.test.ts@@ -4,6 +4,7 @@ import {readBaggageMember,readForwardedAudienceBaggage,readForwardedParentSessionBaggage,+ stripEveTraceBaggage,writeForwardedAudienceBaggage,writeForwardedParentSessionBaggage,} from "#protocol/baggage.js";@@ -165,3 +166,26 @@ describe("forwarded parent session baggage", () => {expect(readForwardedParentSessionBaggage(value)).toBe("malformed");});});++describe("stripEveTraceBaggage", () => {+ it("removes Eve context while preserving unrelated baggage", () => {+ const carrier = {+ baggage:+ "vendor=value,eve.audience=private;ceiling=i0o0,eve.conversation.id=session-1,eve.parent_session=parent",+ };++ stripEveTraceBaggage(carrier);++ expect(carrier.baggage).toBe("vendor=value");+ });++ it("drops an oversized remainder", () => {+ const carrier = {+ baggage: `eve.audience=private,vendor=${"x".repeat(8_192)}`,+ };++ stripEveTraceBaggage(carrier);++ expect(carrier.baggage).toBeUndefined();+ });+});diff --git a/packages/eve/src/protocol/baggage.ts b/packages/eve/src/protocol/baggage.tsindex 8d9f8f495..4098413a9 100644--- a/packages/eve/src/protocol/baggage.ts+++ b/packages/eve/src/protocol/baggage.ts@@ -6,7 +6,13 @@ import { formatTraceContentCeiling } from "#shared/forwarded-trace-policy.js";import type { SessionParent } from "#channel/types.js";const EVE_AUDIENCE_KEY = "eve.audience";+const EVE_CONVERSATION_ID_KEY = "eve.conversation.id";const EVE_PARENT_SESSION_KEY = "eve.parent_session";+const EVE_TRACE_BAGGAGE_KEYS = [+ EVE_AUDIENCE_KEY,+ EVE_CONVERSATION_ID_KEY,+ EVE_PARENT_SESSION_KEY,+] as const;const CEILING_PROPERTY_KEY = "ceiling";const MAX_BAGGAGE_BYTES = 8192;const encoder = new TextEncoder();@@ -104,6 +110,19 @@ export function writeForwardedAudienceBaggage();}+export function stripEveTraceBaggage(carrier: Record<string, string>): void {+ let baggage = carrier["baggage"];+ if (baggage === undefined) return;+ for (const key of EVE_TRACE_BAGGAGE_KEYS) {+ baggage = replaceBaggageMember(baggage, key, undefined);+ }+ if (baggage === undefined || encoder.encode(baggage).byteLength > MAX_BAGGAGE_BYTES) {+ delete carrier["baggage"];+ } else {+ carrier["baggage"] = baggage;+ }+}+/** Recognized members are singular; malformed or oversized input fails closed. */export function readBaggageMember(value: string | null,diff --git a/packages/eve/src/runtime/connections/mcp-tracing.ts b/packages/eve/src/runtime/connections/mcp-tracing.tsindex 32f20d28f..5a37d284a 100644--- a/packages/eve/src/runtime/connections/mcp-tracing.ts+++ b/packages/eve/src/runtime/connections/mcp-tracing.ts@@ -1,18 +1,9 @@+import { stripEveTraceBaggage } from "#protocol/baggage.js";import { createMcpTraceFetch as traceFetch } from "#tracing/eve/mcp.js";import { createMcpTracing } from "#tracing/eve/mcp.js";-import { replaceBaggageMember } from "#protocol/baggage.js";export function createMcpTraceFetch(input: Parameters<typeof traceFetch>[0]): typeof fetch {- return traceFetch({- ...input,- filterCarrier(carrier) {- let baggage = carrier.baggage;- for (const key of ["eve.audience", "eve.conversation.id", "eve.parent_session"])- baggage = replaceBaggageMember(baggage, key, undefined);- if (baggage === undefined) delete carrier.baggage;- else carrier.baggage = baggage;- },- });+ return traceFetch({ ...input, filterCarrier: stripEveTraceBaggage });}export function withMcpToolsListSpan<T>(input: {diff --git a/packages/eve/src/tracing/eve/gateway.ts b/packages/eve/src/tracing/eve/gateway.tsindex 4d255597b..f37f1767a 100644--- a/packages/eve/src/tracing/eve/gateway.ts+++ b/packages/eve/src/tracing/eve/gateway.ts@@ -1,5 +1,37 @@-/** Converts Gateway response metadata to cost data. */import type { Attributes } from "#compiled/@eve/tracing/index.js";+import {+ context as otelContext,+ createContextKey,+ propagation,+ trace,+ type TextMapSetter,+} from "#compiled/@opentelemetry/api/index.js";++import { stripEveTraceBaggage } from "#protocol/baggage.js";++const SUPPRESS_TRACING_KEY = createContextKey("OpenTelemetry SDK Context Key SUPPRESS_TRACING");+const traceContextSetter: TextMapSetter<Record<string, string>> = {+ set(carrier, key, value) {+ carrier[key] = value;+ },+};++export function createGatewayTraceContextHeaders(): Record<string, string> | undefined {+ const activeContext = otelContext.active();+ if (+ activeContext.getValue(SUPPRESS_TRACING_KEY) === true ||+ trace.getSpan(activeContext) === undefined+ ) {+ return undefined;+ }++ const headers: Record<string, string> = {};+ propagation.inject(activeContext, headers, traceContextSetter);+ stripEveTraceBaggage(headers);+ return Object.keys(headers).length === 0 ? undefined : headers;+}++/** Converts Gateway response metadata to cost data. */export function gatewayCostAttributes(input: {cost?: number;gatewayCost?: number;