The Open Framework for Building Agents
fix(eve): parent action spans to steps (#2234)
Chad Hietala8a3288dc7156
diff --git a/.changeset/quiet-steps-replay.md b/.changeset/quiet-steps-replay.mdnew file mode 100644index 000000000..ced856fee--- /dev/null+++ b/.changeset/quiet-steps-replay.md@@ -0,0 +1,5 @@+---+"eve": patch+---++Parent `agent.action` OpenTelemetry spans to their replay-stable `agent.step` boundary instead of directly to the turn.diff --git a/packages/eve/src/tracing/agent-action-instrumentation.ts b/packages/eve/src/tracing/agent-action-instrumentation.tsindex fb66de6c7..4cad11bfb 100644--- a/packages/eve/src/tracing/agent-action-instrumentation.ts+++ b/packages/eve/src/tracing/agent-action-instrumentation.ts@@ -14,7 +14,7 @@ import type {InstrumentationAttemptScope,InstrumentationProviderDefinition,} from "#harness/instrumentation/lifecycle.js";-import { actionIdempotencyKey } from "#harness/instrumentation/lifecycle.js";+import { actionIdempotencyKey, attemptIdempotencyKey } from "#harness/instrumentation/lifecycle.js";import { contentAttribute } from "#tracing/agent-otel-content.js";import { setAgentUsage } from "#tracing/agent-otel-usage.js";import type { AgentSpanIdGenerator } from "#tracing/agent-span-id-generator.js";@@ -46,20 +46,17 @@ export function createAgentActionInstrumentation(input: {readonly idGenerator: AgentSpanIdGenerator;readonly recordInputs: boolean;readonly recordOutputs: boolean;- readonly resolveParent: (+ readonly resolveTraceContext: (event: InstrumentationActionStartedEvent,- ) =>- | { readonly context: Context; readonly spanContext: SpanContext }- | undefined- | PromiseLike<{ readonly context: Context; readonly spanContext: SpanContext } | undefined>;+ ) => SpanContext | undefined | PromiseLike<SpanContext | undefined>;readonly stateStore: AgentTraceStateStore;readonly tracer: Tracer;}): AgentActionInstrumentation {const byAttempt = new Map<string, Set<string>>();const onStarted = async (event: InstrumentationActionStartedEvent): Promise<void> => {- const parent = await input.resolveParent(event);- if (parent === undefined) return;+ const traceContext = await input.resolveTraceContext(event);+ if (traceContext === undefined) return;const existing = await input.stateStore.getAction(event.idempotencyKey);const state: AgentActionTraceState = existing ?? {@@ -69,9 +66,9 @@ export function createAgentActionInstrumentation(input: {kind: event.kind,name: event.name,parent: {- spanId: parent.spanContext.spanId,- traceFlags: parent.spanContext.traceFlags,- traceId: parent.spanContext.traceId,+ spanId: input.idGenerator.deriveSpanId(attemptIdempotencyKey(event.scope)),+ traceFlags: traceContext.traceFlags,+ traceId: traceContext.traceId,},rootSessionId: event.scope.rootSessionId ?? event.scope.sessionId,sessionId: event.scope.sessionId,diff --git a/packages/eve/src/tracing/agent-otel-provider.test.ts b/packages/eve/src/tracing/agent-otel-provider.test.tsindex 6af342eb7..fe2416717 100644--- a/packages/eve/src/tracing/agent-otel-provider.test.ts+++ b/packages/eve/src/tracing/agent-otel-provider.test.ts@@ -677,7 +677,7 @@ describe("createAgentOtelInstrumentation", () => {apiTrace.getSpan(parent as never)?.spanContext().spanId === model.spanContext().spanId,),).toBe(true);- expect(action.parentSpanContext?.spanId).toBe(turn.spanContext().spanId);+ expect(action.parentSpanContext?.spanId).toBe(step.spanContext().spanId);expect(tool.parentSpanContext?.spanId).toBe(action.spanContext().spanId);expect(new Set(@@ -765,7 +765,7 @@ describe("createAgentOtelInstrumentation", () => {}});- it("keeps logical ids stable but separates physical redeliveries", async () => {+ it("keeps replayable boundary ids stable across physical redeliveries", async () => {const first = createRuntime();const redelivery = createRuntime();const parentTraceContext: InstrumentationTraceContext = {@@ -788,12 +788,12 @@ describe("createAgentOtelInstrumentation", () => {const firstSpans = first.exporter.getFinishedSpans();const redeliverySpans = redelivery.exporter.getFinishedSpans();- for (const name of ["agent.turn", "agent.action", "ai.toolCall"]) {+ for (const name of ["agent.turn", "agent.step", "agent.action", "ai.toolCall"]) {expect(byName(redeliverySpans, name)[0]!.spanContext().spanId).toBe(byName(firstSpans, name)[0]!.spanContext().spanId,);}- for (const name of ["agent.step", "ai.streamText", "chat claude-test"]) {+ for (const name of ["ai.streamText", "chat claude-test"]) {expect(byName(redeliverySpans, name)[0]!.spanContext().spanId).not.toBe(byName(firstSpans, name)[0]!.spanContext().spanId,);@@ -971,7 +971,7 @@ describe("createAgentOtelInstrumentation", () => {const action = byName(replacementSpans, "agent.action")[0]!;const tool = byName(replacementSpans, "ai.toolCall")[0]!;expect(action.spanContext().spanId).toBe(tool.parentSpanContext?.spanId);- expect(action.parentSpanContext?.spanId).toBe(step.parentSpanContext?.spanId);+ expect(action.parentSpanContext?.spanId).toBe(step.spanContext().spanId);expect(action.attributes).toMatchObject({"agent.action.kind": "tool-call","agent.action.name": "weather",@@ -1508,7 +1508,7 @@ describe("createAgentOtelInstrumentation", () => {const action = byName(replacementSpans, "agent.action")[0]!;expect(step.parentSpanContext?.spanId).toBe(turn.spanContext().spanId);- expect(action.parentSpanContext?.spanId).toBe(turn.spanContext().spanId);+ expect(action.parentSpanContext?.spanId).toBe(step.spanContext().spanId);expect(step.spanContext().traceId).toBe(turn.spanContext().traceId);});diff --git a/packages/eve/src/tracing/agent-otel-provider.ts b/packages/eve/src/tracing/agent-otel-provider.tsindex 7b87ef11a..3e2122617 100644--- a/packages/eve/src/tracing/agent-otel-provider.ts+++ b/packages/eve/src/tracing/agent-otel-provider.ts@@ -43,6 +43,7 @@ import type {InstrumentationTurnStartedEvent,InstrumentationTurnTerminalEvent,} from "#harness/instrumentation/lifecycle.js";+import { attemptIdempotencyKey } from "#harness/instrumentation/lifecycle.js";interface SpanState {readonly context: Context;@@ -99,11 +100,9 @@ export function createAgentOtelInstrumentation(idGenerator: input.idGenerator,recordInputs,recordOutputs,- resolveParent: async (event) => {+ resolveTraceContext: async (event) => {const turn = await input.stateStore.getTurn(event.scope.sessionId, event.scope.turnId);- return turn === undefined- ? undefined- : { context: contextFromSpanContext(turn.context), spanContext: turn.context };+ return turn?.context;},stateStore: input.stateStore,tracer: input.tracer,@@ -146,31 +145,35 @@ export function createAgentOtelInstrumentation(if (turn === undefined) return;const turnContext = contextFromSpanContext(turn.context);const activeSpanContext = trace.getSpan(context.active())?.spanContext();- const stepSpan = input.tracer.startSpan(- "agent.step",- {- attributes: {- "agent.session.id": event.scope.sessionId,- "agent.framework.name": "eve",- "agent.framework.version": input.frameworkVersion,- "agent.root.session.id": event.scope.rootSessionId ?? event.scope.sessionId,- "agent.step.attempt": event.scope.attemptIndex,- "agent.step.index": event.scope.stepIndex,- "agent.turn.id": event.scope.turnId,- "agent.name": event.scope.functionId,- ...runtimeContextAttributes(event.runtimeContext),- },- links:- activeSpanContext === undefined || activeSpanContext.traceId === turn.context.traceId- ? undefined- : [- {- attributes: { "eve.link.type": "workflow.delivery" },- context: activeSpanContext,- },- ],- },- turnContext,+ const stepSpan = input.idGenerator.withSpanId(+ input.idGenerator.deriveSpanId(attemptIdempotencyKey(event.scope)),+ () =>+ input.tracer.startSpan(+ "agent.step",+ {+ attributes: {+ "agent.session.id": event.scope.sessionId,+ "agent.framework.name": "eve",+ "agent.framework.version": input.frameworkVersion,+ "agent.root.session.id": event.scope.rootSessionId ?? event.scope.sessionId,+ "agent.step.attempt": event.scope.attemptIndex,+ "agent.step.index": event.scope.stepIndex,+ "agent.turn.id": event.scope.turnId,+ "agent.name": event.scope.functionId,+ ...runtimeContextAttributes(event.runtimeContext),+ },+ links:+ activeSpanContext === undefined || activeSpanContext.traceId === turn.context.traceId+ ? undefined+ : [+ {+ attributes: { "eve.link.type": "workflow.delivery" },+ context: activeSpanContext,+ },+ ],+ },+ turnContext,+ ),);stepSpan.addEvent("step.started");const stepContext = trace.setSpan(turnContext, stepSpan);diff --git a/packages/eve/src/tracing/local-instrumentation-runtime.scenario.test.ts b/packages/eve/src/tracing/local-instrumentation-runtime.scenario.test.tsindex cea9bbba7..bd6c42626 100644--- a/packages/eve/src/tracing/local-instrumentation-runtime.scenario.test.ts+++ b/packages/eve/src/tracing/local-instrumentation-runtime.scenario.test.ts@@ -35,7 +35,7 @@ afterEach(async () => {});describe("local instrumentation runtime", () => {- it("persists agent, AI, and user spans in one trace", async () => {+ it("persists the agent trace hierarchy in OTLP segments", async () => {const appRoot = await mkdtemp(join(tmpdir(), "eve-local-traces-"));temporaryDirectories.push(appRoot);// Resolve and cache the public API tracer before eve installs its vendored@@ -195,19 +195,17 @@ describe("local instrumentation runtime", () => {}),);const spans = spanGroups.flat();- expect(spans.map((span) => span.name)).toEqual(- expect.arrayContaining([- "agent.turn",- "agent.step",- "ai.streamText",- "chat model-1",- "agent.action",- "ai.toolCall",- "user.model-work",- "user.tool-work",- ]),- );- expect(span(spans, "agent.step").parentSpanId).toBe(span(spans, "agent.turn").spanId);+ expect(formatTraceTree(spans)).toEqual([+ "agent.session",+ " agent.turn",+ " agent.step",+ " agent.action",+ " ai.toolCall",+ " user.tool-work",+ " ai.streamText",+ " chat model-1",+ " user.model-work",+ ]);expect(span(spans, "agent.step").links).toEqual([expect.objectContaining({attributes: expect.arrayContaining([@@ -220,12 +218,6 @@ describe("local instrumentation runtime", () => {traceId: delivery.spanContext().traceId,}),]);- expect(span(spans, "ai.streamText").parentSpanId).toBe(span(spans, "agent.step").spanId);- expect(span(spans, "chat model-1").parentSpanId).toBe(span(spans, "ai.streamText").spanId);- expect(span(spans, "user.model-work").parentSpanId).toBe(span(spans, "chat model-1").spanId);- expect(span(spans, "agent.action").parentSpanId).toBe(span(spans, "agent.turn").spanId);- expect(span(spans, "ai.toolCall").parentSpanId).toBe(span(spans, "agent.action").spanId);- expect(span(spans, "user.tool-work").parentSpanId).toBe(span(spans, "ai.toolCall").spanId);const listed = await listLocalTraces(appRoot);expect(listed).toHaveLength(1);expect(listed[0]).toMatchObject({ sessionId: "session-1", traceId });@@ -280,3 +272,29 @@ interface OtlpRequest {function span(spans: readonly OtlpSpan[], name: string): OtlpSpan {return spans.find((candidate) => candidate.name === name)!;}++function formatTraceTree(spans: readonly OtlpSpan[]): string[] {+ const children = Map.groupBy(spans, (candidate) => candidate.parentSpanId);+ const lines: string[] = [];+ const visited = new Set<string>();++ const append = (current: OtlpSpan, depth: number): void => {+ visited.add(current.spanId);+ lines.push(`${" ".repeat(depth)}${current.name}`);+ for (const child of (children.get(current.spanId) ?? []).toSorted((a, b) =>+ a.name.localeCompare(b.name),+ )) {+ append(child, depth + 1);+ }+ };++ for (const root of (children.get(undefined) ?? []).toSorted((a, b) =>+ a.name.localeCompare(b.name),+ )) {+ append(root, 0);+ }+ for (const orphan of spans.filter((candidate) => !visited.has(candidate.spanId))) {+ lines.push(`[orphan parent=${orphan.parentSpanId ?? "none"}] ${orphan.name}`);+ }+ return lines;+}