Skip to content

armgit / eve

Public Imported from GitHub
0

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.md
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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>;