Skip to content

armgit / eve

Public Imported from GitHub
0

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