The Open Framework for Building Agents
feat(eve): emit vercel.session_id on agent spans when running on Vercel (#2400)
Chad Hietalaab7f4e1b8934
diff --git a/.changeset/vercel-session-id-attribute.md b/.changeset/vercel-session-id-attribute.mdnew file mode 100644index 000000000..86d9ce456--- /dev/null+++ b/.changeset/vercel-session-id-attribute.md@@ -0,0 +1,5 @@+---+"eve": patch+---++Agent spans now carry `vercel.session_id` (set to the root session id) when running on Vercel, so traces can be equality-looked-up across all session windows via an indexed column. The attribute is omitted in local `eve dev`.diff --git a/packages/eve/src/tracing/agent-action-instrumentation.ts b/packages/eve/src/tracing/agent-action-instrumentation.tsindex 83de88e60..79574e241 100644--- a/packages/eve/src/tracing/agent-action-instrumentation.ts+++ b/packages/eve/src/tracing/agent-action-instrumentation.ts@@ -45,6 +45,7 @@ export interface AgentActionContext {/** Builds durable `agent.action` spans around eve's runtime dispatch boundary. */export function createAgentActionInstrumentation(input: {+ readonly emitVercelSessionId?: boolean;readonly frameworkVersion: string;readonly idGenerator: AgentSpanIdGenerator;readonly recordInputs: boolean;@@ -55,6 +56,7 @@ export function createAgentActionInstrumentation(input: {readonly stateStore: AgentTraceStateStore;readonly tracer: Tracer;}): AgentActionInstrumentation {+ const emitVercelSessionId = input.emitVercelSessionId ?? false;const byAttempt = new Map<string, Set<string>>();const onStarted = async (event: InstrumentationActionStartedEvent): Promise<void> => {@@ -131,6 +133,9 @@ export function createAgentActionInstrumentation(input: {"agent.step.attempt": state.attemptIndex,"agent.step.index": state.stepIndex,"agent.turn.id": state.turnId,+ ...(emitVercelSessionId+ ? { "vercel.session_id": state.rootSessionId }+ : {}),},startTime: state.startTimeMs,},diff --git a/packages/eve/src/tracing/agent-approval-instrumentation.ts b/packages/eve/src/tracing/agent-approval-instrumentation.tsindex cff37245b..2150d09c6 100644--- a/packages/eve/src/tracing/agent-approval-instrumentation.ts+++ b/packages/eve/src/tracing/agent-approval-instrumentation.ts@@ -41,6 +41,7 @@ export function createAgentApprovalInstrumentation(input: {turnId: string,callId: string,) => Promise<AgentActionContext | undefined>;+ readonly emitVercelSessionId?: boolean;readonly frameworkVersion: string;readonly idGenerator: AgentSpanIdGenerator;readonly recordInputs: boolean;@@ -50,6 +51,7 @@ export function createAgentApprovalInstrumentation(input: {NonNullable<InstrumentationProviderDefinition["events"]>,"input.requested" | "input.resolved"> {+ const emitVercelSessionId = input.emitVercelSessionId ?? false;const onRequested = async (event: InstrumentationInputRequestedEvent,ctx: InstrumentationHandlerContext,@@ -110,6 +112,9 @@ export function createAgentApprovalInstrumentation(input: {"agent.step.attempt": state.attemptIndex,"agent.step.index": state.stepIndex,"agent.turn.id": state.turnId,+ ...(emitVercelSessionId+ ? { "vercel.session_id": state.rootSessionId }+ : {}),},startTime: state.startTimeMs,},diff --git a/packages/eve/src/tracing/agent-channel-delivery-instrumentation.ts b/packages/eve/src/tracing/agent-channel-delivery-instrumentation.tsindex d363e9ac5..d388a6a89 100644--- a/packages/eve/src/tracing/agent-channel-delivery-instrumentation.ts+++ b/packages/eve/src/tracing/agent-channel-delivery-instrumentation.ts@@ -35,6 +35,7 @@ interface ChannelDeliverySpanState {/** Builds durable channel delivery spans around the turn that consumes each request. */export function createAgentChannelDeliveryInstrumentation(input: {+ readonly emitVercelSessionId?: boolean;readonly ensureSessionContext: (event: InstrumentationSessionStartedEvent,) => Promise<AgentSessionTraceState>;@@ -50,6 +51,7 @@ export function createAgentChannelDeliveryInstrumentation(input: {| "channel.delivery.failed"| "channel.delivery.started"> {+ const emitVercelSessionId = input.emitVercelSessionId ?? false;const onStarted = async (event: InstrumentationChannelDeliveryStartedEvent,ctx: InstrumentationHandlerContext,@@ -130,6 +132,9 @@ export function createAgentChannelDeliveryInstrumentation(input: {"agent.session.window": session?.window ?? state.window,"agent.turn.id": event.turnId,"agent.turn.sequence": event.sequence,+ ...(emitVercelSessionId+ ? { "vercel.session_id": event.rootSessionId }+ : {}),},kind: SpanKind.CONSUMER,links:diff --git a/packages/eve/src/tracing/agent-otel-provider.test.ts b/packages/eve/src/tracing/agent-otel-provider.test.tsindex 849d4e849..da481a2e7 100644--- a/packages/eve/src/tracing/agent-otel-provider.test.ts+++ b/packages/eve/src/tracing/agent-otel-provider.test.ts@@ -62,6 +62,7 @@ interface TestRuntime {function createRuntime(stateStore: AgentTraceStateStore = new InMemoryAgentTraceStateStore(),tracePolicy: TraceCapturePolicy | null = () => true,+ options: { readonly emitVercelSessionId?: boolean } = {},): TestRuntime {const exporter = new InMemorySpanExporter();const idGenerator = new AgentSpanIdGenerator();@@ -73,6 +74,7 @@ function createRuntime(const agentOtelInput: Omit<AgentOtelInstrumentationInput, "tracePolicy"> & {tracePolicy?: TraceCapturePolicy;} = {+ emitVercelSessionId: options.emitVercelSessionId,frameworkVersion: "test",idGenerator,recordInputs: true,@@ -1847,4 +1849,46 @@ describe("createAgentOtelInstrumentation", () => {});expect(byName(spans, "agent.turn")[0]!.status.code).toBe(SpanStatusCode.UNSET);});++ describe("emitVercelSessionId", () => {+ it("emits vercel.session_id on session, turn, step, and action spans when enabled", async () => {+ const runtime = createRuntime(undefined, undefined, { emitVercelSessionId: true });+ await emitAttempt({+ hooks: runtime.hooks,+ runInContext: runtime.runInContext,+ sessionId: "session-1",+ turnId: "turn-1",+ turnSequence: 0,+ });+ await runtime.provider.forceFlush();++ const spans = runtime.exporter.getFinishedSpans();+ const session = byName(spans, "agent.session")[0]!;+ const turn = byName(spans, "agent.turn")[0]!;+ const step = byName(spans, "agent.step")[0]!;+ const action = byName(spans, "agent.action")[0]!;++ expect(session.attributes["vercel.session_id"]).toBe("session-1");+ expect(turn.attributes["vercel.session_id"]).toBe("session-1");+ expect(step.attributes["vercel.session_id"]).toBe("session-1");+ expect(action.attributes["vercel.session_id"]).toBe("session-1");+ });++ it("does not emit vercel.session_id by default", async () => {+ const runtime = createRuntime();+ await emitAttempt({+ hooks: runtime.hooks,+ runInContext: runtime.runInContext,+ sessionId: "session-1",+ turnId: "turn-1",+ turnSequence: 0,+ });+ await runtime.provider.forceFlush();++ const spans = runtime.exporter.getFinishedSpans();+ for (const span of spans) {+ expect(span.attributes["vercel.session_id"]).toBeUndefined();+ }+ });+ });});diff --git a/packages/eve/src/tracing/agent-otel-provider.ts b/packages/eve/src/tracing/agent-otel-provider.tsindex 2900345e0..f706bb7d4 100644--- a/packages/eve/src/tracing/agent-otel-provider.ts+++ b/packages/eve/src/tracing/agent-otel-provider.ts@@ -73,6 +73,14 @@ export interface AgentOtelInstrumentationInput {readonly stateStore: AgentTraceStateStore;readonly tracer: Tracer;readonly tracePolicy?: TraceCapturePolicy;+ /**+ * When true, every agent span also carries `vercel.session_id` set to the+ * root session id. The VDP trace ingestion materialized view extracts this+ * into the indexed `sessionId` column so Agent Runs can equality-lookup a+ * session across all trace windows without scanning the attribute map.+ * Emitted only on Vercel (not local `eve dev`).+ */+ readonly emitVercelSessionId?: boolean;}/** OTel event definition and its trusted framework context runner. */@@ -93,6 +101,7 @@ export function createAgentOtelInstrumentation(): AgentOtelInstrumentation {const recordInputs = input.recordInputs ?? false;const recordOutputs = input.recordOutputs ?? false;+ const emitVercelSessionId = input.emitVercelSessionId ?? false;const executionContexts = new WeakMap<InstrumentationAttemptScope, Map<string, Context>>();const attemptScopes = new Map<string, InstrumentationAttemptScope>();// A serverless turn runs inside one `turnStep` "use step" invocation. If@@ -101,6 +110,7 @@ export function createAgentOtelInstrumentation(const steps = new WeakMap<InstrumentationAttemptScope, AttemptSpanState>();const modelSpans = new WeakMap<InstrumentationAttemptScope, Map<string, SpanState>>();const actions = createAgentActionInstrumentation({+ emitVercelSessionId,frameworkVersion: input.frameworkVersion,idGenerator: input.idGenerator,recordInputs,@@ -114,6 +124,7 @@ export function createAgentOtelInstrumentation(});const approvals = createAgentApprovalInstrumentation({actionContextFor: actions.contextFor,+ emitVercelSessionId,frameworkVersion: input.frameworkVersion,idGenerator: input.idGenerator,recordInputs,@@ -168,6 +179,9 @@ export function createAgentOtelInstrumentation("agent.step.index": event.scope.stepIndex,"agent.turn.id": event.scope.turnId,"agent.name": event.scope.functionId,+ ...(emitVercelSessionId+ ? { "vercel.session_id": event.scope.rootSessionId ?? event.scope.sessionId }+ : {}),...runtimeContextAttributes(event.runtimeContext),},links:@@ -274,6 +288,9 @@ export function createAgentOtelInstrumentation("agent.session.window": session?.window,"agent.turn.id": event.turnId,"agent.turn.sequence": turn.sequence,+ ...(emitVercelSessionId+ ? { "vercel.session_id": turn.rootSessionId }+ : {}),},startTime: turn.startTimeMs,},@@ -411,6 +428,7 @@ export function createAgentOtelInstrumentation(};const channelDeliveries = createAgentChannelDeliveryInstrumentation({+ emitVercelSessionId,ensureSessionContext,frameworkVersion: input.frameworkVersion,idGenerator: input.idGenerator,diff --git a/packages/eve/src/tracing/agent-otel-session-context.ts b/packages/eve/src/tracing/agent-otel-session-context.tsindex c0f2dbeac..3f0a1526e 100644--- a/packages/eve/src/tracing/agent-otel-session-context.ts+++ b/packages/eve/src/tracing/agent-otel-session-context.ts@@ -17,6 +17,7 @@ import {} from "#tracing/agent-trace-state.js";interface AgentOtelSessionContextInput {+ readonly emitVercelSessionId?: boolean;readonly frameworkVersion: string;readonly idGenerator: AgentSpanIdGenerator;readonly stateStore: AgentTraceStateStore;@@ -39,6 +40,7 @@ interface AgentOtelSessionContext {export function createAgentOtelSessionContext(input: AgentOtelSessionContextInput,): AgentOtelSessionContext {+ const emitVercelSessionId = input.emitVercelSessionId ?? false;const openSessionWindow = (window: {readonly agentName?: string;readonly channelAudience: ChannelAudience;@@ -65,6 +67,9 @@ export function createAgentOtelSessionContext("agent.session.id": window.sessionId,"agent.session.window": window.index,"agent.trace.schema.version": 1,+ ...(emitVercelSessionId+ ? { "vercel.session_id": window.rootSessionId }+ : {}),...(window.previousTraceId === undefined? {}: { "agent.session.window.previous.trace.id": window.previousTraceId }),diff --git a/packages/eve/src/tracing/install-instrumentation-runtime.ts b/packages/eve/src/tracing/install-instrumentation-runtime.tsindex 7c78c5e3f..adbc734f7 100644--- a/packages/eve/src/tracing/install-instrumentation-runtime.ts+++ b/packages/eve/src/tracing/install-instrumentation-runtime.ts@@ -10,6 +10,7 @@ import {type InstrumentationRuntime,} from "#harness/instrumentation/runtime.js";import { createLogger, formatError } from "#internal/logging.js";+import { isEveDevEnvironment } from "#internal/application/dev-environment.js";import { ContextAgentTraceStateStore } from "#tracing/agent-trace-context-store.js";import { createAgentOtelInstrumentation } from "#tracing/agent-otel-provider.js";import { hasSessionRelease, type LocalTracesProcessor } from "#tracing/local-traces.js";@@ -48,6 +49,7 @@ export function installInstrumentationRuntime(input: {serviceName: input.serviceName,});const agentOtel = createAgentOtelInstrumentation({+ emitVercelSessionId: process.env.VERCEL_ENV !== undefined && !isEveDevEnvironment(),frameworkVersion: input.frameworkVersion,idGenerator: otelRuntime.idGenerator,recordInputs: input.collected.settings.recordInputs,