Temporal (Beta)

Documentation Index

Fetch the complete documentation index at: https://raindrop.ai/docs/llms.txt

Use this file to discover all available pages before exploring further.

​

Installation

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

​

Quick Start

​

Client Setup

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 Setup

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,
  userId: "worker-1",
});

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

// Shut down Raindrop when the worker stops
process.on("SIGINT", async () => {
  await worker.shutdown();
  await raindrop.shutdown();
});

await worker.run();

​

What Gets Traced

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

​

What shows in the dashboard

• Events page — each workflow appears as an event with input (Workflow: {type}) and output (Workflow completed: {type})
• Tool calls — activities appear in the event’s tool calls list with their activity type as the name
• Traces tab — full span hierarchy: trigger → workflow → activities, with parent-child nesting for child workflows
• Properties — temporal.workflow_type, temporal.workflow_id, temporal.run_id, and child workflow statuses

​

Configuration

const raindrop = createRaindropTemporal({
  writeKey: process.env.RAINDROP_WRITE_KEY, // Optional: omit to disable telemetry
  endpoint: "...",                           // Optional: custom Raindrop API endpoint
  userId: "user-123",                        // Optional: associate events with a user
  convoId: "convo-456",                      // Optional: conversation/thread ID
  debug: false,                              // Optional: enable verbose logging
});

​

Architecture

1. Client interceptor — wraps client.workflow.start() to create a root trigger span and inject trace context into workflow headers
2. Activity interceptor — creates a span per activity execution, parenting under the workflow span (same-worker) or using header-propagated context (cross-worker)
3. Workflow interceptors — propagate trace context from workflows to their activities and child workflows
4. Sinks — manage workflow-level spans, tracking start and completion events

​

Flushing and Shutdown

await raindrop.flush();     // flush pending data
await raindrop.shutdown();  // flush + release resources

​

Known Limitations

• Abnormally terminated workflows — if a workflow is externally terminated or cancelled without completing normally, the corresponding event may remain in a pending state.
• Cross-worker trace nesting — when an activity runs on a different worker than its workflow, the trace hierarchy may appear flatter than for same-worker activities. The spans are still linked via headers but may not show a deep parent-child tree.
• TypeScript only — this integration is currently available for TypeScript. Python support is not yet available.