TypeScript

import { Raindrop } from "raindrop-ai";

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

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,
});

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",
  },
]);

const interaction = raindrop.resumeInteraction(eventId);

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",
  },
});

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

import * as ai from "ai";

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

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.",
});

{
  "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."
  }
}

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

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 || "{}"));
}

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);
}

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

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

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" },
]);

// 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 });

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

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

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

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

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

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

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

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

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.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
  serverExternalPackages: ['raindrop-ai'],
};

module.exports = nextConfig;

// 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];
  }
);

// 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";
  }
);

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" });

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" });

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
  },
});

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

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

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" });

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