Eve

The @raindrop-ai/eve package instruments Vercel’s Eve agent framework using its native instrumentation entry point: agent/instrumentation/raindrop.ts on Eve >= 0.62, agent/instrumentation.ts on older Eve. No wrapping, no per-call setup — Eve auto-discovers the integration at server startup and every agent turn flows to Raindrop. What gets tracked:

Every agent turn as a single Raindrop event, grouped by the Eve session, with the user’s message as its input
Multi-step streamText / generateText / generateObject calls with full attribute capture
Eve’s own agent spans (agent run, steps, model calls, tool executions), filed under the same event on Eve >= 0.62
Tool calls (inputs, outputs, durations, errors)
Token usage per step and per turn
Sub-agents nested inside the turn that dispatched them, even across Eve’s V8 sandbox boundary
Model name, finish reason, errors, and full AI SDK telemetry attributes
Automatic mirroring to the local Workshop daemon during development

Installation

pnpm add @raindrop-ai/eve @vercel/otel @opentelemetry/api @opentelemetry/sdk-trace-base

eve is expected to already be in your agent project. The integration declares eve: "*" as an optional peer dependency and is verified against Eve 1.0.0-rc.6 and 0.91.0; a single defineRaindropInstrumentation() call works on both layouts without any per-version configuration.

Eve >= 0.62 discovers one instrumentation provider per file under agent/instrumentation/ and owns the process-wide OpenTelemetry pipeline. The object returned by defineRaindropInstrumentation() is an Eve otelIntegration() destination (Raindrop exporter + span processors + runtimeContext resolver). Do not pass registerOTel: Eve refuses to start when another runtime owns the global tracer provider.
Eve <= 0.61 reads the legacy agent/instrumentation.ts default export. Pass registerOTel from @vercel/otel so Eve’s own spans are exported.
Cross-sandbox sub-agent linkage is sourced from the session.parent lineage Eve forwards on every dispatch (via otelIntegration({ runtimeContext }) on >= 0.62, events["step.started"] before).
Per-turn dynamic metadata is authored once via the events["step.started"] option (see Identifying Users) and forwarded to Eve on both layouts; it runs once per model call.

Quick Start

Drop a single file into your Eve project. On Eve >= 0.62:

// agent/instrumentation/raindrop.ts
import { otelIntegration } from "eve/instrumentation/otel";
import { defineRaindropInstrumentation } from "@raindrop-ai/eve";

export default defineRaindropInstrumentation({
  otelIntegration,
  writeKey: process.env.RAINDROP_WRITE_KEY,
});

Passing otelIntegration explicitly is required for bundled deploys: eve build output runs without node_modules, where the runtime fallback lookup cannot resolve eve/instrumentation/otel. Keep the export default un-annotated. The declared return type does not carry Eve’s provider/integration symbol markers, so annotating it as Eve’s InstrumentationProvider fails to type-check even though the object is one. Process-wide OpenTelemetry settings (functionId, tracePolicy, sampler, propagators) live in Eve’s own otel() declaration, one per project, next to the Raindrop file:

// agent/instrumentation/otel.ts (optional)
import { otel } from "eve/instrumentation/otel";

export default otel({ functionId: "support-agent" });

On Eve <= 0.61:

// agent/instrumentation.ts
import { registerOTel } from "@vercel/otel";
import { defineRaindropInstrumentation } from "@raindrop-ai/eve";

export default defineRaindropInstrumentation({
  registerOTel,
  writeKey: process.env.RAINDROP_WRITE_KEY,
});

That’s it. Eve runs the file at server startup before any agent code. Every turn from every session in your agent will land in Raindrop.

Upgrading an agent from Eve <= 0.61 to >= 0.62: move the file to agent/instrumentation/raindrop.ts, replace registerOTel with otelIntegration from eve/instrumentation/otel, and move functionId into otel({ functionId }) if you set it. See Configuration for content capture and redaction behavior.

How It Works

The package does two things:

Implements a SpanExporter (RaindropEveSpanExporter) that serializes OTel spans to OTLP/HTTP JSON and ships them to https://api.raindrop.ai/v1/traces. On Eve >= 0.62 Eve wires it into its own OpenTelemetry pipeline as an otelIntegration() destination; on older Eve the integration registers it through registerOTel. On Eve >= 0.62 it also files Eve’s agent spans under the turn’s Raindrop event (see Captured Trace Hierarchy). It mirrors every export to a local Workshop daemon when one is reachable (http://localhost:5899/), so the same agent run shows up in raindrop workshop AND hosted Raindrop without changing code.
Registers a Raindrop TelemetryIntegration with Vercel AI SDK v7’s global registry so every streamText / generateText / tool call in your agent becomes a proper Raindrop LLM / tool span — and a track_partial semantic event — instead of opaque AI SDK spans. This is what hydrates the Workshop Overview tab and the hosted Raindrop event feed. All AI SDK calls within one Eve turn are grouped under a single eventId built from Eve’s session and turn ids (eve:<sessionId>:<turnId>), so a single agent turn shows up as a single Raindrop event in both UIs. The event’s input is the user’s message, not the task or state messages Eve adds to the model’s history.

For users who’d rather wire OpenTelemetry themselves, RaindropEveSpanExporter is exported separately for use as the traceExporter of an Eve otelIntegration() destination or any registerOTel({ traceExporter }) call (see Application Git identity).

Sub-Agents

Eve runs each sub-agent in its own V8 sandbox. The integration reads the session.parent lineage Eve forwards on dispatch (the otelIntegration({ runtimeContext }) input on Eve >= 0.62, the events["step.started"] input before that), and records the sub-agent inside the parent turn that dispatched it:

Eve >= 0.62: Eve records the sub-agent as an invoke_agent span nested under the parent’s tool call, with the sub-agent’s own steps, model calls and tool executions. The integration files that run under the parent turn’s Raindrop event, so the sub-agent appears inside the parent’s conversation as one sub-agent, with its own steps and tool calls. The integration does not ship a separate AI SDK copy of a sub-agent’s calls; its content follows recordInputs / recordOutputs like every other Eve span.
Eve <= 0.61: the sub-agent’s AI SDK calls are wrapped in a synthetic agent.subagent tool call and reported under the parent turn’s event.

The lineage is attached to the sub-agent’s spans:

Attribute	Description
`raindrop.agent.role`	`"subagent"` when the current sandbox is a sub-agent dispatched by another agent; `"root"` otherwise.
`raindrop.subagent.name`	The sub-agent’s `agentName` (e.g. `weatherResearcher`).
`raindrop.parent.sessionId`	The parent agent’s (bare) Eve session id.
`raindrop.parent.eventId`	The dispatching parent turn’s Raindrop event id (`eve:<sessionId>:<turnId>`).
`raindrop.parent.turnId`	The parent’s turn id that dispatched this sub-agent.
`raindrop.parent.turnSequence`	The parent’s turn sequence number.

When Eve exposes no session.parent (a root session), spans carry raindrop.agent.role = "root".

Configuration

defineRaindropInstrumentation({
  registerOTel,                                // Eve <= 0.61 only, from @vercel/otel
  writeKey: process.env.RAINDROP_WRITE_KEY,
  endpoint: "https://api.raindrop.ai/v1/",   // optional, default
  projectId: "support-prod",                   // optional, route events to a specific project (slug)
  localWorkshopUrl: undefined,                 // optional, see below
  serviceName: "support-agent",                // optional, defaults to the Eve agent name
  eventName: "support_turn",                   // optional, the Raindrop event name for each turn
  staticMetadata: { team: "support", tier: "prod" }, // optional, static, attached to every event
  events: {                                    // optional, per-step callback
    "step.started"(input) {
      return {
        runtimeContext: {
          "raindrop.userId": String(input.session.id),
        },
      };
    },
  },
  recordInputs: false,                         // default: redact inputs on Eve's OTel destination (>= 0.62); forwarded to Eve on <= 0.61
  recordOutputs: false,                        // default: redact outputs on Eve's OTel destination, likewise
  includeStreamFlushSpans: false,              // default: drop per-chunk workflow.stream.flush spans
  debug: false,                                // optional, or set RAINDROP_AI_DEBUG=1
});

