@raindrop-ai/temporal

Raindrop integration for Temporal. Automatically instruments workflow executions, activity spans, and distributed trace propagation across workers.

Installation

npm install @raindrop-ai/temporal @temporalio/client @temporalio/worker

Usage

Client

import { Client, Connection } from "@temporalio/client";
import { createRaindropTemporal } from "@raindrop-ai/temporal";

const raindrop = createRaindropTemporal({
  writeKey: process.env.RAINDROP_WRITE_KEY,
  userId: "user-123",
});

const connection = await Connection.connect();
const client = new Client({
  connection,
  interceptors: {
    workflow: [raindrop.interceptors.client],
  },
});

const handle = await client.workflow.start("processOrder", {
  taskQueue: "my-queue",
  workflowId: "order-123",
  args: [{ orderId: "order-123" }],
});

await raindrop.shutdown();

Worker

import { Worker } from "@temporalio/worker";
import { createRaindropTemporal } from "@raindrop-ai/temporal";
import * as activities from "./activities";

const raindrop = createRaindropTemporal({
  writeKey: process.env.RAINDROP_WRITE_KEY,
});

const worker = await Worker.create({
  taskQueue: "my-queue",
  workflowsPath: require.resolve("./workflows"),
  activities,
  interceptors: {
    activity: [raindrop.interceptors.activityFactory],
    workflowModules: ["@raindrop-ai/temporal/workflow-interceptors"],
  },
  sinks: raindrop.sinks,
});

process.on("SIGINT", async () => {
  await worker.shutdown();
  await raindrop.shutdown();
});

await worker.run();

What gets captured

• Workflow triggers — span when a client starts a workflow
• Workflow execution — span covering the full workflow lifecycle
• Activities — each activity appears as a tool call in the Raindrop dashboard
• Child workflows — nested under their parent with correct span hierarchy
• Distributed traces — context propagated across workers via Temporal headers
• Errors — captured with error status, re-thrown to caller

Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | writeKey | string | — | Raindrop write key. Omit to disable telemetry. | | endpoint | string | https://api.raindrop.ai/v1/ | API endpoint | | userId | string | — | Associate events with a user | | convoId | string | — | Group events into a conversation | | projectId | string | — | Route events to a specific project (slug); omit for the default Production project | | debug | boolean | false | Enable verbose logging | | maxTextFieldChars | number | 1000000 | Per-field character cap for captured activity result text |

Projects

If your org has multiple projects, route events to a specific one by passing its slug as projectId:

const raindrop = createRaindropTemporal({
  writeKey: process.env.RAINDROP_WRITE_KEY,
  projectId: "support-prod",
});

This sets the X-Raindrop-Project-Id header on every event and trace. Omit it (or pass "default") to use your org's default Production project — the existing behavior. Single-project orgs need nothing new.

Payload size limits

String activity results captured onto spans are capped at 1,000,000 characters by default and truncated with a ...[truncated by raindrop] marker (the result, marker included, never exceeds the limit), so multi-MB activity outputs cost the cap — not the payload — on the worker, and oversized spans land truncated instead of being dropped at the ingest size limit. Tune it via maxTextFieldChars. The activity's own return value is never altered.

Documentation

Full docs with dashboard screenshots and architecture details: raindrop.ai/docs/integrations/temporal

License

MIT