TypeScript - Raindrop

Installation

Install with your package manager of choice:

npm install raindrop-ai

yarn add raindrop-ai

pnpm add raindrop-ai

bun add raindrop-ai

import { Raindrop } from "raindrop-ai";

// Replace with the key from your Raindrop dashboard
const raindrop = new Raindrop({ writeKey: RAINDROP_API_KEY });

Quick Start: Interaction API

The Interaction API uses a simple three-step pattern:

begin() – Create an interaction and log the initial user input
Update – Optionally call setProperty, setProperties, or addAttachments
finish() – Record the AI’s final output and close the interaction

Using Vercel AI SDK? Check out our automatic integration to track AI events and traces with zero configuration.

Example: Chat Completion

import { openai } from '@ai-sdk/openai';
import { generateText } from 'ai';
import { randomUUID } from "crypto";
import { Raindrop } from "raindrop-ai";

const raindrop = new Raindrop({ writeKey: RAINDROP_API_KEY });

const message = "What is love?";
const eventId = randomUUID(); // Generate your own ID for log correlation

// 1. Start the interaction
const interaction = raindrop.begin({
  eventId,
  event: "chat_message",
  userId: "user_123",
  input: message,
  model: "gpt-4o",
  convoId: "convo_123",
  properties: {
    tool_call: "reasoning_engine",
    system_prompt: "you are a helpful...",
    experiment: "experiment_a",
  },
});

// 2. Make the LLM call
const { text } = await generateText({
  model: openai("gpt-4o"),
  prompt: message,
});

// 3. Finish the interaction
interaction.finish({
  output: text,
});

Updating an Interaction

Update an interaction at any point using setProperty, setProperties, or addAttachments:

interaction.setProperty("stage", "embedding");
interaction.addAttachments([
  {
    type: "text",
    name: "Additional Info",
    value: "A very long document",
    role: "input",
  },
  { type: "image", value: "https://example.com/image.png", role: "output" },
  {
    type: "iframe",
    name: "Generated UI",
    value: "https://newui.generated.com",
    role: "output",
  },
]);

Resuming an Interaction

If you no longer have the interaction object returned from begin(), resume it with resumeInteraction():

const interaction = raindrop.resumeInteraction(eventId);

Interactions are subject to a 1 MB event limit. Oversized payloads will be truncated. Contact us if you have custom requirements.

Single-Shot Tracking (`trackAi`)

For simple request-response interactions, you can use trackAi() directly:

raindrop.trackAi({
  event: "user_message",
  userId: "user123",
  model: "gpt-4o-mini",
  input: "Who won the 2023 AFL Grand Final?",
  output: "Collingwood by four points!",
  properties: {
    tool_call: "reasoning_engine",
    system_prompt: "you are a helpful...",
    experiment: "experiment_a",
  },
});

We recommend using begin() → finish() for new code to take advantage of partial-event buffering, tracing, and upcoming features like automatic token counts.

Tracking Signals (Feedback)

Signals capture quality ratings on AI events. Use trackSignal() with the same eventId from begin() or trackAi():

Parameter	Type	Description
`eventId`	`string`	The ID of the AI event you’re evaluating
`name`	`"thumbs_up"`, `"thumbs_down"`, `string`	Signal name
`type`	`"default"`, `"standard"`, `"feedback"`, `"edit"`, `"agent"`, `"agent_internal"`	Optional, defaults to `"default"`
`comment`	`string`	User comment (for `feedback` signals)
`after`	`string`	User’s edited content (for `edit` signals)
`sentiment`	`"POSITIVE"`, `"NEGATIVE"`	Signal sentiment (defaults to `"NEGATIVE"`)

await raindrop.trackSignal({
  eventId: "my_event_id",
  name: "thumbs_down",
  comment: "Answer was off-topic",
});

Self Diagnostics

Self Diagnostics lets your agent proactively report its own issues — capability gaps, missing context, persistent tool failures — back to your team. Signals appear in Raindrop’s Self Diagnostics dashboard. The easiest way to enable Self Diagnostics is by using wrap() with the Vercel AI SDK:

import * as ai from "ai";

const { generateText, streamText } = raindrop.wrap(ai, {
  context: { userId: "user_123", eventName: "support-agent" },
  selfDiagnostics: {
    enabled: true,
  },
});