On Eve >= 0.62, omitted recordInputs / recordOutputs declare a redacting exportPolicy for Eve’s OTel spans sent to this destination (Raindrop and Workshop). Setting a flag to true removes that direction’s redaction; Eve’s tracePolicy still controls what content is captured. On Eve <= 0.61, the flags are forwarded to Eve’s telemetry settings. These options are not a content-redaction guarantee for the separate Raindrop AI SDK shippers: their traces follow the AI SDK call’s telemetry settings, and event input/output text is not gated by these flags. On Eve >= 0.62 a sub-agent’s prompts and replies are recorded only on Eve’s spans, so these flags decide whether that content reaches Raindrop. Other OTel destinations follow their own policies. Per-chunk spans named exactly workflow.stream.flush are dropped from Raindrop and Workshop by default (includeStreamFlushSpans: false). Set includeStreamFlushSpans: true to retain them; other workflow and step spans are unchanged. Two ways to attach metadata:

Field	When it runs	Use it for
`staticMetadata`	Set once at startup	Values that are the same on every event — `team`, `tier`, environment, or a fixed `raindrop.userId`.
`events["step.started"]`	Eve callback, runs once per model call	Values that change per turn — e.g. the user who triggered this request. Returns `{ runtimeContext }`.

Both feed the same event fields — the events callback just lets you compute them per turn.

Projects

If your org has multiple projects, route this agent’s events to a specific one by passing its slug as projectId (or via RAINDROP_PROJECT_ID):

defineRaindropInstrumentation({
  writeKey: process.env.RAINDROP_WRITE_KEY,
  projectId: "support-prod",
});

This sets the X-Raindrop-Project-Id header on every cloud export. Omit it (or pass "default") to use your org’s default Production project, which is the existing behavior. Single-project orgs need nothing new.

Eve is one instrumentation per process by design — run one project per process. defineRaindropInstrumentation() installs its OpenTelemetry exporter behind a process-global symbol gate (the first call wins) and registers its AI SDK telemetry integration on globalThis (the last call wins). Two defineRaindropInstrumentation() calls with different writeKeys or projectIds in the same process therefore split-brain — the exporter belongs to the first call, the AI SDK capture to the last — and spans land in the wrong project. To report several agents to different projects, run one instrumented Eve process per project rather than calling defineRaindropInstrumentation() more than once.

Identifying Users

Raindrop sets each event’s user and conversation from two reserved keys: raindrop.userId and raindrop.convoId. Put them on staticMetadata if they never change, or return them from the events["step.started"] callback to compute them per turn. Same user every time — put the keys on staticMetadata:

defineRaindropInstrumentation({
  writeKey: process.env.RAINDROP_WRITE_KEY,
  staticMetadata: {
    "raindrop.userId": "user_123",
    "raindrop.convoId": "convo_456",
    team: "support",
  },
});

Different user per turn — return the keys from the events["step.started"] callback. Eve runs it once per model call with the live input, so you can derive identity from the request that triggered the turn — e.g. map the Slack user onto the Raindrop event userId:

defineRaindropInstrumentation({
  writeKey: process.env.RAINDROP_WRITE_KEY,
  staticMetadata: { app: "support-agent", team: "support" },
  events: {
    "step.started"(input) {
      const m = input.channel.metadata;
      return {
        runtimeContext: {
          // reserved keys -> Raindrop event identity
          "raindrop.userId": m.triggeringUserId, // becomes the event userId
          "raindrop.convoId": m.threadTs,        // becomes the event convoId
          // any other key -> Raindrop event properties
          "slack.user_id": m.triggeringUserId,
          "slack.channel_id": m.channelId,
          "slack.team_id": m.teamId,
          "slack.thread_ts": m.threadTs,
        },
      };
    },
  },
});

How the keys map onto the event:

raindrop.userId → the event’s userId; raindrop.convoId → the event’s convoId.
Every other key → the event’s properties, except keys starting with raindrop. or eve., which are reserved for the integration and are not copied onto the event.

The same values are also attached to the AI SDK spans (as ai.settings.context.*).

When the same key is set in more than one place, the most specific value wins: per-call AI SDK metadata > the events["step.started"] callback > staticMetadata. If no raindrop.userId is set anywhere, Raindrop falls back to the Eve session.id.

