Skip to content

armgit / eve

Public Imported from GitHub
0

The Open Framework for Building Agents

feat(eve): connect workflow runs to agent traces (#2490)

Chad Hietala7ed4fb135e85
diff --git a/.changeset/eve-trace-id-attribute.md b/.changeset/eve-trace-id-attribute.md
new file mode 100644
index 000000000..8c1d7be7e
--- /dev/null
+++ b/.changeset/eve-trace-id-attribute.md
@@ -0,0 +1,5 @@
+---
+"eve": patch
+---
+
+Workflow session, subagent, and turn rows now include `$eve.trace_id` when a sampled agent trace is available, allowing workflow views to open the corresponding OpenTelemetry trace directly. Rows without an exported agent trace omit the attribute.
diff --git a/docs/guides/instrumentation.md b/docs/guides/instrumentation.md
index 71c26eea6..253e79a13 100644
--- a/docs/guides/instrumentation.md
+++ b/docs/guides/instrumentation.md
@@ -164,6 +164,7 @@ Structural tags describe each run's place in the tree:
- `$eve.subagent`: compiled graph node id (subagent runs only)
- `$eve.trigger`: the channel kind that started the run
- `$eve.title`: truncated title derived from the first user message
+- `$eve.trace_id`: trace id of the sampled agent trace containing the run, written on session, subagent, and turn rows so a dashboard run can be joined to its OpenTelemetry trace. Present only when the trace is sampled; absence means no exported OTEL trace exists.
Per-turn usage tags are written on each step of a turn, accumulating cumulative totals (last write wins):
diff --git a/packages/eve/src/execution/eve-workflow-attributes.test.ts b/packages/eve/src/execution/eve-workflow-attributes.test.ts
index be8b0bec1..f8ec45f12 100644
--- a/packages/eve/src/execution/eve-workflow-attributes.test.ts
+++ b/packages/eve/src/execution/eve-workflow-attributes.test.ts
@@ -11,6 +11,7 @@ import {
readParentLineage,
readParentSessionId,
readRootSessionId,
+ readSessionTraceId,
} from "#execution/eve-workflow-attributes.js";
import { ChannelRequestIdKey } from "#context/keys.js";
@@ -151,6 +152,7 @@ describe("buildSessionAttributes", () => {
expect(attrs).toEqual({
"$eve.channel_request_id": undefined,
"$eve.is_trace_content_visible": true,
+ "$eve.trace_id": undefined,
"$eve.type": "session",
"$eve.trigger": "slack",
"$eve.title": "ship the thing please",
@@ -191,6 +193,30 @@ describe("buildSessionAttributes", () => {
expect(attrs["$eve.channel_request_id"]).toBe("req_session");
});
+
+ it("emits $eve.trace_id from a sampled trace seed", () => {
+ const attrs = buildSessionAttributes({
+ inputMessage: "hi",
+ serializedContext: {
+ ...slackChannelCtx,
+ "eve.sessionTraceSeed": { spanId: "a".repeat(16), traceFlags: 1, traceId: "b".repeat(32) },
+ },
+ });
+
+ expect(attrs["$eve.trace_id"]).toBe("b".repeat(32));
+ });
+
+ it("withholds $eve.trace_id from an unsampled trace seed", () => {
+ const attrs = buildSessionAttributes({
+ inputMessage: "hi",
+ serializedContext: {
+ ...slackChannelCtx,
+ "eve.sessionTraceSeed": { spanId: "a".repeat(16), traceFlags: 0, traceId: "b".repeat(32) },
+ },
+ });
+
+ expect(attrs["$eve.trace_id"]).toBeUndefined();
+ });
});
describe("buildSubagentRootAttributes", () => {
@@ -207,6 +233,7 @@ describe("buildSubagentRootAttributes", () => {
expect(attrs).toEqual({
"$eve.channel_request_id": undefined,
"$eve.is_trace_content_visible": true,
+ "$eve.trace_id": undefined,
"$eve.type": "subagent",
"$eve.parent": "wrun_parent_subagent",
"$eve.parent_call": "call_subagent_0",
@@ -230,6 +257,22 @@ describe("buildSubagentRootAttributes", () => {
expect(attrs["$eve.channel_request_id"]).toBe("req_subagent");
});
+
+ it("emits $eve.trace_id from a sampled trace seed", () => {
+ const attrs = buildSubagentRootAttributes({
+ identity: { nodeId: "subagents/linear" },
+ parentCallId: "call_subagent_0",
+ parentSessionId: "wrun_parent_subagent",
+ parentTurnId: "turn_0",
+ rootSessionId: "wrun_top_level_session",
+ serializedContext: {
+ ...subagentChainCtx,
+ "eve.sessionTraceSeed": { spanId: "e".repeat(16), traceFlags: 1, traceId: "f".repeat(32) },
+ },
+ });
+
+ expect(attrs["$eve.trace_id"]).toBe("f".repeat(32));
+ });
});
describe("buildTurnAttributes", () => {
@@ -243,6 +286,7 @@ describe("buildTurnAttributes", () => {
expect(attrs).toEqual({
"$eve.channel_request_id": undefined,
"$eve.is_trace_content_visible": true,
+ "$eve.trace_id": undefined,
"$eve.type": "turn",
"$eve.parent": "wrun_session_123",
"$eve.root": "wrun_session_123",
@@ -259,4 +303,39 @@ describe("buildTurnAttributes", () => {
expect(attrs["$eve.channel_request_id"]).toBe("req_turn");
});
+
+ it("emits $eve.trace_id from a sampled trace seed", () => {
+ const attrs = buildTurnAttributes({
+ parentSessionId: "wrun_session_123",
+ rootSessionId: "wrun_session_123",
+ serializedContext: {
+ ...slackChannelCtx,
+ "eve.sessionTraceSeed": { spanId: "c".repeat(16), traceFlags: 1, traceId: "d".repeat(32) },
+ },
+ });
+
+ expect(attrs["$eve.trace_id"]).toBe("d".repeat(32));
+ });
+});
+
+describe("readSessionTraceId", () => {
+ it("returns the trace id from a sampled seed", () => {
+ expect(
+ readSessionTraceId({
+ "eve.sessionTraceSeed": { spanId: "a".repeat(16), traceFlags: 1, traceId: "b".repeat(32) },
+ }),
+ ).toBe("b".repeat(32));
+ });
+
+ it("returns undefined for an unsampled seed", () => {
+ expect(
+ readSessionTraceId({
+ "eve.sessionTraceSeed": { spanId: "a".repeat(16), traceFlags: 0, traceId: "b".repeat(32) },
+ }),
+ ).toBeUndefined();
+ });
+
+ it("returns undefined when no seed is present", () => {
+ expect(readSessionTraceId({})).toBeUndefined();
+ });
});
diff --git a/packages/eve/src/execution/eve-workflow-attributes.ts b/packages/eve/src/execution/eve-workflow-attributes.ts
index 396bc370e..08bcfcc56 100644
--- a/packages/eve/src/execution/eve-workflow-attributes.ts
+++ b/packages/eve/src/execution/eve-workflow-attributes.ts
@@ -26,10 +26,14 @@
* - `$eve.invocation_token` — channel-local continuation token for an external invocation
* - `$eve.invocation_owner` — SHA-256 fingerprint of the invocation's initiating principal
* - `$eve.is_trace_content_visible` — whether observability may read content-bearing workflow data
+ * - `$eve.trace_id` — trace id of the `agent.session` span, read from the pre-allocated
+ * trace seed in the serialized context. Present only when the trace is sampled;
+ * absence means no exported OTEL trace exists.
*/
-import { ChannelRequestIdKey } from "#context/keys.js";
+import { ChannelRequestIdKey, type SessionTraceSeed } from "#context/keys.js";
import { shouldCaptureInstrumentationContent } from "#harness/instrumentation/content-policy.js";
+import { isSampledTrace } from "#tracing/sampled-trace.js";
import type { EveAttributeValue } from "#runtime/attributes/normalize.js";
import { normalizeChannelAudience } from "#shared/channel-audience.js";
import { isNonEmptyString } from "#shared/guards.js";
@@ -88,6 +92,12 @@ export function isWorkflowTraceContentVisible(serializedContext: Record<string,
return shouldCaptureInstrumentationContent(normalizeChannelAudience(channel?.audience));
}
+export function readSessionTraceId(serializedContext: Record<string, unknown>): string | undefined {
+ const seed = serializedContext["eve.sessionTraceSeed"] as SessionTraceSeed | undefined;
+ if (seed === undefined || !isSampledTrace(seed)) return undefined;
+ return isNonEmptyString(seed.traceId) ? seed.traceId : undefined;
+}
+
/**
* Reads parent session lineage from a deserialized context map. Returns
* an empty object for top-level runs or malformed delegated contexts.
@@ -222,6 +232,7 @@ export function buildSessionAttributes(input: {
return {
"$eve.channel_request_id": readChannelRequestId(input.serializedContext),
"$eve.is_trace_content_visible": isTraceContentVisible,
+ "$eve.trace_id": readSessionTraceId(input.serializedContext),
"$eve.type": "session",
"$eve.trigger": readChannelKind(input.serializedContext),
"$eve.title": isTraceContentVisible ? deriveSessionTitle(input.inputMessage) : undefined,
@@ -248,6 +259,7 @@ export function buildSubagentRootAttributes(input: {
return {
"$eve.channel_request_id": readChannelRequestId(input.serializedContext),
"$eve.is_trace_content_visible": isWorkflowTraceContentVisible(input.serializedContext),
+ "$eve.trace_id": readSessionTraceId(input.serializedContext),
"$eve.type": "subagent",
"$eve.parent": input.parentSessionId,
"$eve.parent_call": input.parentCallId,
@@ -277,6 +289,7 @@ export function buildTurnAttributes(input: {
return {
"$eve.channel_request_id": input.requestId,
"$eve.is_trace_content_visible": isWorkflowTraceContentVisible(input.serializedContext),
+ "$eve.trace_id": readSessionTraceId(input.serializedContext),
"$eve.type": "turn",
"$eve.parent": input.parentSessionId,
"$eve.root": input.rootSessionId,
diff --git a/packages/eve/src/tracing/sampled-trace.ts b/packages/eve/src/tracing/sampled-trace.ts
index bd22801a2..a545e9be7 100644
--- a/packages/eve/src/tracing/sampled-trace.ts
+++ b/packages/eve/src/tracing/sampled-trace.ts
@@ -1,9 +1,12 @@
-import { TraceFlags, type SpanContext } from "#compiled/@opentelemetry/api/index.js";
import type { ChannelAudience } from "#shared/channel-audience.js";
import type { TraceCapturePolicy } from "#tracing/otel-declaration.js";
-export function isSampledTrace(context: Pick<SpanContext, "traceFlags">): boolean {
- return (context.traceFlags & TraceFlags.SAMPLED) === TraceFlags.SAMPLED;
+// W3C sampled flag; written as a literal so this module stays out of the
+// vendored OTel chunk, which the workflow driver bundle cannot include.
+const TRACE_FLAGS_SAMPLED = 0x01;
+
+export function isSampledTrace(context: { readonly traceFlags: number }): boolean {
+ return (context.traceFlags & TRACE_FLAGS_SAMPLED) === TRACE_FLAGS_SAMPLED;
}
export function evaluateTracePolicy(