Skip to content

armgit / eve

Public Imported from GitHub
0

The Open Framework for Building Agents

feat(eve): stamp Agent Runs OTEL enablement (#2560)

Chad Hietalad2995e12e0aa
diff --git a/.changeset/bright-traces-report.md b/.changeset/bright-traces-report.md
new file mode 100644
index 000000000..f5bf58b90
--- /dev/null
+++ b/.changeset/bright-traces-report.md
@@ -0,0 +1,5 @@
+---
+"eve": patch
+---
+
+Stamp Workflow runs with whether eve-managed OTEL tracing is enabled so dashboards can distinguish Workflow-only runs from enabled but unsampled traces. Session titles remain available alongside that metadata.
diff --git a/packages/eve/src/context/keys.ts b/packages/eve/src/context/keys.ts
index b13918770..fb9b2943d 100644
--- a/packages/eve/src/context/keys.ts
+++ b/packages/eve/src/context/keys.ts
@@ -103,6 +103,7 @@ export interface SessionTraceSeed {
readonly traceFlags: number;
}
export const SessionTraceSeedKey = new ContextKey<SessionTraceSeed>("eve.sessionTraceSeed");
+export const OtelTraceEnabledKey = new ContextKey<boolean>("eve.otelTraceEnabled");
export const SubagentDepthKey = new ContextKey<number>("eve.subagentDepth");
diff --git a/packages/eve/src/execution/eve-workflow-attributes.test.ts b/packages/eve/src/execution/eve-workflow-attributes.test.ts
index 90dfaa428..c16084909 100644
--- a/packages/eve/src/execution/eve-workflow-attributes.test.ts
+++ b/packages/eve/src/execution/eve-workflow-attributes.test.ts
@@ -163,6 +163,7 @@ describe("buildSessionAttributes", () => {
expect(attrs).toEqual({
"$eve.channel_request_id": undefined,
+ "$eve.is_otel_trace_enabled": false,
"$eve.is_trace_content_visible": true,
"$eve.trace_id": undefined,
"$eve.type": "session",
@@ -171,7 +172,7 @@ describe("buildSessionAttributes", () => {
});
});
- it("marks unknown sessions denied and omits their content-derived title", () => {
+ it("marks unknown sessions denied while retaining their stored title", () => {
const attrs = buildSessionAttributes({
inputMessage: "hi",
serializedContext: {},
@@ -179,7 +180,19 @@ describe("buildSessionAttributes", () => {
expect(attrs["$eve.trigger"]).toBeUndefined();
expect(attrs["$eve.is_trace_content_visible"]).toBe(false);
- expect(attrs["$eve.title"]).toBeUndefined();
+ expect(attrs["$eve.is_otel_trace_enabled"]).toBe(false);
+ expect(attrs["$eve.title"]).toBe("hi");
+ });
+
+ it("stamps hosted OTEL enablement without suppressing the stored title", () => {
+ const attrs = buildSessionAttributes({
+ inputMessage: "private prompt",
+ serializedContext: { "eve.otelTraceEnabled": true },
+ });
+
+ expect(attrs["$eve.is_otel_trace_enabled"]).toBe(true);
+ expect(attrs["$eve.is_trace_content_visible"]).toBe(false);
+ expect(attrs["$eve.title"]).toBe("private prompt");
});
it("allows unknown session content during local eve dev", () => {
@@ -244,6 +257,7 @@ describe("buildSubagentRootAttributes", () => {
expect(attrs).toEqual({
"$eve.channel_request_id": undefined,
+ "$eve.is_otel_trace_enabled": false,
"$eve.is_trace_content_visible": true,
"$eve.trace_id": undefined,
"$eve.type": "subagent",
@@ -297,6 +311,7 @@ describe("buildTurnAttributes", () => {
expect(attrs).toEqual({
"$eve.channel_request_id": undefined,
+ "$eve.is_otel_trace_enabled": false,
"$eve.is_trace_content_visible": true,
"$eve.trace_id": undefined,
"$eve.type": "turn",
diff --git a/packages/eve/src/execution/eve-workflow-attributes.ts b/packages/eve/src/execution/eve-workflow-attributes.ts
index d4a2b2e71..45f15252e 100644
--- a/packages/eve/src/execution/eve-workflow-attributes.ts
+++ b/packages/eve/src/execution/eve-workflow-attributes.ts
@@ -26,13 +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.is_otel_trace_enabled` — whether hosted Agent Runs OTEL is enabled for the run
* - `$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 { CHANNEL_CONTEXT_KEY_NAME } from "#context/key-names.js";
-import { ChannelRequestIdKey, type SessionTraceSeed } from "#context/keys.js";
+import { ChannelRequestIdKey, OtelTraceEnabledKey, 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";
@@ -97,6 +98,10 @@ export function isWorkflowTraceContentVisible(serializedContext: Record<string,
return shouldCaptureInstrumentationContent(normalizeChannelAudience(channel?.audience));
}
+export function isWorkflowOtelTraceEnabled(serializedContext: Record<string, unknown>): boolean {
+ return serializedContext[OtelTraceEnabledKey.name] === true;
+}
+
export function readSessionTraceId(serializedContext: Record<string, unknown>): string | undefined {
const seed = serializedContext["eve.sessionTraceSeed"] as SessionTraceSeed | undefined;
if (seed === undefined || !isSampledTrace(seed)) return undefined;
@@ -234,13 +239,15 @@ export function buildSessionAttributes(input: {
readonly serializedContext: Record<string, unknown>;
}): Record<string, EveAttributeValue> {
const isTraceContentVisible = isWorkflowTraceContentVisible(input.serializedContext);
+ const isOtelTraceEnabled = isWorkflowOtelTraceEnabled(input.serializedContext);
return {
"$eve.channel_request_id": readChannelRequestId(input.serializedContext),
+ "$eve.is_otel_trace_enabled": isOtelTraceEnabled,
"$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,
+ "$eve.title": deriveSessionTitle(input.inputMessage),
};
}
@@ -263,6 +270,7 @@ export function buildSubagentRootAttributes(input: {
}): Record<string, EveAttributeValue> {
return {
"$eve.channel_request_id": readChannelRequestId(input.serializedContext),
+ "$eve.is_otel_trace_enabled": isWorkflowOtelTraceEnabled(input.serializedContext),
"$eve.is_trace_content_visible": isWorkflowTraceContentVisible(input.serializedContext),
"$eve.trace_id": readSessionTraceId(input.serializedContext),
"$eve.type": "subagent",
@@ -293,6 +301,7 @@ export function buildTurnAttributes(input: {
}): Record<string, EveAttributeValue> {
return {
"$eve.channel_request_id": input.requestId,
+ "$eve.is_otel_trace_enabled": isWorkflowOtelTraceEnabled(input.serializedContext),
"$eve.is_trace_content_visible": isWorkflowTraceContentVisible(input.serializedContext),
"$eve.trace_id": readSessionTraceId(input.serializedContext),
"$eve.type": "turn",
diff --git a/packages/eve/src/execution/workflow-runtime.test.ts b/packages/eve/src/execution/workflow-runtime.test.ts
index 9299f453c..61a953cbb 100644
--- a/packages/eve/src/execution/workflow-runtime.test.ts
+++ b/packages/eve/src/execution/workflow-runtime.test.ts
@@ -356,13 +356,16 @@ describe("createWorkflowRuntime#createSession", () => {
"eve.bundle": { source: compiledArtifactsSource },
"eve.channel": expect.objectContaining({ kind: "http", state: {} }),
"eve.mode": "task",
+ "eve.otelTraceEnabled": false,
}),
},
],
{
allowReservedAttributes: true,
attributes: {
+ "$eve.is_otel_trace_enabled": "false",
"$eve.is_trace_content_visible": "false",
+ "$eve.title": "hello",
"$eve.trigger": "http",
"$eve.type": "session",
},
@@ -371,7 +374,7 @@ describe("createWorkflowRuntime#createSession", () => {
);
});
- it("withholds an explicit title for an unknown-audience workflow", async () => {
+ it("stores an explicit title alongside the trace-content policy", async () => {
const compiledArtifactsSource = {} as RuntimeCompiledArtifactsSource;
mockBundleAndRun(compiledArtifactsSource);
startMock.mockResolvedValue({ runId: "driver-run" });
@@ -388,7 +391,8 @@ describe("createWorkflowRuntime#createSession", () => {
const [, workflowInput, startOptions] = startMock.mock.calls[0]!;
expect(workflowInput[0].input.message).toBe(message);
expect(startOptions.attributes["$eve.is_trace_content_visible"]).toBe("false");
- expect(startOptions.attributes["$eve.title"]).toBeUndefined();
+ expect(startOptions.attributes["$eve.is_otel_trace_enabled"]).toBe("false");
+ expect(startOptions.attributes["$eve.title"]).toBe("ship it");
});
it("passes the configured session timeout to the durable workflow", async () => {
@@ -471,7 +475,9 @@ describe("createWorkflowRuntime#createSession", () => {
allowReservedAttributes: true,
attributes: {
"$eve.channel_request_id": "req_run",
+ "$eve.is_otel_trace_enabled": "false",
"$eve.is_trace_content_visible": "false",
+ "$eve.title": "hello",
"$eve.trigger": "http",
"$eve.type": "session",
},
@@ -511,6 +517,7 @@ describe("createWorkflowRuntime#createSession", () => {
expect(startMock).toHaveBeenCalledWith(workflowEntryReference, expect.any(Array), {
allowReservedAttributes: true,
attributes: {
+ "$eve.is_otel_trace_enabled": "false",
"$eve.parent": "parent-session",
"$eve.parent_call": "call-1",
"$eve.parent_turn": "turn-1",
@@ -541,7 +548,9 @@ describe("createWorkflowRuntime#createSession", () => {
expect(startMock).toHaveBeenNthCalledWith(1, workflowEntryReference, expect.any(Array), {
allowReservedAttributes: true,
attributes: {
+ "$eve.is_otel_trace_enabled": "false",
"$eve.is_trace_content_visible": "false",
+ "$eve.title": "hello",
"$eve.trigger": "http",
"$eve.type": "session",
},
@@ -550,7 +559,9 @@ describe("createWorkflowRuntime#createSession", () => {
expect(startMock).toHaveBeenNthCalledWith(2, workflowEntryReference, expect.any(Array), {
allowReservedAttributes: true,
attributes: {
+ "$eve.is_otel_trace_enabled": "false",
"$eve.is_trace_content_visible": "false",
+ "$eve.title": "hello",
"$eve.trigger": "http",
"$eve.type": "session",
},
@@ -584,7 +595,9 @@ describe("createWorkflowRuntime#createSession", () => {
expect(startMock).toHaveBeenCalledWith(workflowEntryReference, expect.any(Array), {
allowReservedAttributes: true,
attributes: {
+ "$eve.is_otel_trace_enabled": "false",
"$eve.is_trace_content_visible": "false",
+ "$eve.title": "hello",
"$eve.trigger": "http",
"$eve.type": "session",
},
@@ -710,6 +723,8 @@ describe("createWorkflowRuntime#createSession trace seed allocation", () => {
expect(seed).toBeDefined();
expect(seed!.traceFlags).toBe(1);
expect(seed!.traceId).toMatch(/^[0-9a-f]{32}$/u);
+ expect(serialized["eve.otelTraceEnabled"]).toBe(true);
+ expect(startMock.mock.calls[0]?.[2].attributes["$eve.is_otel_trace_enabled"]).toBe("true");
});
it("passes the channel adapter kind as channelType to the policy", async () => {
@@ -795,6 +810,8 @@ describe("createWorkflowRuntime#createSession trace seed allocation", () => {
| { traceId: string; spanId: string; traceFlags: number }
| undefined;
expect(seed).toEqual(parentTrace);
+ expect(serialized["eve.otelTraceEnabled"]).toBe(true);
+ expect(startMock.mock.calls[0]?.[2].attributes["$eve.is_otel_trace_enabled"]).toBe("true");
});
it("does not allocate a seed when no instrumentation runtime is installed", async () => {
@@ -811,6 +828,7 @@ describe("createWorkflowRuntime#createSession trace seed allocation", () => {
const [, workflowInput] = startMock.mock.calls[0]!;
const serialized = workflowInput[0].serializedContext as Record<string, unknown>;
expect(serialized["eve.sessionTraceSeed"]).toBeUndefined();
+ expect(serialized["eve.otelTraceEnabled"]).toBe(false);
});
it("does not allocate a seed when the runtime has no prepareSessionTrace", async () => {
@@ -841,5 +859,7 @@ describe("createWorkflowRuntime#createSession trace seed allocation", () => {
const [, workflowInput] = startMock.mock.calls[0]!;
const serialized = workflowInput[0].serializedContext as Record<string, unknown>;
expect(serialized["eve.sessionTraceSeed"]).toBeUndefined();
+ expect(serialized["eve.otelTraceEnabled"]).toBe(false);
+ expect(startMock.mock.calls[0]?.[2].attributes["$eve.is_otel_trace_enabled"]).toBe("false");
});
});
diff --git a/packages/eve/src/execution/workflow-runtime.ts b/packages/eve/src/execution/workflow-runtime.ts
index 37fd2e203..2ce6a4c55 100644
--- a/packages/eve/src/execution/workflow-runtime.ts
+++ b/packages/eve/src/execution/workflow-runtime.ts
@@ -20,6 +20,7 @@ import type {
import { serializeContext } from "#context/serialize.js";
import {
ChannelInstrumentationKey,
+ OtelTraceEnabledKey,
SessionTraceSeedKey,
type SessionTraceSeed,
} from "#context/keys.js";
@@ -156,6 +157,7 @@ export function createWorkflowRuntime(config: {
if (traceSeed !== undefined) {
ctx.set(SessionTraceSeedKey, traceSeed);
}
+ ctx.set(OtelTraceEnabledKey, getInstrumentationRuntime()?.prepareSessionTrace !== undefined);
const serializedContext = serializeContext(ctx);
const parentLineage = readParentLineage(serializedContext);
const sessionTimeoutMs = effectiveAgent.limits?.sessionTimeoutMs;
diff --git a/packages/eve/src/execution/workflow-steps.test.ts b/packages/eve/src/execution/workflow-steps.test.ts
index d45a46bd5..03b7cd7ea 100644
--- a/packages/eve/src/execution/workflow-steps.test.ts
+++ b/packages/eve/src/execution/workflow-steps.test.ts
@@ -680,6 +680,7 @@ describe("dispatchTurnStep", () => {
allowReservedAttributes: true,
attributes: {
"$eve.channel_request_id": "req_turn",
+ "$eve.is_otel_trace_enabled": "false",
"$eve.parent": "sess-test",
"$eve.root": "sess-test",
"$eve.is_trace_content_visible": "false",
@@ -719,6 +720,7 @@ describe("dispatchTurnStep", () => {
allowReservedAttributes: true,
attributes: {
"$eve.channel_request_id": "req_turn",
+ "$eve.is_otel_trace_enabled": "false",
"$eve.parent": "sess-test",
"$eve.root": "sess-test",
"$eve.is_trace_content_visible": "false",
@@ -742,6 +744,7 @@ describe("dispatchTurnStep", () => {
allowReservedAttributes: true,
attributes: {
"$eve.channel_request_id": "req_turn",
+ "$eve.is_otel_trace_enabled": "false",
"$eve.parent": "sess-test",
"$eve.root": "sess-test",
"$eve.is_trace_content_visible": "false",
@@ -753,6 +756,7 @@ describe("dispatchTurnStep", () => {
allowReservedAttributes: true,
attributes: {
"$eve.channel_request_id": "req_turn",
+ "$eve.is_otel_trace_enabled": "false",
"$eve.parent": "sess-test",
"$eve.root": "sess-test",
"$eve.is_trace_content_visible": "false",