Skip to content

armgit / eve

Public Imported from GitHub
0

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.md
new file mode 100644
index 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.mdx
index 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 data
and 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 traces
diff --git a/packages/eve/src/harness/compaction/step.ts b/packages/eve/src/harness/compaction/step.ts
index 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-event
import {
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.ts
index 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.js
import 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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;