See the Vercel AI SDK docs for the full wrap() reference. For integrations that don’t use the Vercel AI SDK, or can’t use wrap(), the sections below cover standalone alternatives.

Self Diagnostics Tool

createSelfDiagnosticsTool() creates a tool your agent can call to report issues. It gives you:

A reusable execute() handler that tracks an agent signal
Adapter-specific tool definitions for Vercel AI SDK, OpenAI SDK, and Anthropic SDK

The four default categories are missing_context, repeatedly_broken_tool, capability_gap, and complete_task_failure. You can replace these with your own.

Self diagnostics requires an eventId to correlate the signal with an interaction. Pass eventId, interaction, or getEventId when creating the tool.

const interaction = raindrop.begin({
  eventId: "evt_123",
  event: "agent_run",
  userId: "user_123",
  input: "Fix my deployment",
});

const diagnostics = raindrop.createSelfDiagnosticsTool({
  interaction, // pulls eventId from interaction.getEventId()
  toolName: "__raindrop_report", // optional
  guidance: "Optional extra guidance for your domain", // optional
  // Default signals (used when `signals` is omitted):
  signals: {
    missing_context: {
      description:
        "You cannot complete the task because critical information, credentials, or access is missing and the user cannot provide it. " +
        "Do NOT report this for normal clarifying questions — only when you are blocked.",
      sentiment: "NEGATIVE",
    },
    repeatedly_broken_tool: {
      description:
        "A tool has failed on multiple distinct attempts in this conversation, preventing task completion. You are sure the tool exists, and you have tried to use it, but it has failed. " +
        "A single tool error is NOT enough — the tool must be persistently broken across retries.",
      sentiment: "NEGATIVE",
    },
    capability_gap: {
      description:
        "The task requires a tool, permission, or capability that you do not have. " +
        "For example, the user asks you to perform an action but no suitable tool exists, or you lack the necessary access. " +
        "Do NOT report this if you simply need more information from the user — only when the gap is in your own capabilities.",
      sentiment: "NEGATIVE",
    },
    complete_task_failure: {
      description:
        "You were unable to accomplish what the user asked despite making genuine attempts. This might be things like, you genuinely do not have the capabilities the user is asking for. You have tried but run into a persistent bug in the environment etc. " +
        "This is NOT a refusal or policy block — you tried and failed to deliver the result.",
      sentiment: "NEGATIVE",
    },
  },
});

// Later, when tool is executed:
await diagnostics.execute({
  category: "missing_context",
  detail: "Missing deployment credentials and logs access.",
});

You don’t need to mention self diagnostics in your system prompt — the tool description generated by the SDK already tells the model when and how to call it. Just wire the tool into your LLM call using one of the adapters below. When the agent calls the tool, a signal is tracked on the same eventId:

{
  "event_id": "evt_...",
  "signal_name": "self diagnostics - missing_context",
  "signal_type": "agent",
  "properties": {
    "source": "agent_reporting_tool",
    "category": "missing_context",
    "signal_description": "You cannot complete the task because critical information...",
    "detail": "User asked to fix deployment but no access to logs or SSH credentials."
  }
}

Supported adapters

createSelfDiagnosticsTool() supports these adapters:

Adapter	Use with	Returns
`diagnostics.forVercelAI()`	`ai` package / Vercel AI SDK	`{ description, parameters, inputSchema, execute }`
`diagnostics.forOpenAI()`	`openai` package function tools	OpenAI `tools` entry (`type: "function"`)
`diagnostics.forAnthropic()`	`@anthropic-ai/sdk` tool config	Anthropic `tools` entry (`input_schema`)

Vercel AI SDK:

const tools = {
  [diagnostics.name]: diagnostics.forVercelAI(),
};

OpenAI SDK:

const response = await openai.chat.completions.create({
  model: "gpt-4o-mini",
  messages,
  tools: [diagnostics.forOpenAI()],
  tool_choice: { type: "function", function: { name: diagnostics.name } },
});

const toolCall = response.choices[0]?.message.tool_calls?.[0];
if (toolCall) {
  await diagnostics.execute(JSON.parse(toolCall.function.arguments || "{}"));
}

