Skip to content

armgit / eve

Public Imported from GitHub
0

The Open Framework for Building Agents

feat(eve): configure audience-aware tracing (#2335)

Chad Hietala47e8b64df647
diff --git a/.changeset/calm-pandas-trace.md b/.changeset/calm-pandas-trace.md
new file mode 100644
index 000000000..5c0966fc9
--- /dev/null
+++ b/.changeset/calm-pandas-trace.md
@@ -0,0 +1,5 @@
+---
+"eve": minor
+---
+
+Make traces public-only by default while retaining unclassified HTTP/TUI sessions in zero-config local tracing, and add composable input/output redaction, span filtering, and attribute filtering to the export pipeline.
diff --git a/packages/eve/src/cli/dev/tui/traces/trace-view.ts b/packages/eve/src/cli/dev/tui/traces/trace-view.ts
index 3164db3ab..a4fd76a5f 100644
--- a/packages/eve/src/cli/dev/tui/traces/trace-view.ts
+++ b/packages/eve/src/cli/dev/tui/traces/trace-view.ts
@@ -304,7 +304,7 @@ function renderConversation(
if (state.conversationItems.length === 0) {
return [
chromeStyles(theme, options.surfaces).muted(
- " No conversation content in this trace — content capture may be off (EVE_TRACES_CONTENT).",
+ " No conversation content in this trace; its export policy may have redacted it.",
),
];
}
diff --git a/packages/eve/src/execution/workflow-trace-context.ts b/packages/eve/src/execution/workflow-trace-context.ts
index 86dbbd246..264d64428 100644
--- a/packages/eve/src/execution/workflow-trace-context.ts
+++ b/packages/eve/src/execution/workflow-trace-context.ts
@@ -1,5 +1,9 @@
import type { ContextContainer } from "#context/container.js";
-import { ParentSessionKey, ParentTraceContextKey } from "#context/keys.js";
+import {
+ ChannelInstrumentationKey,
+ ParentSessionKey,
+ ParentTraceContextKey,
+} from "#context/keys.js";
import type { HarnessEmissionState } from "#harness/emission.js";
import { getInstrumentationRuntime } from "#harness/instrumentation/runtime.js";
import { resolveParentLineage } from "#harness/parent-lineage.js";
@@ -7,6 +11,7 @@ import { prepareTurnTraceContext } from "#harness/prepare-trace-context.js";
import type { HarnessSession } from "#harness/types.js";
import type { RuntimeIdentity, RuntimeTraceContext } from "#protocol/message.js";
import { ChannelKey } from "#runtime/sessions/runtime-context-keys.js";
+import { normalizeChannelAudience } from "#shared/channel-audience.js";
/** Prepares native tracing for workflow-owned preambles emitted outside the tool loop. */
export async function prepareWorkflowPreambleTrace(input: {
@@ -16,8 +21,10 @@ export async function prepareWorkflowPreambleTrace(input: {
readonly session: HarnessSession;
}): Promise<RuntimeTraceContext | undefined> {
const parent = input.ctx.get(ParentSessionKey);
+ const channel = input.ctx.get(ChannelInstrumentationKey);
return await prepareTurnTraceContext({
agentName: input.runtimeIdentity.agentName,
+ channelAudience: normalizeChannelAudience(channel?.metadata.audience),
instrumentation: getInstrumentationRuntime(),
parentLineage: resolveParentLineage(parent, input.ctx.get(ChannelKey)),
parentTraceContext: input.ctx.get(ParentTraceContextKey),
diff --git a/packages/eve/src/harness/channel-delivery-instrumentation.ts b/packages/eve/src/harness/channel-delivery-instrumentation.ts
index 3ede9df1e..dabfe29f6 100644
--- a/packages/eve/src/harness/channel-delivery-instrumentation.ts
+++ b/packages/eve/src/harness/channel-delivery-instrumentation.ts
@@ -2,6 +2,7 @@ import type { DeliverHookPayload, DeliverPayload } from "#channel/types.js";
import type { AlsContext } from "#context/container.js";
import {
ActiveChannelDeliveriesKey,
+ ChannelInstrumentationKey,
ParentTraceContextKey,
type ActiveChannelDelivery,
} from "#context/keys.js";
@@ -11,6 +12,7 @@ import type {
InstrumentationHooks,
} from "#harness/instrumentation/lifecycle.js";
import { channelDeliveryIdempotencyKey } from "#harness/instrumentation/lifecycle.js";
+import { normalizeChannelAudience } from "#shared/channel-audience.js";
interface ChannelDeliveryStartInstrumentation {
readonly agentName?: string;
@@ -68,9 +70,13 @@ export async function instrumentChannelDelivery(
if (input.hooks === undefined || input.delivery.deliveryMetadata === undefined) return;
const active: ActiveChannelDelivery[] = [];
+ const channelAudience = normalizeChannelAudience(
+ input.ctx.get(ChannelInstrumentationKey)?.metadata.audience,
+ );
for (const metadata of input.delivery.deliveryMetadata) {
const payload = input.delivery.payloads[metadata.payloadIndex];
const delivery = {
+ channelAudience,
channelKind: metadata.channelKind,
channelName: metadata.channelName,
deliveryId: metadata.deliveryId,
diff --git a/packages/eve/src/harness/instrumentation/lifecycle.ts b/packages/eve/src/harness/instrumentation/lifecycle.ts
index 239e64a5a..9598608c0 100644
--- a/packages/eve/src/harness/instrumentation/lifecycle.ts
+++ b/packages/eve/src/harness/instrumentation/lifecycle.ts
@@ -1,6 +1,7 @@
import { createInstrumentationDispatcher } from "#harness/instrumentation/dispatch.js";
import type { InstrumentationStateSlot } from "#harness/instrumentation/state.js";
import type { RuntimeTraceContext } from "#protocol/message.js";
+import type { ChannelAudience } from "#shared/channel-audience.js";
/**
* Stable eve identity for one actual model attempt.
@@ -12,6 +13,7 @@ import type { RuntimeTraceContext } from "#protocol/message.js";
* fire once per attempt.
*/
export interface InstrumentationAttemptScope {
+ readonly channelAudience?: ChannelAudience;
readonly attemptId: string;
readonly attemptIndex: number;
readonly functionId?: string;
@@ -160,6 +162,7 @@ export function channelDeliveryIdempotencyKey(sessionId: string, deliveryId: str
}
export interface InstrumentationChannelDeliveryRef {
+ readonly channelAudience?: ChannelAudience;
readonly channelKind: string;
readonly channelName: string;
readonly deliveryId: string;
@@ -281,6 +284,7 @@ export interface InstrumentationSessionStartedEvent {
readonly type: "session.started";
readonly agentName?: string;
readonly channelKind?: string;
+ readonly channelAudience?: ChannelAudience;
readonly idempotencyKey: string;
readonly parentTraceContext?: InstrumentationTraceContext;
readonly rootSessionId: string;
diff --git a/packages/eve/src/harness/instrumentation/native-events.ts b/packages/eve/src/harness/instrumentation/native-events.ts
index 5dfc62bad..0987c371f 100644
--- a/packages/eve/src/harness/instrumentation/native-events.ts
+++ b/packages/eve/src/harness/instrumentation/native-events.ts
@@ -29,10 +29,12 @@ import type { ResolvedInputBatch } from "#harness/input-requests.js";
import { RuntimeActionSettlementTimesKey } from "#harness/runtime-action-settlement-state.js";
import type { HandleEventFn } from "#harness/types.js";
import type { RuntimeActionRequest, RuntimeActionResult } from "#runtime/actions/types.js";
+import type { ChannelAudience } from "#shared/channel-audience.js";
export interface CreateInstrumentationHandleEventInput {
readonly agentName?: string;
readonly channelKind?: string;
+ readonly channelAudience?: ChannelAudience;
readonly getAttemptScope?: () => InstrumentationAttemptScope | undefined;
readonly handleEvent?: HandleEventFn;
readonly hooks?: InstrumentationHooks;
@@ -292,6 +294,7 @@ function toLifecycleEvent(
case "session.started":
return {
agentName: input.agentName,
+ channelAudience: input.channelAudience,
channelKind: input.channelKind,
idempotencyKey: sessionIdempotencyKey(input.sessionId),
parentTraceContext: input.parentTraceContext,
diff --git a/packages/eve/src/harness/instrumentation/providers.test.ts b/packages/eve/src/harness/instrumentation/providers.test.ts
index f8695ad2d..80a4964fb 100644
--- a/packages/eve/src/harness/instrumentation/providers.test.ts
+++ b/packages/eve/src/harness/instrumentation/providers.test.ts
@@ -152,7 +152,7 @@ describe("seedInstrumentationProviders", () => {
it("lets an authored reserved slot reconfigure or disable its default", async () => {
seedInstrumentationProviders();
- const authored = localTraces({ recordInputs: false });
+ const authored = localTraces({ exportPolicy: { span: () => false } });
await register("local", authored);
expect(getInstrumentationProviders()).toEqual([{ provider: authored, slot: "local" }]);
@@ -160,11 +160,11 @@ describe("seedInstrumentationProviders", () => {
expect(getInstrumentationProviders()).toEqual([]);
});
- it("lets an authored Agent Runs slot narrow the production default", async () => {
+ it("lets an authored Agent Runs slot reconfigure the production default", async () => {
vi.stubEnv(DEVELOPMENT_WORKER_APP_ROOT_ENV, undefined);
vi.stubEnv("VERCEL_ENV", "production");
seedInstrumentationProviders();
- const authored = agentRuns({ recordOutputs: false });
+ const authored = agentRuns({ exportPolicy: { span: () => false } });
await register("agent-runs", authored);
@@ -176,7 +176,7 @@ describe("seedInstrumentationProviders", () => {
seedInstrumentationProviders();
await register("zeta", defineInstrumentation({}));
await register("audit", defineInstrumentation({}));
- await register("local", localTraces({ recordInputs: false }));
+ await register("local", localTraces({ exportPolicy: { span: () => false } }));
expect(getInstrumentationProviders().map(({ slot }) => slot)).toEqual([
"agent-runs",
diff --git a/packages/eve/src/harness/prepare-trace-context.ts b/packages/eve/src/harness/prepare-trace-context.ts
index 92873c1e0..d8c1d6735 100644
--- a/packages/eve/src/harness/prepare-trace-context.ts
+++ b/packages/eve/src/harness/prepare-trace-context.ts
@@ -6,12 +6,14 @@ import type {
} from "#harness/instrumentation/lifecycle.js";
import { sessionIdempotencyKey, turnIdempotencyKey } from "#harness/instrumentation/lifecycle.js";
import type { HarnessInstrumentation } from "#harness/instrumentation/runtime.js";
+import type { ChannelAudience } from "#shared/channel-audience.js";
const log = createLogger("harness.prepare-trace-context");
/** Prepares native session/turn tracing before their durable stream events. */
export async function prepareTurnTraceContext(input: {
readonly agentName?: string;
+ readonly channelAudience?: ChannelAudience;
readonly instrumentation?: HarnessInstrumentation;
readonly parentLineage?: InstrumentationParentLineage;
readonly parentTraceContext?: InstrumentationTraceContext;
@@ -28,6 +30,7 @@ export async function prepareTurnTraceContext(input: {
try {
prepared = await input.instrumentation.prepareSessionTrace({
agentName: input.agentName,
+ channelAudience: input.channelAudience,
idempotencyKey: sessionIdempotencyKey(input.sessionId),
parentTraceContext: input.parentTraceContext,
rootSessionId: input.rootSessionId,
diff --git a/packages/eve/src/harness/tool-loop.ts b/packages/eve/src/harness/tool-loop.ts
index df4f29351..5a1e77d5d 100644
--- a/packages/eve/src/harness/tool-loop.ts
+++ b/packages/eve/src/harness/tool-loop.ts
@@ -55,6 +55,7 @@ import {
import { buildDynamicSubagentTools } from "#context/dynamic-subagent-lifecycle.js";
import { PendingSkillAnnouncementKey } from "#context/dynamic-skill-lifecycle.js";
import { toErrorMessage } from "#shared/errors.js";
+import { normalizeChannelAudience } from "#shared/channel-audience.js";
import {
createActionResultEvent,
createApprovalCandidateEvent,
@@ -648,6 +649,7 @@ export function createToolLoopHarness(config: ToolLoopHarnessConfig): StepFn {
let emissionState = getHarnessEmissionState(session.state);
const store = contextStorage.getStore();
+ const channelInstrumentation = store?.get(ChannelInstrumentationKey);
const parent = store?.get(ParentSessionKey);
const channel = store?.get(ChannelKey);
const callback = store?.get(SessionCallbackKey);
@@ -661,7 +663,8 @@ export function createToolLoopHarness(config: ToolLoopHarnessConfig): StepFn {
let activeAttemptScope: InstrumentationAttemptScope | undefined;
const emit = createInstrumentationHandleEvent({
agentName: config.runtimeIdentity?.agentName,
- channelKind: store?.get(ChannelInstrumentationKey)?.kind,
+ channelAudience: normalizeChannelAudience(channelInstrumentation?.metadata.audience),
+ channelKind: channelInstrumentation?.kind,
getAttemptScope: () => activeAttemptScope,
handleEvent: baseEmit,
hooks: config.instrumentation?.hooks,
@@ -718,6 +721,7 @@ export function createToolLoopHarness(config: ToolLoopHarnessConfig): StepFn {
: undefined;
return await prepareTurnTraceContext({
agentName: config.runtimeIdentity?.agentName,
+ channelAudience: normalizeChannelAudience(channelInstrumentation?.metadata.audience),
instrumentation: config.instrumentation,
parentLineage,
parentTraceContext,
@@ -1497,6 +1501,7 @@ export function createToolLoopHarness(config: ToolLoopHarnessConfig): StepFn {
: {
attemptId: `${session.sessionId}:${instrumentationTurnId}:${emissionState.stepIndex}:${opts.attemptIndex}`,
attemptIndex: opts.attemptIndex,
+ channelAudience: normalizeChannelAudience(channelInstrumentation?.metadata.audience),
functionId: otelSettings?.functionId ?? agentName,
rootSessionId: parent?.rootSessionId ?? session.sessionId,
sessionId: session.sessionId,
diff --git a/packages/eve/src/public/instrumentation/otel.ts b/packages/eve/src/public/instrumentation/otel.ts
index 0a988bec7..15c43e72b 100644
--- a/packages/eve/src/public/instrumentation/otel.ts
+++ b/packages/eve/src/public/instrumentation/otel.ts
@@ -12,8 +12,8 @@
import { createLocalTracesProcessor, resolveLocalTracesContent } from "#tracing/local-traces.js";
import {
agentRunsIntegration,
- otelIntegration,
- type ContentOptions,
+ managedOtelIntegration,
+ type ManagedTraceOptions,
type OtelIntegration,
} from "#tracing/otel-declaration.js";
@@ -22,11 +22,22 @@ export {
isOtelIntegration,
otel,
otelIntegration,
+ composeSpanExportPolicies,
+ redactSpanInputs,
+ redactSpanOutputs,
type ContentOptions,
type OtelDeclaration,
type OtelIntegration,
type OtelIntegrationOptions,
type OtelOptions,
+ type ManagedTraceOptions,
+ type SpanAttributeDecision,
+ type SpanExportAttributeValue,
+ type SpanExportContext,
+ type SpanExportPolicy,
+ type SpanExportPredicate,
+ type TraceCaptureContext,
+ type TraceCapturePolicy,
} from "#tracing/otel-declaration.js";
export type { SpanExporter, SpanProcessor } from "#compiled/@vercel/otel/index.js";
@@ -34,10 +45,10 @@ export type { SpanExporter, SpanProcessor } from "#compiled/@vercel/otel/index.j
/**
* Vercel Agent Runs, enabled by default in production.
*
- * Export it from `agent/instrumentation/agent-runs.ts` to configure content
- * capture, or export `disableInstrumentation()` from that file to turn it off.
+ * Export it from `agent/instrumentation/agent-runs.ts` to configure export, or
+ * export `disableInstrumentation()` from that file to turn it off.
*/
-export function agentRuns(options: ContentOptions = {}): OtelIntegration {
+export function agentRuns(options: ManagedTraceOptions = {}): OtelIntegration {
return agentRunsIntegration(options);
}
@@ -47,13 +58,10 @@ export function agentRuns(options: ContentOptions = {}): OtelIntegration {
* Export it from `agent/instrumentation/local.ts` to keep it alongside a hosted
* backend, or export `disableInstrumentation()` from that file to turn it off.
* Omitting the file leaves eve's default in place.
- *
- * `EVE_TRACES_CONTENT=on` opts the default local spool into content capture.
- * `off` overrides this destination and no other, so declining content locally
- * leaves what a hosted backend receives alone.
*/
-export function localTraces(options: ContentOptions = {}): OtelIntegration {
- return otelIntegration({
+export function localTraces(options: ManagedTraceOptions = {}): OtelIntegration {
+ return managedOtelIntegration({
+ ...options,
...resolveLocalTracesContent(options),
spanProcessors: [createLocalTracesProcessor()],
});
diff --git a/packages/eve/src/tracing/agent-action-instrumentation.ts b/packages/eve/src/tracing/agent-action-instrumentation.ts
index 4cad11bfb..83de88e60 100644
--- a/packages/eve/src/tracing/agent-action-instrumentation.ts
+++ b/packages/eve/src/tracing/agent-action-instrumentation.ts
@@ -19,6 +19,9 @@ 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";
import type { AgentActionTraceState, AgentTraceStateStore } from "#tracing/agent-trace-state.js";
+import { normalizeChannelAudience } from "#shared/channel-audience.js";
+import { isSampledTrace } from "#tracing/sampled-trace.js";
+import { withChannelAudience } from "#tracing/channel-audience-context.js";
export interface AgentActionInstrumentation {
readonly events: Pick<
@@ -56,12 +59,13 @@ export function createAgentActionInstrumentation(input: {
const onStarted = async (event: InstrumentationActionStartedEvent): Promise<void> => {
const traceContext = await input.resolveTraceContext(event);
- if (traceContext === undefined) return;
+ if (traceContext === undefined || !isSampledTrace(traceContext)) return;
const existing = await input.stateStore.getAction(event.idempotencyKey);
const state: AgentActionTraceState = existing ?? {
attemptIndex: event.scope.attemptIndex,
callId: event.callId,
+ channelAudience: normalizeChannelAudience(event.scope.channelAudience),
inputAttribute: input.recordInputs ? contentAttribute(event.input, false) : undefined,
kind: event.kind,
name: event.name,
@@ -185,13 +189,19 @@ function actionContext(state: AgentActionTraceState): AgentActionContext {
traceId: state.parent.traceId,
};
return {
- context: trace.setSpan(ROOT_CONTEXT, trace.wrapSpanContext(spanContext)),
+ context: withChannelAudience(
+ trace.setSpan(ROOT_CONTEXT, trace.wrapSpanContext(spanContext)),
+ state.channelAudience,
+ ),
spanContext,
};
}
function contextFromActionState(state: AgentActionTraceState): Context {
- return trace.setSpan(ROOT_CONTEXT, trace.wrapSpanContext({ ...state.parent, isRemote: false }));
+ return withChannelAudience(
+ trace.setSpan(ROOT_CONTEXT, trace.wrapSpanContext({ ...state.parent, isRemote: false })),
+ state.channelAudience,
+ );
}
function recordError(span: Span, error: unknown): void {
diff --git a/packages/eve/src/tracing/agent-approval-instrumentation.ts b/packages/eve/src/tracing/agent-approval-instrumentation.ts
index 6f095249c..cff37245b 100644
--- a/packages/eve/src/tracing/agent-approval-instrumentation.ts
+++ b/packages/eve/src/tracing/agent-approval-instrumentation.ts
@@ -17,11 +17,13 @@ import type { JsonValue } from "#shared/json.js";
import { contentAttribute } from "#tracing/agent-otel-content.js";
import type { AgentActionContext } from "#tracing/agent-action-instrumentation.js";
import type { AgentSpanIdGenerator } from "#tracing/agent-span-id-generator.js";
+import { normalizeChannelAudience, type ChannelAudience } from "#shared/channel-audience.js";
interface AgentApprovalSpanState {
readonly actionCallId: string;
readonly actionName: string;
readonly attemptIndex: number;
+ readonly channelAudience: ChannelAudience;
readonly parent: SpanContext;
readonly requestAttribute?: string;
readonly requestId: string;
@@ -63,6 +65,7 @@ export function createAgentApprovalInstrumentation(input: {
actionCallId: event.action.callId,
actionName: event.action.name,
attemptIndex: event.scope.attemptIndex,
+ channelAudience: normalizeChannelAudience(event.scope.channelAudience),
parent: {
spanId: parent.spanContext.spanId,
traceFlags: parent.spanContext.traceFlags,
@@ -158,6 +161,7 @@ function readState(value: unknown): AgentApprovalSpanState | undefined {
actionCallId: state["actionCallId"],
actionName: state["actionName"],
attemptIndex: state["attemptIndex"],
+ channelAudience: normalizeChannelAudience(state["channelAudience"]),
parent: {
isRemote: false,
spanId: parentRecord["spanId"],
diff --git a/packages/eve/src/tracing/agent-channel-delivery-instrumentation.ts b/packages/eve/src/tracing/agent-channel-delivery-instrumentation.ts
index 97f861953..d363e9ac5 100644
--- a/packages/eve/src/tracing/agent-channel-delivery-instrumentation.ts
+++ b/packages/eve/src/tracing/agent-channel-delivery-instrumentation.ts
@@ -17,11 +17,14 @@ import type {
} from "#harness/instrumentation/lifecycle.js";
import { sessionIdempotencyKey } from "#harness/instrumentation/lifecycle.js";
import type { JsonValue } from "#shared/json.js";
+import { normalizeChannelAudience, type ChannelAudience } from "#shared/channel-audience.js";
import { contentAttribute } from "#tracing/agent-otel-content.js";
import type { AgentSpanIdGenerator } from "#tracing/agent-span-id-generator.js";
import type { AgentSessionTraceState, AgentTraceStateStore } from "#tracing/agent-trace-state.js";
+import { isSampledTrace } from "#tracing/sampled-trace.js";
interface ChannelDeliverySpanState {
+ readonly channelAudience: ChannelAudience;
readonly inputAttribute?: string;
readonly parent: SpanContext;
readonly requestTraceContext?: SpanContext;
@@ -53,6 +56,7 @@ export function createAgentChannelDeliveryInstrumentation(input: {
): Promise<void> => {
const session = await input.ensureSessionContext({
agentName: event.agentName,
+ channelAudience: event.delivery.channelAudience,
channelKind: event.delivery.channelKind,
idempotencyKey: sessionIdempotencyKey(event.sessionId),
parentTraceContext: event.parentTraceContext,
@@ -60,8 +64,10 @@ export function createAgentChannelDeliveryInstrumentation(input: {
sessionId: event.sessionId,
type: "session.started",
});
+ if (!isSampledTrace(session.context)) return;
const inputAttribute = input.recordInputs ? contentAttribute(event.input, false) : undefined;
const state: Record<string, JsonValue> = {
+ channelAudience: normalizeChannelAudience(event.delivery.channelAudience),
parent: {
isRemote: session.context.isRemote ?? false,
spanId: session.context.spanId,
@@ -178,6 +184,7 @@ function readState(value: unknown): ChannelDeliverySpanState | undefined {
? value.requestTraceContext
: undefined;
return {
+ channelAudience: normalizeChannelAudience(value.channelAudience),
inputAttribute: typeof value.inputAttribute === "string" ? value.inputAttribute : undefined,
parent: value.parent,
requestTraceContext,
diff --git a/packages/eve/src/tracing/agent-otel-provider.test.ts b/packages/eve/src/tracing/agent-otel-provider.test.ts
index fe2416717..849d4e849 100644
--- a/packages/eve/src/tracing/agent-otel-provider.test.ts
+++ b/packages/eve/src/tracing/agent-otel-provider.test.ts
@@ -15,7 +15,10 @@ import {
import { ContextContainer, contextStorage } from "#context/container.js";
import { deserializeContext, serializeContext } from "#context/serialize.js";
import { createAiSdkHookBridge } from "#harness/ai-sdk-hook-bridge.js";
-import { createAgentOtelInstrumentation } from "#tracing/agent-otel-provider.js";
+import {
+ createAgentOtelInstrumentation,
+ type AgentOtelInstrumentationInput,
+} from "#tracing/agent-otel-provider.js";
import { AgentSpanIdGenerator } from "#tracing/agent-span-id-generator.js";
import { ContextAgentTraceStateStore } from "#tracing/agent-trace-context-store.js";
import {
@@ -33,6 +36,8 @@ import {
type InstrumentationTraceContext,
type InstrumentationUsage,
} from "#harness/instrumentation/lifecycle.js";
+import type { ChannelAudience } from "#shared/channel-audience.js";
+import type { TraceCapturePolicy } from "#tracing/otel-declaration.js";
import {
actionIdempotencyKey,
attemptIdempotencyKey,
@@ -56,6 +61,7 @@ interface TestRuntime {
function createRuntime(
stateStore: AgentTraceStateStore = new InMemoryAgentTraceStateStore(),
+ tracePolicy: TraceCapturePolicy | null = () => true,
): TestRuntime {
const exporter = new InMemorySpanExporter();
const idGenerator = new AgentSpanIdGenerator();
@@ -64,14 +70,18 @@ function createRuntime(
spanProcessors: [new SimpleSpanProcessor(exporter)],
});
const tracer = provider.getTracer("eve.agent");
- const agentOtel = createAgentOtelInstrumentation({
+ const agentOtelInput: Omit<AgentOtelInstrumentationInput, "tracePolicy"> & {
+ tracePolicy?: TraceCapturePolicy;
+ } = {
frameworkVersion: "test",
idGenerator,
recordInputs: true,
recordOutputs: true,
stateStore,
tracer,
- });
+ };
+ if (tracePolicy !== null) agentOtelInput.tracePolicy = tracePolicy;
+ const agentOtel = createAgentOtelInstrumentation(agentOtelInput);
const hooks = createInstrumentationHooks([agentOtel.hook]);
return {
exporter,
@@ -88,6 +98,7 @@ async function emitAttempt(input: {
readonly actionUsage?: InstrumentationUsage;
readonly attemptIndex?: number;
readonly attemptError?: Error;
+ readonly channelAudience?: ChannelAudience;
readonly hooks: InstrumentationHooks;
readonly parentTraceContext?: InstrumentationTraceContext;
readonly runInContext: InstrumentationContextRunner;
@@ -105,6 +116,7 @@ async function emitAttempt(input: {
const scope: InstrumentationAttemptScope = {
attemptId: `${input.sessionId}:${input.turnId}:0:${input.attemptIndex ?? 0}`,
attemptIndex: input.attemptIndex ?? 0,
+ channelAudience: input.channelAudience,
functionId: "weather",
sessionId: input.sessionId,
stepIndex: 0,
@@ -274,6 +286,7 @@ async function emitAttempt(input: {
}
async function publishTurnStarted(input: {
+ readonly channelAudience?: ChannelAudience;
readonly hooks: InstrumentationHooks;
readonly parentLineage?: InstrumentationParentLineage;
readonly parentTraceContext?: InstrumentationTraceContext;
@@ -285,6 +298,7 @@ async function publishTurnStarted(input: {
const rootSessionId = input.rootSessionId ?? input.sessionId;
await input.hooks.publish({
agentName: "weather",
+ channelAudience: input.channelAudience,
channelKind: "http",
idempotencyKey: sessionIdempotencyKey(input.sessionId),
parentTraceContext: input.parentTraceContext,
@@ -632,6 +646,7 @@ describe("createAgentOtelInstrumentation", () => {
const contextWith = vi.spyOn(context, "with");
await context.with(activeContext, () =>
emitAttempt({
+ channelAudience: "public",
hooks: runtime.hooks,
runInContext: runtime.runInContext,
sessionId: "session-1",
@@ -657,6 +672,7 @@ describe("createAgentOtelInstrumentation", () => {
expect(session.parentSpanContext).toBeUndefined();
expect(session.events.map((event) => event.name)).toEqual(["session.started"]);
expect(session.attributes).toMatchObject({
+ "agent.channel.audience": "public",
"agent.session.id": "session-1",
"agent.session.window": 0,
"agent.trace.schema.version": 1,
@@ -679,6 +695,9 @@ describe("createAgentOtelInstrumentation", () => {
).toBe(true);
expect(action.parentSpanContext?.spanId).toBe(step.spanContext().spanId);
expect(tool.parentSpanContext?.spanId).toBe(action.spanContext().spanId);
+ for (const span of [turn, step, operation, model, action, tool]) {
+ expect(span.attributes).not.toHaveProperty("agent.channel.audience");
+ }
expect(
new Set(
spans
@@ -710,6 +729,62 @@ describe("createAgentOtelInstrumentation", () => {
});
});
+ it.each(["private", "unknown"] as const)(
+ "does not record %s conversation traces by default",
+ async (audience) => {
+ const runtime = createRuntime(new InMemoryAgentTraceStateStore(), null);
+
+ await emitAttempt({
+ channelAudience: audience,
+ hooks: runtime.hooks,
+ runInContext: runtime.runInContext,
+ sessionId: `session-${audience}`,
+ turnId: `turn-${audience}`,
+ turnSequence: 0,
+ });
+ await runtime.provider.forceFlush();
+
+ expect(runtime.exporter.getFinishedSpans()).toEqual([]);
+ },
+ );
+
+ it("applies the private audience gate to an adopted sampled trace", async () => {
+ const runtime = createRuntime(new InMemoryAgentTraceStateStore(), null);
+
+ await emitAttempt({
+ channelAudience: "private",
+ hooks: runtime.hooks,
+ parentTraceContext: {
+ spanId: "a".repeat(16),
+ traceFlags: 1,
+ traceId: "b".repeat(32),
+ },
+ runInContext: runtime.runInContext,
+ sessionId: "session-private",
+ turnId: "turn-private",
+ turnSequence: 0,
+ });
+ await runtime.provider.forceFlush();
+
+ expect(runtime.exporter.getFinishedSpans()).toEqual([]);
+ });
+
+ it("allows private tracing when the trace policy opts in", async () => {
+ const runtime = createRuntime(new InMemoryAgentTraceStateStore(), () => true);
+
+ await emitAttempt({
+ channelAudience: "private",
+ hooks: runtime.hooks,
+ runInContext: runtime.runInContext,
+ sessionId: "session-private",
+ turnId: "turn-private",
+ turnSequence: 0,
+ });
+ await runtime.provider.forceFlush();
+
+ expect(byName(runtime.exporter.getFinishedSpans(), "agent.session")).toHaveLength(1);
+ });
+
it("writes merged runtime context onto the step, operation, and chat spans", async () => {
const runtime = createRuntime();
diff --git a/packages/eve/src/tracing/agent-otel-provider.ts b/packages/eve/src/tracing/agent-otel-provider.ts
index 3e2122617..2900345e0 100644
--- a/packages/eve/src/tracing/agent-otel-provider.ts
+++ b/packages/eve/src/tracing/agent-otel-provider.ts
@@ -27,6 +27,10 @@ import { createAgentChannelDeliveryInstrumentation } from "#tracing/agent-channe
import { createAgentToolInstrumentation } from "#tracing/agent-tool-instrumentation.js";
import { setAgentUsage } from "#tracing/agent-otel-usage.js";
import { createAgentOtelSessionContext } from "#tracing/agent-otel-session-context.js";
+import type { TraceCapturePolicy } from "#tracing/otel-declaration.js";
+import { isSampledTrace } from "#tracing/sampled-trace.js";
+import { withChannelAudience } from "#tracing/channel-audience-context.js";
+import { suppressTracing } from "#tracing/suppress-tracing.js";
import type {
InstrumentationStepAttemptMetadataEvent,
InstrumentationAttemptScope,
@@ -68,6 +72,7 @@ export interface AgentOtelInstrumentationInput {
readonly idGenerator: AgentSpanIdGenerator;
readonly stateStore: AgentTraceStateStore;
readonly tracer: Tracer;
+ readonly tracePolicy?: TraceCapturePolicy;
}
/** OTel event definition and its trusted framework context runner. */
@@ -142,8 +147,11 @@ export function createAgentOtelInstrumentation(
const onStepStarted = async (event: InstrumentationStepAttemptStartedEvent): Promise<void> => {
const turn = await input.stateStore.getTurn(event.scope.sessionId, event.scope.turnId);
- if (turn === undefined) return;
- const turnContext = contextFromSpanContext(turn.context);
+ if (turn === undefined || !isSampledTrace(turn.context)) return;
+ const turnContext = withChannelAudience(
+ contextFromSpanContext(turn.context),
+ event.scope.channelAudience,
+ );
const activeSpanContext = trace.getSpan(context.active())?.spanContext();
const stepSpan = input.idGenerator.withSpanId(
input.idGenerator.deriveSpanId(attemptIdempotencyKey(event.scope)),
@@ -251,39 +259,41 @@ export function createAgentOtelInstrumentation(
const turn = await input.stateStore.getTurn(event.sessionId, event.turnId);
if (turn !== undefined) {
const session = await input.stateStore.getSession(event.sessionId);
- const span = input.idGenerator.withSpanId(turn.context.spanId, () =>
- input.tracer.startSpan(
- "agent.turn",
- {
- attributes: {
- "agent.framework.name": "eve",
- "agent.framework.version": input.frameworkVersion,
- "agent.name": session?.agentName,
- ...parentLineageAttributes(turn.lineage),
- "agent.root.session.id": turn.rootSessionId,
- "agent.session.id": event.sessionId,
- "agent.session.window": session?.window,
- "agent.turn.id": event.turnId,
- "agent.turn.sequence": turn.sequence,
+ if (isSampledTrace(turn.context)) {
+ const span = input.idGenerator.withSpanId(turn.context.spanId, () =>
+ input.tracer.startSpan(
+ "agent.turn",
+ {
+ attributes: {
+ "agent.framework.name": "eve",
+ "agent.framework.version": input.frameworkVersion,
+ "agent.name": session?.agentName,
+ ...parentLineageAttributes(turn.lineage),
+ "agent.root.session.id": turn.rootSessionId,
+ "agent.session.id": event.sessionId,
+ "agent.session.window": session?.window,
+ "agent.turn.id": event.turnId,
+ "agent.turn.sequence": turn.sequence,
+ },
+ startTime: turn.startTimeMs,
},
- startTime: turn.startTimeMs,
- },
- contextFromSpanContext({
- isRemote: turn.parentIsRemote ?? false,
- spanId: turn.parentSpanId,
- traceFlags: turn.context.traceFlags,
- traceId: turn.context.traceId,
- }),
- ),
- );
- span.addEvent("turn.started", undefined, turn.startTimeMs);
- if (turn.terminal !== undefined) {
- span.addEvent(turn.terminal.type);
- if (turn.terminal.type === "turn.failed") {
- recordError(span, turn.terminal.error);
+ contextFromSpanContext({
+ isRemote: turn.parentIsRemote ?? false,
+ spanId: turn.parentSpanId,
+ traceFlags: turn.context.traceFlags,
+ traceId: turn.context.traceId,
+ }),
+ ),
+ );
+ span.addEvent("turn.started", undefined, turn.startTimeMs);
+ if (turn.terminal !== undefined) {
+ span.addEvent(turn.terminal.type);
+ if (turn.terminal.type === "turn.failed") {
+ recordError(span, turn.terminal.error);
+ }
}
+ span.end();
}
- span.end();
await input.stateStore.deleteTurn(event.sessionId, event.turnId);
}
}
@@ -458,13 +468,26 @@ export function createAgentOtelInstrumentation(
},
prepareSessionTrace,
prepareTurnTrace,
- runInContext(operation, execute) {
+ async runInContext(operation, execute) {
const scope = attemptScopes.get(operation.scope.attemptId) ?? operation.scope;
const contexts = executionContexts.get(scope);
- const parent =
+ let parent =
operation.type === "model.call"
? contexts?.get(operation.idempotencyKey)
: tools.contextFor(operation.scope.attemptId, operation.idempotencyKey);
+ if (parent === undefined) {
+ const turn = await input.stateStore.getTurn(
+ operation.scope.sessionId,
+ operation.scope.turnId,
+ );
+ if (turn !== undefined) {
+ parent = withChannelAudience(
+ contextFromSpanContext(turn.context),
+ operation.scope.channelAudience,
+ );
+ if (!isSampledTrace(turn.context)) parent = suppressTracing(parent);
+ }
+ }
return parent === undefined ? execute() : context.with(parent, execute);
},
};
diff --git a/packages/eve/src/tracing/agent-otel-session-context.ts b/packages/eve/src/tracing/agent-otel-session-context.ts
index 154f0c978..c0f2dbeac 100644
--- a/packages/eve/src/tracing/agent-otel-session-context.ts
+++ b/packages/eve/src/tracing/agent-otel-session-context.ts
@@ -7,6 +7,9 @@ import {
type InstrumentationTurnStartedEvent,
} from "#harness/instrumentation/lifecycle.js";
import type { AgentSpanIdGenerator } from "#tracing/agent-span-id-generator.js";
+import { normalizeChannelAudience } from "#shared/channel-audience.js";
+import type { ChannelAudience } from "#shared/channel-audience.js";
+import type { TraceCapturePolicy } from "#tracing/otel-declaration.js";
import {
SESSION_WINDOW_TURN_LIMIT,
type AgentSessionTraceState,
@@ -18,6 +21,7 @@ interface AgentOtelSessionContextInput {
readonly idGenerator: AgentSpanIdGenerator;
readonly stateStore: AgentTraceStateStore;
readonly tracer: Tracer;
+ readonly tracePolicy?: TraceCapturePolicy;
}
interface AgentOtelSessionContext {
@@ -37,15 +41,25 @@ export function createAgentOtelSessionContext(
): AgentOtelSessionContext {
const openSessionWindow = (window: {
readonly agentName?: string;
+ readonly channelAudience: ChannelAudience;
readonly index: number;
readonly previousTraceId?: string;
readonly rootSessionId: string;
readonly sessionId: string;
}): SpanContext => {
+ if (!shouldTrace(input.tracePolicy, window)) {
+ return {
+ isRemote: false,
+ spanId: input.idGenerator.deriveSpanId(`session:${window.sessionId}:${window.index}`),
+ traceFlags: 0,
+ traceId: input.idGenerator.generateTraceId(),
+ };
+ }
const span = input.tracer.startSpan("agent.session", {
attributes: {
"agent.framework.name": "eve",
"agent.framework.version": input.frameworkVersion,
+ "agent.channel.audience": window.channelAudience,
"agent.name": window.agentName,
"agent.root.session.id": window.rootSessionId,
"agent.session.id": window.sessionId,
@@ -72,16 +86,26 @@ export function createAgentOtelSessionContext(
if (state === undefined) {
state = {
agentName: event.agentName,
+ channelAudience: normalizeChannelAudience(event.channelAudience),
channelKind: event.channelKind,
context:
event.parentTraceContext === undefined
? openSessionWindow({
agentName: event.agentName,
+ channelAudience: normalizeChannelAudience(event.channelAudience),
index: 0,
rootSessionId: event.rootSessionId,
sessionId: event.sessionId,
})
- : adoptedSpanContext(event.parentTraceContext),
+ : adoptedSpanContext(
+ event.parentTraceContext,
+ shouldTrace(input.tracePolicy, {
+ agentName: event.agentName,
+ channelAudience: normalizeChannelAudience(event.channelAudience),
+ rootSessionId: event.rootSessionId,
+ sessionId: event.sessionId,
+ }),
+ ),
rootSessionId: event.rootSessionId,
turnsInWindow: 0,
window: 0,
@@ -101,6 +125,7 @@ export function createAgentOtelSessionContext(
...session,
context: openSessionWindow({
agentName: session.agentName,
+ channelAudience: normalizeChannelAudience(session.channelAudience),
index,
previousTraceId: session.context.traceId,
rootSessionId: session.rootSessionId,
@@ -133,6 +158,7 @@ export function createAgentOtelSessionContext(
event.sessionId,
await ensureSessionContext({
agentName: undefined,
+ channelAudience: "unknown",
channelKind: undefined,
idempotencyKey: sessionIdempotencyKey(event.sessionId),
parentTraceContext: event.parentTraceContext,
@@ -169,6 +195,29 @@ export function createAgentOtelSessionContext(
return { ensureSessionContext, prepareSessionTrace, prepareTurnTrace };
}
+function shouldTrace(
+ policy: TraceCapturePolicy | undefined,
+ trace: {
+ readonly agentName?: string;
+ readonly channelAudience: ChannelAudience;
+ readonly rootSessionId: string;
+ readonly sessionId: string;
+ },
+): boolean {
+ try {
+ return (
+ policy?.({
+ agentName: trace.agentName,
+ audience: trace.channelAudience,
+ rootSessionId: trace.rootSessionId,
+ sessionId: trace.sessionId,
+ }) ?? trace.channelAudience === "public"
+ );
+ } catch {
+ return false;
+ }
+}
+
function portableSpanContext(spanContext: SpanContext): InstrumentationTraceContext {
return {
spanId: spanContext.spanId,
@@ -177,11 +226,11 @@ function portableSpanContext(spanContext: SpanContext): InstrumentationTraceCont
};
}
-function adoptedSpanContext(handed: InstrumentationTraceContext): SpanContext {
+function adoptedSpanContext(handed: InstrumentationTraceContext, sampled = true): SpanContext {
return {
isRemote: "isRemote" in handed && handed.isRemote === true,
spanId: handed.spanId,
- traceFlags: handed.traceFlags,
+ traceFlags: sampled ? handed.traceFlags : 0,
traceId: handed.traceId,
};
}
diff --git a/packages/eve/src/tracing/agent-trace-context-store.ts b/packages/eve/src/tracing/agent-trace-context-store.ts
index 104101347..eba434d30 100644
--- a/packages/eve/src/tracing/agent-trace-context-store.ts
+++ b/packages/eve/src/tracing/agent-trace-context-store.ts
@@ -9,6 +9,7 @@ import type {
AgentTraceStateStore,
AgentTurnTraceState,
} from "#tracing/agent-trace-state.js";
+import { normalizeChannelAudience } from "#shared/channel-audience.js";
interface AgentTraceContextState {
readonly actions: Readonly<Record<string, AgentActionTraceState>>;
@@ -191,6 +192,7 @@ function deserializeState(data: unknown): AgentTraceContextState {
if (!isRecord(value) || !isSpanContext(value.context)) return undefined;
return {
agentName: typeof value.agentName === "string" ? value.agentName : undefined,
+ channelAudience: normalizeChannelAudience(value.channelAudience),
channelKind: typeof value.channelKind === "string" ? value.channelKind : undefined,
context: value.context,
rootSessionId: typeof value.rootSessionId === "string" ? value.rootSessionId : "",
@@ -237,6 +239,7 @@ function deserializeAction(value: unknown): AgentActionTraceState | undefined {
return {
attemptIndex: value.attemptIndex,
callId: value.callId,
+ channelAudience: normalizeChannelAudience(value.channelAudience),
inputAttribute: typeof value.inputAttribute === "string" ? value.inputAttribute : undefined,
kind: value.kind,
name: value.name,
diff --git a/packages/eve/src/tracing/agent-trace-state.ts b/packages/eve/src/tracing/agent-trace-state.ts
index 21c79182d..84f0d32cd 100644
--- a/packages/eve/src/tracing/agent-trace-state.ts
+++ b/packages/eve/src/tracing/agent-trace-state.ts
@@ -7,11 +7,13 @@ import type {
InstrumentationTurnFailedEvent,
InstrumentationTurnSettledEvent,
} from "#harness/instrumentation/lifecycle.js";
+import type { ChannelAudience } from "#shared/channel-audience.js";
/** Sized so an ordinary session stays one trace and only an outsized one rolls. */
export const SESSION_WINDOW_TURN_LIMIT = 200;
export interface AgentSessionTraceState {
+ readonly channelAudience?: ChannelAudience;
readonly agentName?: string;
readonly channelKind?: string;
readonly context: SpanContext;
@@ -36,6 +38,7 @@ export interface AgentTurnTraceState {
export interface AgentActionTraceState {
readonly attemptIndex: number;
readonly callId: string;
+ readonly channelAudience?: ChannelAudience;
readonly inputAttribute?: string;
readonly kind: InstrumentationActionKind;
readonly name: string;
diff --git a/packages/eve/src/tracing/channel-audience-context.ts b/packages/eve/src/tracing/channel-audience-context.ts
new file mode 100644
index 000000000..a8884c3bd
--- /dev/null
+++ b/packages/eve/src/tracing/channel-audience-context.ts
@@ -0,0 +1,16 @@
+import { createContextKey, type Context } from "#compiled/@opentelemetry/api/index.js";
+import { normalizeChannelAudience, type ChannelAudience } from "#shared/channel-audience.js";
+
+const CHANNEL_AUDIENCE_KEY = createContextKey("eve.channel.audience");
+
+export function channelAudienceFromContext(context: unknown): ChannelAudience {
+ if (typeof context !== "object" || context === null) return "unknown";
+ const getValue = Reflect.get(context, "getValue");
+ return typeof getValue === "function"
+ ? normalizeChannelAudience(Reflect.apply(getValue, context, [CHANNEL_AUDIENCE_KEY]))
+ : "unknown";
+}
+
+export function withChannelAudience(context: Context, audience: unknown): Context {
+ return context.setValue(CHANNEL_AUDIENCE_KEY, normalizeChannelAudience(audience));
+}
diff --git a/packages/eve/src/tracing/content-attributes.ts b/packages/eve/src/tracing/content-attributes.ts
index 5e9f33062..bc7b3a866 100644
--- a/packages/eve/src/tracing/content-attributes.ts
+++ b/packages/eve/src/tracing/content-attributes.ts
@@ -16,6 +16,7 @@
/** Prompts, instructions, tool arguments — what went in. */
const INPUT_CONTENT_ATTRIBUTES: ReadonlySet<string> = new Set([
"agent.channel.delivery.input",
+ "agent.approval.request",
"ai.documents",
"ai.prompt",
"ai.prompt.messages",
@@ -37,6 +38,7 @@ const INPUT_CONTENT_ATTRIBUTES: ReadonlySet<string> = new Set([
* `recordOutputs`; matching that is what keeps one destination's view coherent.
*/
const OUTPUT_CONTENT_ATTRIBUTES: ReadonlySet<string> = new Set([
+ "agent.approval.response",
"ai.embedding",
"ai.embeddings",
"ai.ranking",
diff --git a/packages/eve/src/tracing/content-span-processor.test.ts b/packages/eve/src/tracing/content-span-processor.test.ts
index 628e87e70..26dd66535 100644
--- a/packages/eve/src/tracing/content-span-processor.test.ts
+++ b/packages/eve/src/tracing/content-span-processor.test.ts
@@ -7,6 +7,11 @@ import {
import type { SpanProcessor } from "#compiled/@vercel/otel/index.js";
import { contentFilteringProcessor } from "#tracing/content-span-processor.js";
+import {
+ composeSpanExportPolicies,
+ redactSpanInputs,
+ redactSpanOutputs,
+} from "#tracing/span-export-policy.js";
function recordingProcessor(): SpanProcessor & {
readonly ended: unknown[];
@@ -40,9 +45,7 @@ describe("contentFilteringProcessor", () => {
const downstream = recordingProcessor();
const original = span({ "ai.prompt.messages": "what the user said" });
- contentFilteringProcessor(downstream, { recordInputs: true, recordOutputs: true }).onEnd(
- original as never,
- );
+ contentFilteringProcessor(downstream).onEnd(original as never);
expect(downstream.ended).toEqual([original]);
});
@@ -50,7 +53,7 @@ describe("contentFilteringProcessor", () => {
it("forwards a copy without what the destination declined", () => {
const downstream = recordingProcessor();
- contentFilteringProcessor(downstream, { recordInputs: false, recordOutputs: true }).onEnd(
+ contentFilteringProcessor(downstream, redactSpanInputs()).onEnd(
span({
"ai.prompt.messages": "what the user said",
"ai.response.text": "what the model said",
@@ -67,9 +70,10 @@ describe("contentFilteringProcessor", () => {
const declined = recordingProcessor();
const original = span({ "ai.prompt.messages": "what the user said" });
- contentFilteringProcessor(declined, { recordInputs: false, recordOutputs: false }).onEnd(
- original as never,
- );
+ contentFilteringProcessor(
+ declined,
+ composeSpanExportPolicies(redactSpanInputs(), redactSpanOutputs()),
+ ).onEnd(original as never);
kept.onEnd(original as never);
expect((declined.ended[0] as { attributes: unknown }).attributes).toEqual({});
@@ -81,9 +85,10 @@ describe("contentFilteringProcessor", () => {
it("keeps the rest of the span surface reachable on the copy", () => {
const downstream = recordingProcessor();
- contentFilteringProcessor(downstream, { recordInputs: false, recordOutputs: false }).onEnd(
- span({ "ai.prompt.messages": "what the user said" }) as never,
- );
+ contentFilteringProcessor(
+ downstream,
+ composeSpanExportPolicies(redactSpanInputs(), redactSpanOutputs()),
+ ).onEnd(span({ "ai.prompt.messages": "what the user said" }) as never);
expect((downstream.ended[0] as { spanContext: () => unknown }).spanContext()).toEqual({
spanId: "span",
@@ -102,9 +107,7 @@ describe("contentFilteringProcessor", () => {
status: { code: 2, message: "private failure detail" },
};
- contentFilteringProcessor(downstream, { recordInputs: true, recordOutputs: false }).onEnd(
- original as never,
- );
+ contentFilteringProcessor(downstream, redactSpanOutputs()).onEnd(original as never);
const visible = downstream.ended[0] as {
events: unknown[];
@@ -123,7 +126,7 @@ describe("contentFilteringProcessor", () => {
"service.name": "weather",
});
- contentFilteringProcessor(downstream, { recordInputs: false, recordOutputs: true }).onStart(
+ contentFilteringProcessor(downstream, redactSpanInputs()).onStart(
original as never,
undefined as never,
);
@@ -144,10 +147,7 @@ describe("contentFilteringProcessor", () => {
"ai.prompt.messages": "what the user said",
"service.name": "weather",
}) as { attributes: Record<string, unknown> };
- const processor = contentFilteringProcessor(downstream, {
- recordInputs: false,
- recordOutputs: true,
- });
+ const processor = contentFilteringProcessor(downstream, redactSpanInputs());
processor.onStart(original as never, undefined as never);
const retainedAttributes = (downstream.started[0] as { attributes: unknown }).attributes;
@@ -184,10 +184,7 @@ describe("contentFilteringProcessor", () => {
},
};
const downstream = recordingProcessor();
- const processor = contentFilteringProcessor(downstream, {
- recordInputs: false,
- recordOutputs: true,
- });
+ const processor = contentFilteringProcessor(downstream, redactSpanInputs());
processor.onStart(original as never, undefined as never);
@@ -210,10 +207,7 @@ describe("contentFilteringProcessor", () => {
const original = span({ "ai.prompt.messages": "what the user said" }) as {
attributes: Record<string, unknown>;
};
- const processor = contentFilteringProcessor(downstream, {
- recordInputs: false,
- recordOutputs: true,
- });
+ const processor = contentFilteringProcessor(downstream, redactSpanInputs());
processor.onStart(original as never, undefined as never);
Object.freeze(downstream.started[0]);
@@ -227,10 +221,7 @@ describe("contentFilteringProcessor", () => {
it("facades a real OpenTelemetry span across both callbacks", () => {
const downstream = recordingProcessor();
- const filtering = contentFilteringProcessor(downstream, {
- recordInputs: false,
- recordOutputs: true,
- });
+ const filtering = contentFilteringProcessor(downstream, redactSpanInputs());
const provider = new BasicTracerProvider({
spanProcessors: [filtering as OpenTelemetrySpanProcessor],
});
@@ -250,15 +241,92 @@ describe("contentFilteringProcessor", () => {
});
});
+ it.each([
+ ["public", true],
+ ["private", false],
+ ["unknown", false],
+ ] as const)("retains content for the %s audience: %s", (audience, retained) => {
+ const downstream = recordingProcessor();
+ contentFilteringProcessor(
+ downstream,
+ composeSpanExportPolicies(
+ redactSpanInputs(({ audience }) => audience !== "public"),
+ redactSpanOutputs(({ audience }) => audience !== "public"),
+ ),
+ ).onEnd(
+ span({
+ "agent.channel.audience": audience,
+ "ai.prompt.messages": "input",
+ "ai.response.text": "output",
+ }) as never,
+ );
+
+ const expected: Record<string, unknown> = { "agent.channel.audience": audience };
+ if (retained) {
+ expected["ai.prompt.messages"] = "input";
+ expected["ai.response.text"] = "output";
+ }
+ expect((downstream.ended[0] as { attributes: Record<string, unknown> }).attributes).toEqual(
+ expected,
+ );
+ });
+
+ it("fails closed when audience attributes disagree", () => {
+ const downstream = recordingProcessor();
+ contentFilteringProcessor(
+ downstream,
+ composeSpanExportPolicies(
+ redactSpanInputs(({ audience }) => audience !== "public"),
+ redactSpanOutputs(({ audience }) => audience !== "public"),
+ ),
+ ).onEnd(
+ span({
+ "agent.channel.audience": "public",
+ "ai.prompt.messages": "private",
+ "ai.settings.context.eve.channel.audience": "private",
+ }) as never,
+ );
+
+ expect(
+ (downstream.ended[0] as { attributes: Record<string, unknown> }).attributes,
+ ).not.toHaveProperty("ai.prompt.messages");
+ });
+
+ it("can drop an individual span", () => {
+ const downstream = recordingProcessor();
+ contentFilteringProcessor(downstream, { span: ({ name }) => name !== "private-work" }).onEnd({
+ ...(span({}) as object),
+ name: "private-work",
+ } as never);
+
+ expect(downstream.ended).toEqual([]);
+ });
+
+ it("can drop and replace individual attributes", () => {
+ const downstream = recordingProcessor();
+ contentFilteringProcessor(downstream, {
+ attribute: ({ key }) =>
+ key === "secret"
+ ? { action: "drop" }
+ : key === "email"
+ ? { action: "replace", value: "[redacted]" }
+ : { action: "keep" },
+ }).onEnd(span({ email: "[email protected]", secret: "value" }) as never);
+
+ expect((downstream.ended[0] as { attributes: unknown }).attributes).toEqual({
+ email: "[redacted]",
+ });
+ });
+
it("preserves local trace session release through the wrapper", async () => {
const releaseSession = vi.fn(async () => true);
const downstream: SpanProcessor & {
releaseSession(sessionId: string): Promise<boolean>;
} = { ...recordingProcessor(), releaseSession };
- const processor = contentFilteringProcessor(downstream, {
- recordInputs: false,
- recordOutputs: false,
- }) as SpanProcessor & { releaseSession(sessionId: string): Promise<boolean> };
+ const processor = contentFilteringProcessor(
+ downstream,
+ composeSpanExportPolicies(redactSpanInputs(), redactSpanOutputs()),
+ ) as SpanProcessor & { releaseSession(sessionId: string): Promise<boolean> };
await expect(processor.releaseSession("session-1")).resolves.toBe(true);
expect(releaseSession).toHaveBeenCalledExactlyOnceWith("session-1");
diff --git a/packages/eve/src/tracing/content-span-processor.ts b/packages/eve/src/tracing/content-span-processor.ts
index 9465eb844..563162c8c 100644
--- a/packages/eve/src/tracing/content-span-processor.ts
+++ b/packages/eve/src/tracing/content-span-processor.ts
@@ -5,15 +5,24 @@ import {
type ResolvedContentOptions,
} from "#tracing/content-attributes.js";
import { hasSessionRelease, type LocalTracesProcessor } from "#tracing/local-traces.js";
+import { normalizeChannelAudience } from "#shared/channel-audience.js";
+import type { ChannelAudience } from "#shared/channel-audience.js";
+import {
+ contentRedactionForSpan,
+ spanExportPolicyStages,
+ type SpanExportContext,
+ type SpanExportPolicy,
+} from "#tracing/span-export-policy.js";
+import { channelAudienceFromContext } from "#tracing/channel-audience-context.js";
/**
* Puts one destination's content policy in front of it.
*
- * Content is written onto a span if any destination wants it, so the span
- * reaching a destination that declined still carries it. This cannot strip the
- * attribute in place: that span object is shared with every other processor in
- * the pipeline, and editing it would strip the attribute everywhere. So it
- * gives the destination a facade whose attributes omit what it declined.
+ * Accepted traces carry content before they reach destination policies. This
+ * cannot strip an attribute in place: the span object is shared with every
+ * processor in the pipeline, and editing it would strip the attribute
+ * everywhere. So it gives the destination a facade whose attributes omit what
+ * its policy redacted.
*
* One facade follows the original from start through end. This preserves the
* object identity stateful processors key on without ever exposing the original
@@ -24,20 +33,36 @@ import { hasSessionRelease, type LocalTracesProcessor } from "#tracing/local-tra
*/
export function contentFilteringProcessor(
downstream: SpanProcessor,
- content: ResolvedContentOptions,
+ exportPolicy?: SpanExportPolicy,
): SpanProcessor {
- if (content.recordInputs && content.recordOutputs) return downstream;
+ if (exportPolicy === undefined) return downstream;
+ let processor = downstream;
+ for (const policy of spanExportPolicyStages(exportPolicy).toReversed()) {
+ processor = policyFilteringProcessor(processor, policy);
+ }
+ return processor;
+}
+
+function policyFilteringProcessor(
+ downstream: SpanProcessor,
+ exportPolicy: SpanExportPolicy,
+): SpanProcessor {
const facades = new WeakMap<object, SpanFacade>();
+ const dropped = new WeakSet<object>();
const filtering: SpanProcessor = {
forceFlush: () => downstream.forceFlush(),
onEnd: (span) => {
if (typeof span !== "object" || span === null) {
- downstream.onEnd(span);
return;
}
- const scoped = facadeFor(span, content, facades);
+ const scoped = facadeFor(span, exportPolicy, facades);
+ if (dropped.has(span) || !scoped.exported) {
+ dropped.delete(span);
+ facades.delete(span);
+ return;
+ }
scoped.refresh();
try {
downstream.onEnd(scoped.value);
@@ -47,10 +72,19 @@ export function contentFilteringProcessor(
},
onStart: (span, parentContext) => {
if (typeof span !== "object" || span === null) {
- downstream.onStart(span, parentContext);
return;
}
- downstream.onStart(facadeFor(span, content, facades).value, parentContext);
+ const scoped = facadeFor(
+ span,
+ exportPolicy,
+ facades,
+ channelAudienceFromContext(parentContext),
+ );
+ if (!scoped.exported) {
+ dropped.add(span);
+ return;
+ }
+ downstream.onStart(scoped.value, parentContext);
},
shutdown: () => downstream.shutdown(),
};
@@ -64,27 +98,32 @@ export function contentFilteringProcessor(
}
interface SpanFacade {
+ readonly context: SpanExportContext;
+ readonly exported: boolean;
readonly refresh: () => void;
readonly value: object;
}
function facadeFor(
span: object,
- content: ResolvedContentOptions,
+ exportPolicy: SpanExportPolicy,
facades: WeakMap<object, SpanFacade>,
+ inheritedAudience?: ChannelAudience,
): SpanFacade {
const existing = facades.get(span);
if (existing !== undefined) return existing;
+ const context = spanExportContext(span, inheritedAudience);
+ const effectiveContent = contentForSpan(context, exportPolicy);
const attributes: Record<string, unknown> = {};
const events: unknown[] = [];
const status: Record<string, unknown> = {};
const target = Object.create(Reflect.getPrototypeOf(span)) as Record<PropertyKey, unknown>;
const boundMethods = new Map<PropertyKey, unknown>();
const refresh = (): void => {
- refreshAttributes(attributes, span, content);
- refreshEvents(events, span, content);
- refreshStatus(status, span, content);
+ refreshAttributes(attributes, span, effectiveContent, context, exportPolicy);
+ refreshEvents(events, span, effectiveContent);
+ refreshStatus(status, span, effectiveContent);
};
let value: object;
const readOriginal = (property: PropertyKey): unknown => {
@@ -134,6 +173,8 @@ function facadeFor(
: readOriginal(property),
});
const facade = {
+ context,
+ exported: shouldExport(context, exportPolicy),
refresh,
value,
};
@@ -142,10 +183,20 @@ function facadeFor(
return facade;
}
+function contentForSpan(span: SpanExportContext, policy: SpanExportPolicy): ResolvedContentOptions {
+ const redaction = contentRedactionForSpan(policy, span);
+ return {
+ recordInputs: !redaction.redactInputs,
+ recordOutputs: !redaction.redactOutputs,
+ };
+}
+
function refreshAttributes(
destination: Record<string, unknown>,
span: object,
content: ResolvedContentOptions,
+ context: SpanExportContext,
+ policy: SpanExportPolicy | undefined,
): void {
for (const key of Object.keys(destination)) delete destination[key];
@@ -153,7 +204,68 @@ function refreshAttributes(
if (typeof source !== "object" || source === null) return;
const kept = withoutDeclinedContent(source as Record<string, unknown>, content);
- Object.assign(destination, kept ?? source);
+ const visible = kept ?? (source as Record<string, unknown>);
+ for (const [key, value] of Object.entries(visible)) {
+ const decision = attributeDecision(policy, { key, span: context, value });
+ if (decision.action === "keep") destination[key] = value;
+ else if (decision.action === "replace") destination[key] = decision.value;
+ }
+}
+
+function spanExportContext(
+ span: object,
+ inheritedAudience: ChannelAudience = "unknown",
+): SpanExportContext {
+ const attributes = (span as { readonly attributes?: unknown }).attributes;
+ const record =
+ typeof attributes === "object" && attributes !== null
+ ? (attributes as Readonly<Record<string, unknown>>)
+ : {};
+ const candidates = [
+ record["agent.channel.audience"],
+ record["ai.settings.context.eve.channel.audience"],
+ ].filter((value) => value !== undefined);
+ const normalized = candidates.map(normalizeChannelAudience);
+ const audience =
+ normalized.length > 0 && normalized.every((value) => value === normalized[0])
+ ? normalized[0]!
+ : normalized.length > 0
+ ? "unknown"
+ : inheritedAudience;
+ const spanContext = (span as { readonly spanContext?: () => unknown }).spanContext?.();
+ const ids =
+ typeof spanContext === "object" && spanContext !== null
+ ? (spanContext as Readonly<Record<string, unknown>>)
+ : {};
+ const name = (span as { readonly name?: unknown }).name;
+ return {
+ attributes: record,
+ audience,
+ name: typeof name === "string" ? name : "",
+ spanId: typeof ids["spanId"] === "string" ? ids["spanId"] : "",
+ traceId: typeof ids["traceId"] === "string" ? ids["traceId"] : "",
+ };
+}
+
+function shouldExport(context: SpanExportContext, policy: SpanExportPolicy | undefined): boolean {
+ if (policy === undefined) return true;
+ try {
+ return policy.span?.(context) !== false;
+ } catch {
+ return false;
+ }
+}
+
+function attributeDecision(
+ policy: SpanExportPolicy | undefined,
+ input: Parameters<NonNullable<SpanExportPolicy["attribute"]>>[0],
+) {
+ if (policy?.attribute === undefined) return { action: "keep" } as const;
+ try {
+ return policy.attribute(input);
+ } catch {
+ return { action: "drop" } as const;
+ }
}
function refreshEvents(
diff --git a/packages/eve/src/tracing/install-instrumentation-runtime.test.ts b/packages/eve/src/tracing/install-instrumentation-runtime.test.ts
index 84d2edd9b..d56ad362a 100644
--- a/packages/eve/src/tracing/install-instrumentation-runtime.test.ts
+++ b/packages/eve/src/tracing/install-instrumentation-runtime.test.ts
@@ -70,8 +70,9 @@ describe("installInstrumentationRuntime", () => {
expect(forceFlush).toHaveBeenCalledOnce();
expect(providerFlush).toHaveBeenCalledOnce();
expect(runtime.otelSettings).toEqual({
- recordInputs: false,
- recordOutputs: false,
+ functionId: undefined,
+ recordInputs: true,
+ recordOutputs: true,
traceChannelRequests: false,
});
expect(shutdown).toHaveBeenCalledOnce();
diff --git a/packages/eve/src/tracing/install-instrumentation-runtime.ts b/packages/eve/src/tracing/install-instrumentation-runtime.ts
index c3882e7c5..7c78c5e3f 100644
--- a/packages/eve/src/tracing/install-instrumentation-runtime.ts
+++ b/packages/eve/src/tracing/install-instrumentation-runtime.ts
@@ -54,6 +54,7 @@ export function installInstrumentationRuntime(input: {
recordOutputs: input.collected.settings.recordOutputs,
stateStore: new ContextAgentTraceStateStore(),
tracer: trace.getTracer("eve.agent", input.frameworkVersion),
+ tracePolicy: input.collected.settings.tracePolicy,
});
// The span must exist before authored providers observe the lifecycle event.
serialBefore.push({ ...agentOtel.hook, stateNamespace: "internal:otel" });
diff --git a/packages/eve/src/tracing/local-instrumentation-runtime.ts b/packages/eve/src/tracing/local-instrumentation-runtime.ts
index 3695f01dd..905547fb1 100644
--- a/packages/eve/src/tracing/local-instrumentation-runtime.ts
+++ b/packages/eve/src/tracing/local-instrumentation-runtime.ts
@@ -4,7 +4,16 @@ import {
} from "#harness/instrumentation/runtime.js";
import { installInstrumentationRuntime } from "#tracing/install-instrumentation-runtime.js";
import { createLocalTracesProcessor, resolveLocalTracesContent } from "#tracing/local-traces.js";
-import { collectOtelPipeline, otel, otelIntegration } from "#tracing/otel-declaration.js";
+import {
+ collectOtelPipeline,
+ managedOtelIntegration,
+ otel,
+ type TraceCapturePolicy,
+} from "#tracing/otel-declaration.js";
+
+/** Zero-config local tracing keeps unclassified HTTP/TUI sessions observable. @internal */
+export const localTracePolicy: TraceCapturePolicy = ({ audience }) =>
+ audience === "public" || audience === "unknown";
/** Installs the zero-config local OTel runtime once in an `eve dev` worker. */
export function installLocalInstrumentationRuntime(input: {
@@ -18,8 +27,11 @@ export function installLocalInstrumentationRuntime(input: {
const spool = createLocalTracesProcessor({ appRoot: input.appRoot });
return installInstrumentationRuntime({
collected: collectOtelPipeline([
- otel(),
- otelIntegration({ ...resolveLocalTracesContent(), spanProcessors: [spool] }),
+ otel({ tracePolicy: localTracePolicy }),
+ managedOtelIntegration({
+ ...resolveLocalTracesContent(),
+ spanProcessors: [spool],
+ }),
]),
frameworkVersion: input.frameworkVersion,
providers: [],
diff --git a/packages/eve/src/tracing/local-traces.test.ts b/packages/eve/src/tracing/local-traces.test.ts
index ac7e42240..e0bd1e850 100644
--- a/packages/eve/src/tracing/local-traces.test.ts
+++ b/packages/eve/src/tracing/local-traces.test.ts
@@ -1,6 +1,7 @@
import { afterEach, describe, expect, it, vi } from "vitest";
import { createLocalTracesProcessor, resolveLocalTracesContent } from "#tracing/local-traces.js";
+import { localTracePolicy } from "#tracing/local-instrumentation-runtime.js";
import { localTraces } from "#public/instrumentation/otel.js";
vi.mock("#tracing/local-trace-span-processor.js", () => ({
@@ -65,21 +66,21 @@ describe("createLocalTracesProcessor", () => {
});
describe("resolveLocalTracesContent", () => {
- it("records no content by default", () => {
+ it("retains content by default", () => {
expect(resolveLocalTracesContent()).toEqual({
- recordInputs: false,
- recordOutputs: false,
+ recordInputs: true,
+ recordOutputs: true,
});
});
- it("records content when explicitly enabled", () => {
- expect(resolveLocalTracesContent({ recordInputs: true, recordOutputs: true })).toEqual({
- recordInputs: true,
+ it("preserves explicit legacy redaction", () => {
+ expect(resolveLocalTracesContent({ recordInputs: false })).toEqual({
+ recordInputs: false,
recordOutputs: true,
});
});
- it("uses EVE_TRACES_CONTENT=on as the zero-config opt-in", () => {
+ it("keeps EVE_TRACES_CONTENT=on compatible with the new default", () => {
vi.stubEnv("EVE_TRACES_CONTENT", "on");
expect(resolveLocalTracesContent()).toEqual({
@@ -88,7 +89,7 @@ describe("resolveLocalTracesContent", () => {
});
});
- it("lets EVE_TRACES_CONTENT=off override explicit local capture", () => {
+ it("maps EVE_TRACES_CONTENT=off to full local redaction", () => {
vi.stubEnv("EVE_TRACES_CONTENT", "off");
expect(resolveLocalTracesContent({ recordInputs: true, recordOutputs: true })).toEqual({
@@ -97,3 +98,19 @@ describe("resolveLocalTracesContent", () => {
});
});
});
+
+describe("localTracePolicy", () => {
+ it.each([
+ ["public", true],
+ ["unknown", true],
+ ["private", false],
+ ] as const)("accepts the %s audience: %s", (audience, accepted) => {
+ expect(
+ localTracePolicy({
+ audience,
+ rootSessionId: "session-1",
+ sessionId: "session-1",
+ }),
+ ).toBe(accepted);
+ });
+});
diff --git a/packages/eve/src/tracing/local-traces.ts b/packages/eve/src/tracing/local-traces.ts
index 37c51d50f..b9310bb93 100644
--- a/packages/eve/src/tracing/local-traces.ts
+++ b/packages/eve/src/tracing/local-traces.ts
@@ -89,27 +89,19 @@ export function createLocalTracesProcessor(
};
}
-/**
- * The local spool's content policy: its options, intersected with
- * `EVE_TRACES_CONTENT`.
- *
- * The variable applies to this destination only. `on` opts the zero-config
- * spool into content, while `off` overrides authored local options without
- * changing what a hosted backend beside it receives.
- *
- * @internal
- */
+/** Maps legacy local content configuration onto destination redaction. @internal */
export function resolveLocalTracesContent(
options: {
readonly recordInputs?: boolean;
readonly recordOutputs?: boolean;
} = {},
): { readonly recordInputs: boolean; readonly recordOutputs: boolean } {
- const environmentDefault = process.env.EVE_TRACES_CONTENT === "on";
- const enabled = process.env.EVE_TRACES_CONTENT !== "off";
+ if (process.env.EVE_TRACES_CONTENT === "off") {
+ return { recordInputs: false, recordOutputs: false };
+ }
return {
- recordInputs: enabled && (options.recordInputs ?? environmentDefault),
- recordOutputs: enabled && (options.recordOutputs ?? environmentDefault),
+ recordInputs: options.recordInputs !== false,
+ recordOutputs: options.recordOutputs !== false,
};
}
diff --git a/packages/eve/src/tracing/otel-declaration.test.ts b/packages/eve/src/tracing/otel-declaration.test.ts
index 89789075d..57173f035 100644
--- a/packages/eve/src/tracing/otel-declaration.test.ts
+++ b/packages/eve/src/tracing/otel-declaration.test.ts
@@ -6,9 +6,11 @@ import {
collectOtelPipeline,
isOtelDeclaration,
isOtelIntegration,
+ managedOtelIntegration,
otel,
otelIntegration,
} from "#tracing/otel-declaration.js";
+import { composeSpanExportPolicies, redactSpanInputs } from "#tracing/span-export-policy.js";
/** Collection only ever moves processors, so a fresh no-op is identity enough. */
function processor(): SpanProcessor {
@@ -29,6 +31,14 @@ function exporter(): SpanExporter {
};
}
+function testSpan(attributes: Record<string, unknown>): never {
+ return {
+ attributes,
+ name: "agent.step",
+ spanContext: () => ({ spanId: "span", traceId: "trace" }),
+ } as never;
+}
+
describe("otel", () => {
it("declares settings without registering anything", () => {
const declaration = otel({ sampler: "always_on" });
@@ -41,8 +51,6 @@ describe("otelIntegration", () => {
it("passes declared processors through untouched", () => {
const first = processor();
const integration = otelIntegration({
- recordInputs: true,
- recordOutputs: true,
spanProcessors: [first],
});
@@ -53,8 +61,6 @@ describe("otelIntegration", () => {
it("wraps an exporter in a batching processor, after any declared ones", () => {
const first = processor();
const integration = otelIntegration({
- recordInputs: true,
- recordOutputs: true,
spanProcessors: [first],
traceExporter: exporter(),
});
@@ -63,39 +69,94 @@ describe("otelIntegration", () => {
expect(integration.spanProcessors[0]).toBe(first);
});
- it("records no content unless explicitly enabled", () => {
- expect(otelIntegration().content).toStrictEqual({ recordInputs: false, recordOutputs: false });
- });
-
- // An author's own processor is part of this destination, and the point of
- // declining is that nothing under it sees what was said.
- it("puts a declined policy in front of every processor, an author's included", () => {
+ it("maps deprecated capture switches to destination redaction", () => {
const first = processor();
- const integration = otelIntegration({
- recordInputs: true,
- recordOutputs: false,
- spanProcessors: [first],
- });
+ const integration = otelIntegration({ recordInputs: false, spanProcessors: [first] });
- expect(integration.content).toStrictEqual({ recordInputs: true, recordOutputs: false });
+ expect(integration.content).toEqual({ recordInputs: false, recordOutputs: true });
expect(integration.spanProcessors[0]).not.toBe(first);
});
});
describe("agentRunsIntegration", () => {
- it("records no content by default", () => {
+ it("declares the Agent Runs runtime processor", () => {
const integration = agentRunsIntegration();
- expect(integration.content).toStrictEqual({ recordInputs: false, recordOutputs: false });
expect(integration.spanProcessors).toHaveLength(1);
expect(integration.spanProcessors[0]).not.toBe("auto");
});
+});
+
+describe("managed export policy", () => {
+ it("does not redact content unless the export pipeline requests it", () => {
+ let visibleAttributes: Readonly<Record<string, unknown>> | undefined;
+ const integration = managedOtelIntegration({
+ exportPolicy: {
+ span: ({ attributes }) => {
+ visibleAttributes = attributes;
+ return true;
+ },
+ },
+ spanProcessors: [processor()],
+ });
+
+ const spanProcessor = integration.spanProcessors[0];
+ if (spanProcessor === undefined || spanProcessor === "auto") throw new Error("Expected policy");
+ spanProcessor.onEnd(
+ testSpan({
+ "agent.channel.audience": "private",
+ "ai.prompt.messages": "private input",
+ }),
+ );
+
+ expect(visibleAttributes).toHaveProperty("ai.prompt.messages", "private input");
+ });
+
+ it("runs composed export policies in declaration order", () => {
+ let visibleAttributes: Readonly<Record<string, unknown>> | undefined;
+ const integration = managedOtelIntegration({
+ exportPolicy: composeSpanExportPolicies(
+ redactSpanInputs(({ audience }) => audience !== "public"),
+ {
+ span: ({ attributes }) => {
+ visibleAttributes = attributes;
+ return true;
+ },
+ },
+ ),
+ spanProcessors: [processor()],
+ });
+
+ const spanProcessor = integration.spanProcessors[0];
+ if (spanProcessor === undefined || spanProcessor === "auto") throw new Error("Expected policy");
+ spanProcessor.onEnd(
+ testSpan({
+ "agent.channel.audience": "private",
+ "ai.prompt.messages": "private input",
+ }),
+ );
+
+ expect(visibleAttributes).toEqual({ "agent.channel.audience": "private" });
+ });
- it("uses Vercel's automatic processor when all content is enabled", () => {
- const integration = agentRunsIntegration({ recordInputs: true, recordOutputs: true });
+ it("applies deprecated content switches before the configured export policy", () => {
+ let visibleAttributes: Readonly<Record<string, unknown>> | undefined;
+ const integration = managedOtelIntegration({
+ exportPolicy: {
+ span: ({ attributes }) => {
+ visibleAttributes = attributes;
+ return true;
+ },
+ },
+ recordInputs: false,
+ spanProcessors: [processor()],
+ });
+
+ const spanProcessor = integration.spanProcessors[0];
+ if (spanProcessor === undefined || spanProcessor === "auto") throw new Error("Expected policy");
+ spanProcessor.onEnd(testSpan({ "ai.prompt.messages": "private input" }));
- expect(integration.content).toStrictEqual({ recordInputs: true, recordOutputs: true });
- expect(integration.spanProcessors).toStrictEqual(["auto"]);
+ expect(visibleAttributes).toEqual({});
});
});
@@ -109,11 +170,9 @@ describe("collectOtelPipeline", () => {
const [first, second, third] = [processor(), processor(), processor()];
const collected = collectOtelPipeline([
otelIntegration({
- recordInputs: true,
- recordOutputs: true,
spanProcessors: [first, second],
}),
- otelIntegration({ recordInputs: true, recordOutputs: true, spanProcessors: [third] }),
+ otelIntegration({ spanProcessors: [third] }),
otel(),
]);
@@ -127,8 +186,8 @@ describe("collectOtelPipeline", () => {
expect(collected.declared).toBe(true);
expect(collected.settings).toStrictEqual({
functionId: undefined,
- recordInputs: false,
- recordOutputs: false,
+ recordInputs: true,
+ recordOutputs: true,
traceChannelRequests: false,
});
});
@@ -151,32 +210,17 @@ describe("collectOtelPipeline", () => {
});
expect(collected.settings).toStrictEqual({
functionId: "weather",
- // Nothing declared a destination, so nothing asked for content.
+ // Nothing declared a destination, so nothing consumes content.
recordInputs: false,
recordOutputs: false,
traceChannelRequests: true,
});
});
- // Content governs what is written onto the span, which is upstream of every
- // destination — so one that wants it is enough, and the ones that declined
- // drop it on their own way out.
- it("takes content capture as the union across destinations", () => {
- const collected = collectOtelPipeline([
- otelIntegration({ recordInputs: false, recordOutputs: false }),
- otelIntegration({ recordInputs: false, recordOutputs: true }),
- ]);
-
- expect(collected.settings).toMatchObject({ recordInputs: false, recordOutputs: true });
- });
-
- it("writes nothing when every destination declined", () => {
- const collected = collectOtelPipeline([
- otelIntegration({ recordInputs: false, recordOutputs: false }),
- otelIntegration({ recordInputs: false, recordOutputs: false }),
- ]);
+ it("captures complete spans whenever a destination is declared", () => {
+ const collected = collectOtelPipeline([otelIntegration()]);
- expect(collected.settings).toMatchObject({ recordInputs: false, recordOutputs: false });
+ expect(collected.settings).toMatchObject({ recordInputs: true, recordOutputs: true });
});
// A process has one tracer provider, so letting the first declaration win
diff --git a/packages/eve/src/tracing/otel-declaration.ts b/packages/eve/src/tracing/otel-declaration.ts
index b14e557a2..e14ff8b22 100644
--- a/packages/eve/src/tracing/otel-declaration.ts
+++ b/packages/eve/src/tracing/otel-declaration.ts
@@ -13,6 +13,26 @@ import { batchSpanProcessor } from "#tracing/batch-span-processor.js";
import type { ResolvedContentOptions } from "#tracing/content-attributes.js";
import { contentFilteringProcessor } from "#tracing/content-span-processor.js";
import { vercelRuntimeSpanProcessor } from "#tracing/vercel-runtime-span-exporter.js";
+import type { ChannelAudience } from "#shared/channel-audience.js";
+import {
+ composeSpanExportPolicies,
+ redactSpanInputs,
+ redactSpanOutputs,
+ type SpanExportPolicy,
+} from "#tracing/span-export-policy.js";
+
+export type {
+ SpanAttributeDecision,
+ SpanExportAttributeValue,
+ SpanExportContext,
+ SpanExportPolicy,
+ SpanExportPredicate,
+} from "#tracing/span-export-policy.js";
+export {
+ composeSpanExportPolicies,
+ redactSpanInputs,
+ redactSpanOutputs,
+} from "#tracing/span-export-policy.js";
/**
* The process-wide OpenTelemetry settings, declared by `otel()`.
@@ -39,6 +59,11 @@ export interface OtelOptions {
* outgoing HTTP spans. Defaults to `false`.
*/
readonly traceChannelRequests?: boolean;
+ /**
+ * Process-wide head gate for an agent session trace. Defaults to retaining
+ * only public conversations. A thrown error rejects the trace.
+ */
+ readonly tracePolicy?: TraceCapturePolicy;
/**
* Resource attributes merged into eve's own, which already carry the
* service name.
@@ -64,23 +89,31 @@ export interface OtelOptions {
readonly instrumentations?: readonly unknown[];
}
-/**
- * What one destination records of the conversation itself.
- *
- * Declining is per destination, not per process: content is written onto the
- * span if any destination wants it, and one that declined never exports it. So
- * an agent whose every destination declines still never materializes a prompt —
- * the union of nothing is nothing — but a local spool and a hosted backend no
- * longer have to agree.
- */
+export interface ManagedTraceOptions {
+ /** Destination policy applied before spans are exported. */
+ readonly exportPolicy?: SpanExportPolicy;
+ /** @deprecated Use `exportPolicy: redactSpanInputs()` instead. */
+ readonly recordInputs?: boolean;
+ /** @deprecated Use `exportPolicy: redactSpanOutputs()` instead. */
+ readonly recordOutputs?: boolean;
+}
+
+/** @deprecated Compose `redactSpanInputs()` and `redactSpanOutputs()` into an export policy. */
export interface ContentOptions {
- /** Record model prompts and tool call inputs. Defaults to `false`. */
readonly recordInputs?: boolean;
- /** Record model responses and tool call outputs. Defaults to `false`. */
readonly recordOutputs?: boolean;
}
-/** Where one `otelIntegration()` sends spans, and what it records. */
+export interface TraceCaptureContext {
+ readonly agentName?: string;
+ readonly audience: ChannelAudience;
+ readonly rootSessionId: string;
+ readonly sessionId: string;
+}
+
+export type TraceCapturePolicy = (trace: TraceCaptureContext) => boolean;
+
+/** Where one `otelIntegration()` sends spans. */
export interface OtelIntegrationOptions extends ContentOptions {
/** Merged into the pipeline in declaration order. */
readonly spanProcessors?: readonly SpanProcessor[];
@@ -114,7 +147,7 @@ export interface OtelDeclaration extends InstrumentationProvider {
/** One declared destination. A process may have as many as it has files. */
export interface OtelIntegration extends InstrumentationProvider {
readonly [OTEL_INTEGRATION]: true;
- /** Resolved from `ContentOptions`, so the union does not re-apply defaults. */
+ /** @deprecated Content is captured upstream and redacted by destination policies. */
readonly content: ResolvedContentOptions;
readonly runtimeContext?: (input: InstrumentationRuntimeContextInput) => JsonObject | undefined;
readonly spanProcessors: readonly SpanProcessorOrName[];
@@ -138,15 +171,24 @@ export function otel(options: OtelOptions = {}): OtelDeclaration {
* the one-line form of a hosted backend enough. Pass `spanProcessors` instead
* when the destination needs its own batching, sampling, or filtering.
*
- * Declining content wraps every processor here, an author's included: they are
- * this destination, and the point of declining is that nothing under it sees
- * what was said.
+ * The export policy wraps every processor here, an author's included: they are
+ * this destination, and nothing beneath the policy sees what it removes.
*/
export function otelIntegration(options: OtelIntegrationOptions = {}): OtelIntegration {
- const content: ResolvedContentOptions = {
- recordInputs: options.recordInputs === true,
- recordOutputs: options.recordOutputs === true,
- };
+ return createOtelIntegration(options);
+}
+
+/** @internal Local and Agent Runs destination declaration. */
+export function managedOtelIntegration(
+ options: OtelIntegrationOptions & ManagedTraceOptions = {},
+): OtelIntegration {
+ return createOtelIntegration(options, options.exportPolicy);
+}
+
+function createOtelIntegration(
+ options: OtelIntegrationOptions,
+ exportPolicy?: SpanExportPolicy,
+): OtelIntegration {
const declared = options.spanProcessors ?? [];
const spanProcessors =
options.traceExporter === undefined
@@ -156,36 +198,55 @@ export function otelIntegration(options: OtelIntegrationOptions = {}): OtelInteg
return {
[OTEL_INTEGRATION]: true,
[PROVIDER]: true,
- content,
+ content: resolveContentOptions(options),
runtimeContext: options.runtimeContext,
- spanProcessors:
- content.recordInputs && content.recordOutputs
- ? spanProcessors
- : spanProcessors.map((processor) => contentFilteringProcessor(processor, content)),
+ spanProcessors: spanProcessors.map((processor) =>
+ withExportPolicies(processor, legacyContentRedactionPolicy(options), exportPolicy),
+ ),
};
}
/** Vercel Agent Runs through the production request-context transport. @internal */
-export function agentRunsIntegration(options: ContentOptions = {}): OtelIntegration {
- const content = resolveContentOptions(options);
+export function agentRunsIntegration(options: ManagedTraceOptions = {}): OtelIntegration {
return {
[OTEL_INTEGRATION]: true,
[PROVIDER]: true,
- content,
- spanProcessors:
- content.recordInputs && content.recordOutputs
- ? ["auto"]
- : [contentFilteringProcessor(vercelRuntimeSpanProcessor(), content)],
+ content: resolveContentOptions(options),
+ spanProcessors: [
+ withExportPolicies(
+ vercelRuntimeSpanProcessor(),
+ legacyContentRedactionPolicy(options),
+ options.exportPolicy,
+ ),
+ ],
};
}
+function legacyContentRedactionPolicy(options: ContentOptions): SpanExportPolicy | undefined {
+ const policies: SpanExportPolicy[] = [];
+ if (options.recordInputs === false) policies.push(redactSpanInputs());
+ if (options.recordOutputs === false) policies.push(redactSpanOutputs());
+ return policies.length === 0 ? undefined : composeSpanExportPolicies(...policies);
+}
+
export function resolveContentOptions(options: ContentOptions): ResolvedContentOptions {
return {
- recordInputs: options.recordInputs === true,
- recordOutputs: options.recordOutputs === true,
+ recordInputs: options.recordInputs !== false,
+ recordOutputs: options.recordOutputs !== false,
};
}
+function withExportPolicies(
+ downstream: SpanProcessor,
+ ...policies: readonly (SpanExportPolicy | undefined)[]
+): SpanProcessor {
+ let processor = downstream;
+ for (const policy of policies.toReversed()) {
+ processor = contentFilteringProcessor(processor, policy);
+ }
+ return processor;
+}
+
export function isOtelDeclaration(value: unknown): value is OtelDeclaration {
return (
typeof value === "object" &&
@@ -215,11 +276,8 @@ export interface OtelPipeline {
export interface OtelHarnessSettings {
readonly functionId?: string;
readonly traceChannelRequests: boolean;
- /**
- * What to write onto a span at all, as opposed to what any one destination
- * exports. `agent/instrumentation.ts` sets this directly; a provider
- * directory arrives at it as the union of its destinations.
- */
+ readonly tracePolicy?: TraceCapturePolicy;
+ /** Legacy `defineInstrumentation()` capture settings. Provider destinations capture fully. */
readonly recordInputs?: boolean;
readonly recordOutputs?: boolean;
}
@@ -249,10 +307,6 @@ export interface CollectedOtel {
* happened to visit first. With one declaration per file that collision needs
* two files both exporting `otel()`, which is the only way to reach it.
*
- * Content capture is the union of what the destinations asked for, because it
- * governs what is written rather than what is exported. Each destination's own
- * processors already drop what it declined.
- *
* @internal
*/
export function collectOtelPipeline(values: readonly unknown[]): CollectedOtel {
@@ -260,14 +314,12 @@ export function collectOtelPipeline(values: readonly unknown[]): CollectedOtel {
const runtimeContextResolvers: RuntimeContextResolver[] = [];
let declaration: OtelDeclaration | undefined;
let declared = false;
- let recordInputs = false;
- let recordOutputs = false;
+ let capturesContent = false;
for (const value of values) {
if (isOtelIntegration(value)) {
declared = true;
- recordInputs ||= value.content.recordInputs;
- recordOutputs ||= value.content.recordOutputs;
+ capturesContent = true;
spanProcessors.push(...value.spanProcessors);
if (value.runtimeContext !== undefined) {
runtimeContextResolvers.push(value.runtimeContext);
@@ -285,6 +337,15 @@ export function collectOtelPipeline(values: readonly unknown[]): CollectedOtel {
}
const options = declaration?.options ?? {};
+ const settings: OtelHarnessSettings = {
+ functionId: options.functionId,
+ recordInputs: capturesContent,
+ recordOutputs: capturesContent,
+ traceChannelRequests: options.traceChannelRequests === true,
+ };
+ if (options.tracePolicy !== undefined) {
+ Object.assign(settings, { tracePolicy: options.tracePolicy });
+ }
return {
declared,
pipeline: {
@@ -295,11 +356,6 @@ export function collectOtelPipeline(values: readonly unknown[]): CollectedOtel {
spanProcessors,
},
runtimeContextResolvers,
- settings: {
- functionId: options.functionId,
- recordInputs,
- recordOutputs,
- traceChannelRequests: options.traceChannelRequests === true,
- },
+ settings,
};
}
diff --git a/packages/eve/src/tracing/sampled-trace.ts b/packages/eve/src/tracing/sampled-trace.ts
new file mode 100644
index 000000000..ccebfd272
--- /dev/null
+++ b/packages/eve/src/tracing/sampled-trace.ts
@@ -0,0 +1,5 @@
+import { TraceFlags, type SpanContext } from "#compiled/@opentelemetry/api/index.js";
+
+export function isSampledTrace(context: Pick<SpanContext, "traceFlags">): boolean {
+ return (context.traceFlags & TraceFlags.SAMPLED) === TraceFlags.SAMPLED;
+}
diff --git a/packages/eve/src/tracing/span-export-policy.ts b/packages/eve/src/tracing/span-export-policy.ts
new file mode 100644
index 000000000..116008179
--- /dev/null
+++ b/packages/eve/src/tracing/span-export-policy.ts
@@ -0,0 +1,94 @@
+import type { ChannelAudience } from "#shared/channel-audience.js";
+
+export interface SpanExportContext {
+ readonly attributes: Readonly<Record<string, unknown>>;
+ readonly audience: ChannelAudience;
+ readonly name: string;
+ readonly spanId: string;
+ readonly traceId: string;
+}
+
+export type SpanExportPredicate = (span: SpanExportContext) => boolean;
+
+export type SpanExportAttributeValue =
+ | string
+ | number
+ | boolean
+ | readonly string[]
+ | readonly number[]
+ | readonly boolean[];
+
+export type SpanAttributeDecision =
+ | { readonly action: "keep" }
+ | { readonly action: "drop" }
+ | { readonly action: "replace"; readonly value: SpanExportAttributeValue };
+
+export interface SpanExportPolicy {
+ /** Return false to block one span without blocking its trace. */
+ readonly span?: SpanExportPredicate;
+ /** Drop or replace individual span attributes after content filtering. */
+ readonly attribute?: (input: {
+ readonly key: string;
+ readonly span: SpanExportContext;
+ readonly value: unknown;
+ }) => SpanAttributeDecision;
+}
+
+interface ContentRedaction {
+ readonly inputs: readonly SpanExportPredicate[];
+ readonly outputs: readonly SpanExportPredicate[];
+}
+
+const contentRedactions = new WeakMap<SpanExportPolicy, ContentRedaction>();
+const composedPolicies = new WeakMap<SpanExportPolicy, readonly SpanExportPolicy[]>();
+
+/** Redact input content from every matching span. */
+export function redactSpanInputs(when: SpanExportPredicate = () => true): SpanExportPolicy {
+ const policy = {};
+ contentRedactions.set(policy, { inputs: [when], outputs: [] });
+ return policy;
+}
+
+/** Redact output content, exception details, and status messages from every matching span. */
+export function redactSpanOutputs(when: SpanExportPredicate = () => true): SpanExportPolicy {
+ const policy = {};
+ contentRedactions.set(policy, { inputs: [], outputs: [when] });
+ return policy;
+}
+
+/** Compose policies in declaration order. A drop or redaction from any policy is final. */
+export function composeSpanExportPolicies(
+ ...policies: readonly SpanExportPolicy[]
+): SpanExportPolicy {
+ if (policies.length === 0) return {};
+ if (policies.length === 1) return policies[0]!;
+ const composed = {};
+ composedPolicies.set(composed, policies.flatMap(spanExportPolicyStages));
+ return composed;
+}
+
+/** @internal */
+export function spanExportPolicyStages(policy: SpanExportPolicy): readonly SpanExportPolicy[] {
+ return composedPolicies.get(policy) ?? [policy];
+}
+
+/** @internal */
+export function contentRedactionForSpan(
+ policy: SpanExportPolicy | undefined,
+ span: SpanExportContext,
+): { readonly redactInputs: boolean; readonly redactOutputs: boolean } {
+ const redaction = policy === undefined ? undefined : contentRedactions.get(policy);
+ return {
+ redactInputs: redaction?.inputs.some((when) => matches(when, span)) ?? false,
+ redactOutputs: redaction?.outputs.some((when) => matches(when, span)) ?? false,
+ };
+}
+
+function matches(predicate: SpanExportPredicate, span: SpanExportContext): boolean {
+ try {
+ return predicate(span);
+ } catch {
+ // Redaction predicates fail closed.
+ return true;
+ }
+}
diff --git a/packages/eve/src/tracing/suppress-tracing.ts b/packages/eve/src/tracing/suppress-tracing.ts
new file mode 100644
index 000000000..b21a13abb
--- /dev/null
+++ b/packages/eve/src/tracing/suppress-tracing.ts
@@ -0,0 +1,8 @@
+import { createContextKey, type Context } from "#compiled/@opentelemetry/api/index.js";
+
+// Standard OpenTelemetry SDK suppression key, kept behind an eve-owned wrapper.
+const SUPPRESS_TRACING_KEY = createContextKey("OpenTelemetry SDK Context Key SUPPRESS_TRACING");
+
+export function suppressTracing(context: Context): Context {
+ return context.setValue(SUPPRESS_TRACING_KEY, true);
+}