Using the Slack user’s name / email / channel name

Whatever string you return as raindrop.userId becomes the event’s userId — so to make Raindrop track e.g. the Slack email instead of the user id, just return that string. What’s reachable from step.started:

User id (Uxxxx) — directly on input.channel.metadata.triggeringUserId.
User’s name — already resolved, no API call: read input.session.auth.current?.attributes and use full_name / user_name (Eve’s default Slack auth puts them there).
Email / channel name — not in any Slack mention payload, so resolve them once on the async inbound side (onAppMention) via the Slack Web API (users.info → user.profile.email, needs the users:read.email scope; conversations.info → channel.name), stash them on the session auth attributes, then read them back in step.started (which is synchronous and can’t call Slack itself):

// agent/channels/slack.ts — runs on the inbound webhook (async ok)
export default slackChannel({
  async onAppMention(ctx, message) {
    const auth = defaultSlackAuth(message, ctx);
    const who = await ctx.slack.request("users.info", { user: message.author.userId });
    return auth && {
      auth: { ...auth, attributes: { ...auth.attributes, email: who?.user?.profile?.email ?? "" } },
    };
  },
});

// agent/instrumentation/raindrop.ts: step.started is synchronous, just reads what you stashed
"step.started"(input) {
  const a = input.session.auth.current?.attributes ?? {};
  return { runtimeContext: { "raindrop.userId": String(a.email || a.user_id || "") } }; // userId will be the email
},

Workshop / Production Mirroring

localWorkshopUrl controls Workshop mirroring:

Value	Behavior
`string`	Force-enable; mirror every export to that URL.
`false`	Opt out entirely (skip env vars and auto-detect).
`null`	Same as `false`.
`undefined` (default)	Honor `RAINDROP_WORKSHOP` / `RAINDROP_LOCAL_DEBUGGER`, then auto-detect localhost during development.

Run raindrop workshop locally to get a daemon at http://localhost:5899 — the integration starts mirroring as soon as the daemon is reachable.

Production-Only Mode

defineRaindropInstrumentation({
  writeKey: process.env.RAINDROP_WRITE_KEY,
  localWorkshopUrl: false,
});

Workshop-Only Mode (no Raindrop account)

Leave writeKey undefined. Spans still flow to Workshop:

defineRaindropInstrumentation({
  localWorkshopUrl: "http://localhost:5899/v1/",
});

Captured Trace Hierarchy

Eve >= 0.62 owns the agent spans and emits OpenTelemetry GenAI semantic-convention attributes (gen_ai.*). A turn that dispatches a sub-agent looks like:

invoke_agent <agent>
  agent.step
    chat <model>                              // model call
    execute_tool <tool>                       // tool exec
    execute_tool <sub-agent>                  // dispatch
      invoke_agent <sub-agent>                // the sub-agent's run
        agent.step
          chat <model>
          execute_tool <tool>

The integration files these agent spans (invoke_agent, agent.step, chat, execute_tool) under the turn’s Raindrop event by setting ai.telemetry.metadata.raindrop.eventId, so they land on the same event as the AI SDK spans and the event itself. Eve’s internal workflow spans are exported as before but are not attached to the event. Older Eve relies on the AI SDK’s spans:

ai.eve.turn                                   // session / turn metadata
  ai.streamText                               // step
    ai.streamText.doStream                    // model call
    ai.toolCall  { toolName: get_weather }    // tool exec
  ai.streamText

On every Eve version the AI SDK telemetry integration this package registers also ships each root-agent model / tool call as a Raindrop event (track_partial).

Captured Event Fields

Each turn’s Raindrop event carries:

Field	Source
`eventId`	`eve:<sessionId>:<turnId>` for the turn.
`userId`	`raindrop.userId` from `events["step.started"]` or `staticMetadata`; otherwise the Eve `session.id`.
`convoId`	`raindrop.convoId` if set; otherwise the Eve session (sub-agents share their root session’s conversation).
`eventName`	The `eventName` option; otherwise the AI SDK operation name.
`input` / `output`	The user’s message for the turn and the agent’s reply.
`properties`	Your `staticMetadata` and `events["step.started"]` keys, except reserved `raindrop.` / `eve.` keys.