Anthropic SDK:

const response = await anthropic.messages.create({
  model: "claude-sonnet-4-6",
  max_tokens: 512,
  messages,
  tools: [diagnostics.forAnthropic()],
  tool_choice: { type: "tool", name: diagnostics.name },
});

const block = response.content.find((b) => b.type === "tool_use");
if (block && block.type === "tool_use") {
  await diagnostics.execute(block.input);
}

UI guidance

__raindrop_report is an internal tool. If your chat UI renders tool calls, hide this tool call from end users to avoid confusing them with internal diagnostics details.

const visibleToolCalls = toolCalls.filter((call) => call.toolName !== diagnostics.name);

Manual Reporting

If your agent already has its own way of detecting issues, use selfDiagnose() to report them directly — no LLM tool call needed.

raindrop.selfDiagnose({
  eventId: "evt_123",
  description: "User asked for production DB access but no credentials were provided.",
  category: "missing_context",   // optional — defaults to "general"
});

Parameter	Type	Required	Description
`eventId`	`string`	Yes	Interaction/event ID (from `begin()` or `trackAi()`)
`description`	`string`	Yes	Human-readable description of the issue
`category`	`string`	No	Category name (e.g. `"missing_context"`). Defaults to `"general"`
`source`	`string`	No	Origin identifier. Defaults to `"selfDiagnose"`
`sentiment`	`"POSITIVE"` \| `"NEGATIVE"`	No	Defaults to `"NEGATIVE"`
`properties`	`Record<string, unknown>`	No	Additional custom properties

Attachments

Attachments let you include additional context—documents, images, code, or embedded content—with your events. They work with both begin() interactions and trackAi() calls.

Property	Type	Description
`type`	`string`	`"code"`, `"text"`, `"image"`, or `"iframe"`
`name`	`string`	Optional display name
`value`	`string`	Content or URL
`role`	`string`	`"input"` or `"output"`
`language`	`string`	Programming language (for `code` attachments)

interaction.addAttachments([
  {
    type: "code",
    role: "input",
    language: "typescript",
    name: "example.ts",
    value: "console.log('hello');",
  },
  {
    type: "text",
    name: "Additional Info",
    value: "Some extra text",
    role: "input",
  },
  { type: "image", value: "https://example.com/image.png", role: "output" },
  { type: "iframe", value: "https://example.com/embed", role: "output" },
]);

Feature Flags

Feature flags record which flags and experiment variants were active when an event happened, so you can compare AI quality across variants in Raindrop. Like properties, they attach to individual events — pass them wherever the event is created (begin() or trackAi()), or set them on a live interaction as your pipeline makes decisions. Two input forms are accepted:

Form	Example	Sent as `feature_flags`
Array of flag names (each implicitly `"true"`)	`["prompt-v2", "reasoning"]`	`{"prompt-v2": "true", "reasoning": "true"}`
Object with explicit values (`string`, `number`, or `boolean` — stringified)	`{ "prompt-version": "v2", "max-retries": 3, "reasoning": false }`	`{"prompt-version": "v2", "max-retries": "3", "reasoning": "false"}`

With `begin()`

Pass the flags that shaped the request — typically the values you just read from your flag provider (LaunchDarkly, Statsig, PostHog, etc.):

// Flag values you resolved for this user
const promptVersion = await flagProvider.getVariant("prompt-version", userId); // "v1" | "v2"
const reasoningEnabled = await flagProvider.isEnabled("reasoning", userId);    // boolean

const interaction = raindrop.begin({
  event: "chat_message",
  userId,
  input: message,
  model: "gpt-4o",
  // Array form also works: featureFlags: ["prompt-v2", "reasoning"]
  featureFlags: {
    "prompt-version": promptVersion,
    reasoning: reasoningEnabled,
  },
});

const { text } = await generateText({
  model: openai("gpt-4o"),
  system: promptVersion === "v2" ? SYSTEM_PROMPT_V2 : SYSTEM_PROMPT_V1,
  prompt: message,
});

interaction.finish({ output: text });

Updating a live interaction

Use setFeatureFlag / setFeatureFlags when a flag decision happens mid-interaction — for example, a retrieval strategy chosen after begin():

