Observability

eve configures its built-in OpenTelemetry destinations automatically. eve dev records local traces, while preview and production deployments export to Agent Runs by default. Use this page to configure process-wide tracing, third-party destinations, and export policies.

OpenTelemetry configuration uses separate helpers for process-wide settings, built-in destinations, and third-party destinations:

• Use otel() for process-wide settings such as the resource, sampler, propagators, or trace capture policy. Declare it at most once.
• Use localTraces() to customize local tracing.
• Use agentRuns() to customize the built-in Agent Runs integration.
• Use otelIntegration() only to add a third-party OpenTelemetry destination. Declare one file per exporter or processor chain.

Add agent/instrumentation/otel.ts when you need process-wide OpenTelemetry settings or want to control the content eve writes to every destination:

import { otel } from 'eve/instrumentation/otel';
 
export default otel({
  resource: {
    'deployment.environment': process.env.VERCEL_ENV ?? 'development',
  },
  tracePolicy: ({ audience, environment }) => ({
    emit: true,
    recordInputs: audience === 'public' || environment === 'development',
    recordOutputs: audience === 'public' || environment === 'development',
  }),
});

The tracePolicy is a capture ceiling shared by every OpenTelemetry destination. A destination cannot restore content excluded by this policy. The policy does not affect lifecycle instrumentation created with defineInstrumentation().

To configure content for the built-in Edgenivo integration, see Configure Agent Runs trace content.

Install @vercel/otel before using its exporters:

pnpm add @vercel/otel

Create an integration file for the destination:

import { OTLPHttpProtoTraceExporter } from '@vercel/otel';
import { otelIntegration } from 'eve/instrumentation/otel';
 
export default otelIntegration({
  exportPolicy: {
    span: () => ({ redact: true, inputs: true, outputs: true }),
  },
  traceExporter: new OTLPHttpProtoTraceExporter({
    url: 'https://api.honeycomb.io/v1/traces',
    headers: {
      'x-honeycomb-team': process.env.HONEYCOMB_API_KEY!,
    },
  }),
});

Any OpenTelemetry-compatible backend can receive eve traces. Pass spanProcessors to otelIntegration() when a destination needs additional filtering or transformation. The example's exportPolicy preserves span metadata while removing inputs and outputs from this destination.

For a third-party destination, use runtimeContext to add JSON values to AI SDK spans for each model attempt. For typed channel metadata, import the channel definition and narrow with isChannel:

import { isChannel } from 'eve/instrumentation';
import { otelIntegration } from 'eve/instrumentation/otel';
 
import supportChannel from '../channels/support';
 
export default otelIntegration({
  runtimeContext(input) {
    if (!isChannel(input.channel, supportChannel)) return undefined;
 
    return {
      'support.channel_id': input.channel.metadata.channelId ?? '',
      'support.user_id': input.channel.metadata.triggeringUserId ?? '',
    };
  },
});

The resolver receives the channel, session, final model input, step, and turn. Keys beginning with eve. are reserved. Content excluded by otel({ tracePolicy }) is not available to the resolver.

Third-party destinations created with otelIntegration() and built-in destinations configured with localTraces() or agentRuns() accept one exportPolicy object or an array applied in order. Each policy filters spans and attributes before that destination's processors receive them.

Return { emit: true } to retain a span or attribute, and { emit: false } to omit it from this destination. For attributes, return { replace: true, value } to replace the value. To retain a span while redacting content, return { redact: true } with inputs: true, outputs: true, or both. Policies run in array order, and each policy receives the result of the policies before it.

For an Agent Runs filtering example, see Configure Agent Runs trace content.

OpenTelemetry destinations receive the following trace topology for an ordinary agent turn:

invoke_agent <agent>
  +-- agent.step
        +-- chat <model>
        +-- agent.action
              +-- execute_tool <tool>

Each turn starts a new trace. The first subagent trace links to its caller with eve.link.type=agent.dispatch; the link is not an authorization grant. Use gen_ai.conversation.id to find traces for one conversation in your destination's span-search surface.

Instrumentation has two environment-specific defaults:

• Local traces: eve dev records local traces by default. Omitting agent/instrumentation/local.ts preserves the default. Export localTraces(...) from that file to reconfigure it, or export disableInstrumentation() to disable it.
• Edgenivo Agent Runs: Preview and production deployments export to Agent Runs by default. Omitting agent/instrumentation/agent-runs.ts preserves the default. Export agentRuns(...) from that file to reconfigure it, or export disableInstrumentation() to disable it.

• Concepts: learn how eve's runtime pieces fit together.
• Agent Runs: inspect agent sessions and configure the built-in Edgenivo integration.
• Edgenivo Observability: inspect traces alongside logs and metrics.
• OpenTelemetry on eve: review the full eve instrumentation reference.