Model, token usage and cost come from the turn’s model-call spans. Sub-agent lineage (raindrop.agent.role, raindrop.parent.*) is recorded on spans, not as event properties.

Flush & Shutdown

Eve’s BatchSpanProcessor flushes spans automatically at process exit, and the integration registers a shutdown() hook that drains the internal Raindrop client buffer before the process exits. Most users don’t need to call anything manually. If you’re embedding RaindropEveSpanExporter directly, call await exporter.shutdown() before exit.

Known Limitations

Streaming: The integration captures aggregate token usage and the final outputs of each step. Individual token-by-token deltas are not traced separately.
functionId on Eve >= 0.62: the functionId option only affects the integration’s own sub-agent detection; Eve reads the span functionId from otel({ functionId }).
OTel provider access (Eve <= 0.61): The integration calls addSpanProcessor on the NodeTracerProvider returned by @vercel/otel. Custom OTel setups that hide the underlying provider behind a non-standard proxy will gracefully skip the ai.eve.turn session-id enrichment path and fall back to the events["step.started"] session input only.

Application Git identity

Set appGit on defineRaindropInstrumentation (or RaindropEveSpanExporter) to provide commitSha, commitDirty, and optional branch, or pass false to opt out. Local Git is not read unless sourceDirectory explicitly identifies the AUT; both Eve telemetry feeds use that same identity. See the TypeScript Git reference. defineRaindropInstrumentation installs span-start capture automatically. If you wire RaindropEveSpanExporter directly, add its public start processor to freeze automatic Git metadata. On Eve >= 0.62 declare it as a destination in agent/instrumentation/raindrop.ts:

import { otelIntegration } from "eve/instrumentation/otel";
import { RaindropEveSpanExporter, createEveAppGitSpanProcessor } from "@raindrop-ai/eve";

const exporter = new RaindropEveSpanExporter({
  writeKey: process.env.RAINDROP_WRITE_KEY,
  appGit: { sourceDirectory: "/path/to/application" },
});

export default otelIntegration({
  traceExporter: exporter,
  spanProcessors: [createEveAppGitSpanProcessor(exporter)],
});

On older Eve, keep "auto" to preserve Vercel’s default processors:

import { registerOTel } from "@vercel/otel";
import { RaindropEveSpanExporter, createEveAppGitSpanProcessor } from "@raindrop-ai/eve";

const exporter = new RaindropEveSpanExporter({
  writeKey: process.env.RAINDROP_WRITE_KEY,
  appGit: { sourceDirectory: "/path/to/application" },
});

registerOTel({
  traceExporter: exporter,
  spanProcessors: ["auto", createEveAppGitSpanProcessor(exporter)],
});

This keeps the normal batch exporter and Vercel processors. Without start capture, a direct exporter reports only explicit client, environment, operation, or span values; it never adds an inferred revision discovered after an unobserved span started.

Getting Started

SDK

Integrations

Platform

Organization

Cookbooks

Workshop

Query API

MCP

Security

Support

Installation

Quick Start

How It Works

Sub-Agents

Configuration

Projects

Identifying Users

Using the Slack user’s name / email / channel name

Workshop / Production Mirroring

Production-Only Mode

Workshop-Only Mode (no Raindrop account)

Captured Trace Hierarchy

Captured Event Fields

Flush & Shutdown

Known Limitations

Application Git identity

​Installation

​Quick Start

​How It Works

​Sub-Agents

​Configuration

​Projects

​Identifying Users

​Using the Slack user’s name / email / channel name

​Workshop / Production Mirroring

​Production-Only Mode

​Workshop-Only Mode (no Raindrop account)

​Captured Trace Hierarchy

​Captured Event Fields

​Flush & Shutdown

​Known Limitations

​Application Git identity

Installation

Quick Start

How It Works

Sub-Agents

Configuration

Projects

Identifying Users

Using the Slack user’s name / email / channel name

Workshop / Production Mirroring

Production-Only Mode

Workshop-Only Mode (no Raindrop account)

Captured Trace Hierarchy

Captured Event Fields

Flush & Shutdown

Known Limitations

Application Git identity