interaction.setFeatureFlag("retrieval-strategy", "hybrid"); // explicit value
interaction.setFeatureFlag("semantic-cache");               // value defaults to "true"
interaction.setFeatureFlags(["rerank", "query-expansion"]); // array form — both "true"

Method	Parameters	Behavior
`setFeatureFlag`	`(name: string, value?: string \| number \| boolean)`	Sets one flag; `value` defaults to `"true"`
`setFeatureFlags`	`(flags: string[] \| Record<string, string \| number \| boolean>)`	Normalizes and merges into existing flags

Flags merge across calls; setting the same flag again overwrites its value.

With `trackAi()`

raindrop.trackAi({
  event: "summarize_ticket",
  userId,
  model: "gpt-4o-mini",
  input: ticketText,
  output: summary,
  featureFlags: ["summary-prompt-v2"], // sent as {"summary-prompt-v2": "true"}
});

Identifying Users

raindrop.setUserDetails({
  userId: "user123",
  traits: {
    name: "Jane",
    email: "jane@example.com",
    plan: "paid", // we recommend 'free', 'paid', 'trial'
    os: "macOS",
  },
});

PII Redaction

Read more about how Raindrop handles privacy and PII redaction here. Enable client-side PII redaction when initializing the SDK:

new Raindrop({
  writeKey: RAINDROP_API_KEY,
  redactPii: true,
});

Error Handling

Exceptions are raised when errors occur while sending events to Raindrop. Handle these appropriately in your application.

Configuration

new Raindrop({
  writeKey: RAINDROP_API_KEY,
  debugLogs: process.env.NODE_ENV !== "production",  // Print queued events
  disabled: process.env.NODE_ENV === "test",         // Disable all tracking
});

Option	Type	Default	Description
`writeKey`	`string`	—	Your Raindrop API key (required)
`projectId`	`string`	`"default"`	Send events to a specific project; omit for the default Production project
`debugLogs`	`boolean`	`false`	Print queued events and tracing info to console
`disabled`	`boolean`	`false`	Disable all tracking (useful for test environments)
`redactPii`	`boolean`	`false`	Enable client-side PII redaction
`useExternalOtel`	`boolean`	`false`	Use your own OpenTelemetry setup instead of Raindrop’s built-in one
`bypassOtelForTools`	`boolean`	`false`	Ship `trackTool()` / `withTool()` / `startToolSpan()` spans directly via HTTP, bypassing the OTEL exporter
`disableBatching`	`boolean`	`true` in dev	Disable span batching for faster feedback in development

Call await raindrop.close() before your process exits to flush any buffered events.

Projects

Pass projectId to scope every event from a client to a specific project. Under the hood this sets the X-Raindrop-Project-Id header on each request.

const raindrop = new Raindrop({
  writeKey: RAINDROP_API_KEY,
  projectId: "support-prod",
});

Omitting projectId (or passing "default") sends to the default Production project, which is the existing behavior. See Projects for isolation, archival, and the full behavior table.

Multiple projects in one process

When one service runs several agents that should report to different projects — e.g. an Express app serving a support agent and a billing agent — create one Raindrop client per project and reuse them. The instance is the routing decision; there is no shared mutable project state to race on, so concurrent requests handled by different agents route independently.

import { Raindrop } from "raindrop-ai";

// One long-lived client per project, created at startup and reused.
const rdSupport = new Raindrop({ writeKey: RAINDROP_API_KEY, projectId: "support-prod" });
const rdBilling = new Raindrop({ writeKey: RAINDROP_API_KEY, projectId: "billing-prod" });

// Each client owns its delivery pipeline — events ship to its own project.
const interaction = rdBilling.begin({ userId: "u1", event: "billing-chat", input: "..." });
interaction.trackTool({ name: "invoice_lookup", input: {}, output: {} });
interaction.finish({ output: "..." });            // -> billing-prod

rdSupport.trackAi({ userId: "u1", event: "support-chat", input: "q", output: "a" });  // -> support-prod

Tracing across multiple projects. OpenTelemetry auto-instrumentation is shared per process: the first client that enables tracing initializes it, and later clients share the pipeline. begin() scopes every span produced in the current request/task to its client’s project, until the matching finish() (an interaction that is never finished releases its scope once garbage-collected). For LLM calls made outside an interaction, scope them explicitly with asCurrent():

