The Open Framework for Building Agents
fix(eve): consult the OTel sampler for pre-allocated trace seeds (#2820)
Chad Hietala1982202d907b
diff --git a/.changeset/sampler-honest-trace-seed.md b/.changeset/sampler-honest-trace-seed.mdnew file mode 100644index 000000000..5dc25018f--- /dev/null+++ b/.changeset/sampler-honest-trace-seed.md@@ -0,0 +1,5 @@+---+"eve": patch+---++Pre-allocated session trace seeds now consult the configured OTel sampler, so `$eve.trace_id` workflow attributes are only stamped for traces the sampler will actually record. Previously an `always_off`, ratio, or custom sampler could leave links to traces that were never exported.diff --git a/packages/eve/src/instrumentation/runtime.test.ts b/packages/eve/src/instrumentation/runtime.test.tsindex bd3bc40aa..c6f9fcb48 100644--- a/packages/eve/src/instrumentation/runtime.test.ts+++ b/packages/eve/src/instrumentation/runtime.test.ts@@ -10,11 +10,13 @@ import type { InstrumentationHooks } from "#instrumentation/lifecycle.js";import {bindInstrumentationRuntime,bindSessionInstrumentation,+ initializeSessionInstrumentation,registerInstrumentationRuntime,type ExecutionInstrumentation,type InstrumentationRuntime,type InstrumentationStepScope,} from "#instrumentation/runtime.js";+import { AgentSpanIdGenerator } from "#tracing/agent-span-id-generator.js";import { ContextAgentTraceStateStore } from "#tracing/agent-trace-context-store.js";import type { TraceCapturePolicy } from "#tracing/otel-declaration.js";@@ -382,3 +384,59 @@ describe("bindSessionInstrumentation", () => {expect(ctx.get(SessionTraceSeedKey)).toBeUndefined();});});++describe("initializeSessionInstrumentation", () => {+ function registerSeedRuntime(input: {+ readonly samplesTrace?: (traceId: string) => boolean;+ readonly tracePolicy?: TraceCapturePolicy;+ }): void {+ registerInstrumentationRuntime({+ ...createRuntime({ capturesContent: true, publish: vi.fn() }, input.tracePolicy),+ idGenerator: new AgentSpanIdGenerator(),+ prepareSessionTrace: async () => ({ spanId: "", traceFlags: 0, traceId: "" }),+ samplesTrace: input.samplesTrace,+ });+ }++ it("marks the seed unsampled when the installed sampler drops the trace", () => {+ const samplesTrace = vi.fn(() => false);+ registerSeedRuntime({ samplesTrace });+ const ctx = createContext();++ initializeSessionInstrumentation({ agentName: "test-agent", ctx });++ const seed = ctx.get(SessionTraceSeedKey);+ expect(seed?.traceFlags).toBe(0);+ expect(seed?.decision).toMatchObject({ action: "record" });+ expect(samplesTrace).toHaveBeenCalledExactlyOnceWith(seed?.traceId);+ });++ it("keeps the seed sampled when the sampler admits the trace", () => {+ registerSeedRuntime({ samplesTrace: () => true });+ const ctx = createContext();++ initializeSessionInstrumentation({ agentName: "test-agent", ctx });++ expect(ctx.get(SessionTraceSeedKey)?.traceFlags).toBe(1);+ });++ it("stays sampled when no sampler capability is installed", () => {+ registerSeedRuntime({});+ const ctx = createContext();++ initializeSessionInstrumentation({ agentName: "test-agent", ctx });++ expect(ctx.get(SessionTraceSeedKey)?.traceFlags).toBe(1);+ });++ it("skips the sampler when policy already drops the trace", () => {+ const samplesTrace = vi.fn(() => true);+ registerSeedRuntime({ samplesTrace, tracePolicy: () => false });+ const ctx = createContext();++ initializeSessionInstrumentation({ agentName: "test-agent", ctx });++ expect(ctx.get(SessionTraceSeedKey)?.traceFlags).toBe(0);+ expect(samplesTrace).not.toHaveBeenCalled();+ });+});diff --git a/packages/eve/src/instrumentation/runtime.ts b/packages/eve/src/instrumentation/runtime.tsindex 387411173..9c8c045c3 100644--- a/packages/eve/src/instrumentation/runtime.ts+++ b/packages/eve/src/instrumentation/runtime.ts@@ -157,6 +157,8 @@ export interface InstrumentationRuntime {otelSettings: OtelHarnessSettings | undefined;readonly runtimeContextResolvers?: readonly RuntimeContextResolver[];readonly runInContext: InstrumentationContextRunner;+ /** Whether the installed OTel sampler would record a trace with this id. */+ readonly samplesTrace?: (traceId: string) => boolean;readonly shutdown: () => Promise<void>;stepStartedRuntimeContextResolver?: InstrumentationEvents["step.started"];}@@ -538,11 +540,13 @@ function allocateSessionTraceSeed(input: {audience: input.audience,channelType: input.channelType,});+ const traceId = input.runtime.idGenerator.generateTraceId();+ const sampled = decision.action === "record" && (input.runtime.samplesTrace?.(traceId) ?? true);return {decision,spanId: input.runtime.idGenerator.allocateSpanId(),- traceFlags: decision.action === "record" ? 1 : 0,- traceId: input.runtime.idGenerator.generateTraceId(),+ traceFlags: sampled ? 1 : 0,+ traceId,};}diff --git a/packages/eve/src/tracing/install-instrumentation-runtime.ts b/packages/eve/src/tracing/install-instrumentation-runtime.tsindex 5c8351bcb..4be229db1 100644--- a/packages/eve/src/tracing/install-instrumentation-runtime.ts+++ b/packages/eve/src/tracing/install-instrumentation-runtime.ts@@ -91,6 +91,7 @@ export function installInstrumentationRuntime(input: {prepareTurnTrace,runtimeContextResolvers: input.runtimeContextResolvers,runInContext,+ samplesTrace: otelRuntime?.samplesTrace,shutdown: () => {shutdown ??= settleAll([...(otelRuntime === undefined ? [] : [otelRuntime.shutdown]),diff --git a/packages/eve/src/tracing/otel-registration.scenario.test.ts b/packages/eve/src/tracing/otel-registration.scenario.test.tsindex 21a46f94d..f0b092cff 100644--- a/packages/eve/src/tracing/otel-registration.scenario.test.ts+++ b/packages/eve/src/tracing/otel-registration.scenario.test.ts@@ -70,6 +70,44 @@ describe("registerOtelPipeline", () => {).not.toThrow();});+ it("reports the installed sampler's verdict for pre-allocated trace ids", () => {+ const runtime = registerOtelPipeline({+ pipeline: { sampler: "always_off", spanProcessors: [] },+ serviceName: "weather",+ });++ expect(runtime.samplesTrace(runtime.idGenerator.generateTraceId())).toBe(false);+ });++ it("passes the pre-allocated trace id to a custom sampler without exporting the probe", async () => {+ const seen: string[] = [];+ const sampler: NonNullable<Parameters<typeof registerOtelPipeline>[0]["pipeline"]["sampler"]> =+ {+ shouldSample: (_context: unknown, traceId: string) => {+ seen.push(traceId);+ return { decision: traceId.startsWith("a") ? 2 : 0 };+ },+ toString: () => "test-sampler",+ };+ const exporter = new InMemorySpanExporter();+ const processor = new SimpleSpanProcessor(exporter);+ const runtime = registerOtelPipeline({+ pipeline: {+ sampler,+ spanProcessors: [processor],+ },+ serviceName: "weather",+ });++ expect(runtime.samplesTrace("a".repeat(32))).toBe(true);+ expect(runtime.samplesTrace("b".repeat(32))).toBe(false);+ expect(seen).toContain("a".repeat(32));+ expect(seen).toContain("b".repeat(32));++ await runtime.forceFlush();+ expect(exporter.getFinishedSpans()).toEqual([]);+ });+it("fails without replacing another runtime's global propagator", async () => {let foreignInjections = 0;const shutdown = vi.fn(async () => undefined);diff --git a/packages/eve/src/tracing/otel-registration.ts b/packages/eve/src/tracing/otel-registration.tsindex 5942bf334..860e367f5 100644--- a/packages/eve/src/tracing/otel-registration.ts+++ b/packages/eve/src/tracing/otel-registration.ts@@ -159,6 +159,7 @@ export function registerOtelPipeline(input: {return {forceFlush: () => provider.forceFlush!(),idGenerator,+ samplesTrace: (traceId) => samplerAdmitsTrace(idGenerator, traceId),shutdown: () => provider.shutdown!(),};}@@ -167,9 +168,18 @@ export function registerOtelPipeline(input: {export interface RegisteredOtelPipeline {readonly forceFlush: () => Promise<void>;readonly idGenerator: AgentSpanIdGenerator;+ /** Whether the installed sampler would record a trace with this id. */+ readonly samplesTrace: (traceId: string) => boolean;readonly shutdown: () => Promise<void>;}+function samplerAdmitsTrace(idGenerator: AgentSpanIdGenerator, traceId: string): boolean {+ const probe = idGenerator.withTraceId(traceId, () =>+ trace.getTracer("eve.registration").startSpan(REGISTRATION_SPAN_NAME, { root: true }),+ );+ return (probe.spanContext().traceFlags & 1) === 1;+}+interface RuntimeTracerProvider {forceFlush(): Promise<void>;shutdown(): Promise<void>;