await rdBilling.asCurrent(async () => {
  await openai.chat.completions.create({ ... });  // spans -> billing-prod
});

One tracing API key per process: all auto-instrumented spans export under the first tracing-enabled client’s write key. Clients created with a different writeKey (a different workspace) get a warning, and from then on only spans scoped to a client via begin()/asCurrent() are exported — the other workspace’s spans and any unscoped spans are dropped at export rather than delivered to the wrong workspace. Run a second workspace’s tracing in its own process. Single-key processes (the normal case) are unaffected. useExternalOtel is unsupported when more than one write key is used in a single process. Manual events (trackAi, begin/finish, signals, identify) always ship with each client’s own key and are unaffected.

On runtimes without AsyncLocalStorage.enterWith — notably Cloudflare Workers (workerd) — begin() cannot scope auto-instrumented spans: it still records the interaction and its manual withSpan/withTool/events, but ambient span routing is skipped (so it can’t cross-contaminate concurrent requests). Use asCurrent() (or interaction.withSpan(...)) to route auto-instrumented spans there — those are built on AsyncLocalStorage.run, which Workers support.

Tracing

Tracing captures detailed execution information from your AI pipelines—multi-model interactions, chained prompts, and tool calls. This helps you:

Visualize the full execution flow of your AI application
Debug and optimize prompt chains
Understand the intermediate steps that led to a response

Getting Started

Wrap your code with withSpan or withTool on an interaction, and LLM calls inside are automatically captured:

import { Raindrop } from "raindrop-ai";

const raindrop = new Raindrop({ writeKey: RAINDROP_API_KEY });

const interaction = raindrop.begin({ ... });
await interaction.withSpan({ name: "my_task" }, async () => {
  // LLM calls here are automatically traced
});

Next.js users: Add raindrop-ai to serverExternalPackages in your config:

// next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
  serverExternalPackages: ['raindrop-ai'],
};

module.exports = nextConfig;

Using `withSpan`

Use withSpan to trace tasks or operations. Any LLM calls within the span are automatically captured:

// Basic span
const result = await interaction.withSpan(
  { name: "generate_response" },
  async () => {
    return "Generated response";
  }
);

// Span with metadata
const result = await interaction.withSpan(
  {
    name: "embedding_generation",
    properties: { model: "text-embedding-3-large" },
    inputParameters: ["What is the weather today?"],
  },
  async () => {
    return [0.1, 0.2, 0.3, 0.4];
  }
);

Parameter	Type	Description
`name`	`string`	Name for identification in traces
`properties`	`Record<string, string>`	Additional metadata
`inputParameters`	`unknown[]`	Input parameters for the task

Using `withTool`

Use withTool to trace agent actions—memory operations, web searches, API calls, and more:

// Basic tool call
const result = await interaction.withTool(
  { name: "search_tool" },
  async () => {
    return "Search results";
  }
);

// Tool with metadata
const result = await interaction.withTool(
  {
    name: "calculator",
    properties: { operation: "multiply" },
    inputParameters: { a: 5, b: 10 },
  },
  async () => {
    return "Result: 50";
  }
);

Parameter	Type	Description
`name`	`string`	Name for identification in traces
`version`	`number`	Version number of the tool
`properties`	`Record<string, string>`	Additional metadata
`inputParameters`	`Record<string, any>`	Input parameters for the tool
`traceContent`	`boolean`	Whether to trace content
`suppressTracing`	`boolean`	Suppress tracing for this invocation

Manual Tool Tracking

For more control over tool span tracking, use trackTool or startToolSpan.

`trackTool` – Retroactive Logging

Use trackTool to log a tool call after it has completed:

const interaction = raindrop.begin({
  eventId: "my-event",
  event: "agent_run",
  userId: "user_123",
  input: "Search for weather data",
});

// Log a completed tool call
interaction.trackTool({
  name: "web_search",
  input: { query: "weather in NYC" },
  output: { results: ["Sunny, 72°F", "Clear skies"] },
  durationMs: 150,
  properties: { engine: "google" },
});

// Log a failed tool call
interaction.trackTool({
  name: "database_query",
  input: { query: "SELECT * FROM users" },
  durationMs: 50,
  error: new Error("Connection timeout"),
});

interaction.finish({ output: "Weather search complete" });

Parameter	Type	Description
`name`	`string`	Name of the tool
`input`	`unknown`	Input passed to the tool
`output`	`unknown`	Output returned by the tool
`durationMs`	`number`	Duration in milliseconds
`startTime`	`Date \| number`	When the tool started (defaults to `now - durationMs`)
`error`	`Error \| string`	Error if the tool failed
`properties`	`Record<string, string>`	Additional metadata
`traceId`	`string`	W3C trace ID override (requires `parentSpanId`)
`parentSpanId`	`string`	W3C parent span ID override (requires `traceId`)

`startToolSpan` – Real-Time Tracking

Use startToolSpan to track a tool as it executes:

const interaction = raindrop.begin({
  eventId: "my-event",
  event: "agent_run",
  userId: "user_123",
  input: "Process this data",
});

const toolSpan = interaction.startToolSpan({
  name: "api_call",
  properties: { endpoint: "/api/data" },
  inputParameters: { method: "GET", path: "/api/data" },
});

try {
  const result = await fetchData();
  toolSpan.setOutput(result);
} catch (error) {
  toolSpan.setError(error);
} finally {
  toolSpan.end();
}

interaction.finish({ output: "Data processed" });

Method	Description
`setInput(input)`	Set the input (JSON stringified if object)
`setOutput(output)`	Set the output (JSON stringified if object)
`setError(error)`	Mark the span as failed
`end()`	End the span (required when execution completes)

Module Instrumentation

In some environments, automatic instrumentation may not work due to module loading order or bundler behavior. Use instrumentModules to explicitly specify which modules to instrument:

Anthropic users: You must use a module namespace import (import * as ...), not the default export.

import OpenAI from "openai";
import Anthropic from "@anthropic-ai/sdk";
import * as AnthropicModule from "@anthropic-ai/sdk";  // Required for instrumentation
import { Raindrop } from "raindrop-ai";

const raindrop = new Raindrop({
  writeKey: RAINDROP_API_KEY,
  instrumentModules: {
    openAI: OpenAI,
    anthropic: AnthropicModule,  // Pass the module namespace, not the default export
  },
});

Supported modules: openAI, anthropic, cohere, bedrock, google_vertexai, google_aiplatform, pinecone, together, langchain, llamaIndex, chromadb, qdrant, mcp. For Bedrock, use a namespace import — same pattern as Anthropic above. Cross-region inference profile model IDs (e.g. us.anthropic.claude-*) are supported.

import * as BedrockModule from "@aws-sdk/client-bedrock-runtime";

const raindrop = new Raindrop({
  writeKey: RAINDROP_API_KEY,
  instrumentModules: { bedrock: BedrockModule },
});

OpenTelemetry Integration

If you already have an OpenTelemetry setup (Sentry, Datadog, Honeycomb, etc.), integrate Raindrop alongside it using useExternalOtel:

import { NodeSDK } from "@opentelemetry/sdk-node";
import * as AnthropicModule from "@anthropic-ai/sdk";
import Anthropic from "@anthropic-ai/sdk";
import { Raindrop } from "raindrop-ai";

// 1. Create Raindrop with useExternalOtel
const raindrop = new Raindrop({
  writeKey: RAINDROP_API_KEY,
  useExternalOtel: true,
  instrumentModules: { anthropic: AnthropicModule },
});

// 2. Add Raindrop's processor and instrumentations to your NodeSDK
const sdk = new NodeSDK({
  spanProcessors: [
    raindrop.createSpanProcessor(),  // Sends traces to Raindrop
    datadogProcessor,                  // Your existing processor
  ],
  instrumentations: raindrop.getInstrumentations(),
});
sdk.start();

// If using Sentry, skip NodeSDK and pass the processor directly:
// Sentry.init({
//   dsn: process.env.SENTRY_DSN,
//   openTelemetrySpanProcessors: [raindrop.createSpanProcessor()],
// });

// 3. Create AI clients AFTER SDK starts
const anthropic = new Anthropic({ apiKey: "..." });

// 4. Use Raindrop normally
const interaction = raindrop.begin({
  eventId: "my-event",
  event: "chat_request",
  userId: "user_123",
  input: "Hello!",
});

await interaction.withSpan({ name: "generate_response" }, async () => {
  const response = await anthropic.messages.create({
    model: "claude-3-haiku-20240307",
    max_tokens: 100,
    messages: [{ role: "user", content: "Hello!" }],
  });
  return response;
});

interaction.finish({ output: "Response from Claude" });

Method	Description
`createSpanProcessor()`	Returns a span processor that sends traces to Raindrop
`getInstrumentations()`	Returns OpenTelemetry instrumentations for AI libraries

Without instrumentModules, getInstrumentations() returns instrumentations for all supported AI libraries. Specify instrumentModules to instrument only specific libraries.

Direct tool spans in stateless handlers

bypassOtelForTools: true changes how tool spans are shipped, but they still read their parent from the active @opentelemetry/api context. trace.setSpanContext() with context.with() is sufficient when the handler, Sentry, and Raindrop share the same OpenTelemetry API singleton and context manager. If a stateless handler cannot rely on ambient context, pass the propagated W3C hexadecimal IDs directly. Both values must be supplied together:

raindrop.resumeInteraction(eventId).trackTool({
  name,
  input,
  output,
  durationMs,
  traceId,       // 32 hexadecimal characters
  parentSpanId,  // 16 hexadecimal characters
});

Invalid or incomplete overrides are ignored, and the SDK falls back to the active OpenTelemetry context.

Detached sub-agents (Beta)

A detached sub-agent runs asynchronously in another process, worker, or machine. Unlike resumeInteraction(), which joins the parent’s event, it reports as its own event. The parent mints the child event and sends a hand-off carrier; the worker resumes that event and reports its result.

Beta. The detached sub-agent API surface may change in a minor release. Requires raindrop-ai 0.3.0 or later.

Dispatch from the parent

Each process creates its own Raindrop instance. The parent allocates the child event before sending the job:

// Parent process
import { Raindrop } from "raindrop-ai";

const raindrop = new Raindrop({
  writeKey: process.env.RAINDROP_API_KEY,
});

const interaction = raindrop.begin({
  event: "parent_turn",
  userId: "user_123",
  convoId: "conversation_456",
  input: "Find the relevant documents",
});

const dispatch = interaction.subagent({
  name: "researcher",
  input: { task: "Find the relevant documents" },
});

Send the hand-off

Send the job with all of dispatch.headers:

await queue.send({
  task: "Find the relevant documents",
  headers: dispatch.headers,
});

await interaction.finish({
  output: `Dispatched ${dispatch.name} as ${dispatch.childEventId}`,
});

childEventId is allocated before dispatch, so the link is resolvable while the job is queued. The dispatch span is named launch_subagent by default; use toolName to choose another name.interaction.subagent() returns:

childEventId — the child event id, allocated before dispatch
name — the sub-agent name
parentEventId — the parent event id
dispatchSpanId — the dispatch span id, when tracing is enabled
headers — the native carrier headers
langsmithHeaders — the carrier in LangSmith’s header shape
carrier — the parsed carrier for non-HTTP transports

Send all returned headers, not only traceparent. The carrier includes traceparent, baggage with raindrop-* fields, and x-raindrop-handoff. The hand-off header wins if standard propagation headers are rewritten or replaced.

With disabled: true, childEventId is still allocated, but carrier is null and both header objects are empty. There is no dispatch span or carrier link.

Resume in the worker

The carrier travels with the job. It is JSON-serialisable, so a queue, file, or another process can carry it. The worker’s request.headers below means the received header bag:

// Worker process
import { Raindrop } from "raindrop-ai";

const raindrop = new Raindrop({
  writeKey: process.env.RAINDROP_API_KEY,
});

const run = raindrop.resumeSubagent(request.headers);

try {
  const answer = await run.interaction.withTool(
    { name: "search_corpus" },
    () => doTheWork()
  );
  await run.finish({ output: answer });
} catch (error) {
  await run.fail(error);
}

await raindrop.close();

For a non-HTTP transport, the first argument accepts the received TraceCarrier too:

const run = raindrop.resumeSubagent(carrier);
// Equivalent: raindrop.resumeSubagent(undefined, { parent: carrier });

A short-lived worker must await raindrop.close() before exit to flush buffered events.

Report the outcome

withSubagentRun() wraps the same worker flow:

await raindrop.withSubagentRun(request.headers, async (run) => {
  await run.finish({ output: await doTheWork() });
});

It resolves with the callback’s return value. If the callback returns without reporting, the SDK aborts the run. If it throws, the SDK reports the failure and rethrows the error.

run.interaction is the child’s ordinary interaction object. It supports withSpan, withTool, trackTool, and the other interaction APIs. Use the object form: withTool({ name: "search_corpus" }, fn). While the run is open, its reverse reference is bound to the execution context. Every span the child emits—including auto-instrumented spans—is linked back to the dispatch. cancel() emits no span, so a cancelled child has no reverse reference on a child span.

Reported outcomes

finish({ output }) reports a successful result; the caller supplies the output.
fail(reason) marks telemetry as errored and synthesizes output from the reason.
cancel(reason) writes a terminal event with raindrop.handoff.terminal=cancelled and synthesized output, but emits no span or errored span.

Status comes from the child’s telemetry, so a failed run needs an errored span. Only a child that reports no outcome at all produces no event, leaving its launcher queued.

Carrier rules

The carrier is authoritative. SubagentResumeOptions values (name, eventId, userId, convoId, event, input, model, or properties) are fallbacks only when no carrier is available. A missing carrier is valid: the child still reports its own event, with run.linked === false and run.parent === null. When a carrier resolves, run.linked === true and run.parent describes the launching context, including the parent event id and dispatch span id. The child’s run.eventId is the childEventId allocated by the parent.

Only accept carriers inside your own trust boundary; an untrusted carrier can attribute a child to another tenant’s event. For non-HTTP transports, pass the carrier as the first argument or use resumeSubagent(undefined, { parent: carrier }). Passing { parent: carrier } as the first argument does not link the run.

Dispatch options

Option	Type	Description
`name`	`string`	Name of the sub-agent
`input`	`unknown`	Launch arguments recorded on the dispatch span
`childEventId`	`string`	Optional caller-supplied child event id
`toolName`	`string`	Dispatch span name; defaults to `launch_subagent`
`properties`	`RaindropProperties`	Extra dispatch span properties

That’s it! You’re ready to explore your events in the Raindrop dashboard. Ping us on Slack or email us if you get stuck!

​Installation

​Quick Start: Interaction API

​Example: Chat Completion

​Updating an Interaction

​Resuming an Interaction

​Single-Shot Tracking (trackAi)

​Tracking Signals (Feedback)

​Self Diagnostics

​Self Diagnostics Tool

​Supported adapters

​UI guidance

​Manual Reporting

​Attachments

​Feature Flags

​With begin()

​Updating a live interaction

​With trackAi()

​Identifying Users

​PII Redaction

​Error Handling

​Configuration

​Projects

​Multiple projects in one process

​Tracing

​Getting Started

​Using withSpan

​Using withTool

​Manual Tool Tracking

​trackTool – Retroactive Logging

​startToolSpan – Real-Time Tracking

​Module Instrumentation

​OpenTelemetry Integration

​Direct tool spans in stateless handlers

​Detached sub-agents (Beta)

​Reported outcomes

​Carrier rules

​Dispatch options

Installation

Quick Start: Interaction API

Example: Chat Completion

Updating an Interaction

Resuming an Interaction

Single-Shot Tracking (`trackAi`)

Tracking Signals (Feedback)

Self Diagnostics

Self Diagnostics Tool

Supported adapters

UI guidance

Manual Reporting

Attachments

Feature Flags

With `begin()`

Updating a live interaction

With `trackAi()`

Identifying Users

PII Redaction

Error Handling

Configuration

Projects

Multiple projects in one process

Tracing

Getting Started

Using `withSpan`

Using `withTool`

Manual Tool Tracking

`trackTool` – Retroactive Logging

`startToolSpan` – Real-Time Tracking

Module Instrumentation

OpenTelemetry Integration

Direct tool spans in stateless handlers

Detached sub-agents (Beta)

Reported outcomes

Carrier rules

Dispatch options