spinlap-radar

Radar SDK (JS/TS) — spinlap-radar

Non-blocking tracing for AI agents on Node.js (18+). Mirrors the Python SDK's behaviour and guarantees. Zero runtime dependencies.

Install

npm install spinlap-radar

Usage

import * as radar from "spinlap-radar";

// Once, at startup:
radar.init({
  apiKey: "rdr_…",                       // from POST /v1/projects
  projectName: "my-agent",
  baseUrl: "https://your-radar-api…",    // your backend
  redactFields: ["input.user.email"],    // dot-notation, redacted client-side
});

// Wrap an agent run (sync or async). Return value = trace output; a throw marks it errored.
const answer = await radar.trace(
  "support_bot_run",
  async () => {
    radar.logStep({ name: "call_llm", input: question, output: reply, tokens: 340, cost: 0.0021 });
    return reply;
  },
  { tags: { customer_id: "123" } },
);

Manual control (no wrapper):

import { Trace } from "spinlap-radar";
const t = new Trace("job", { env: "prod" }).start();
t.logStep({ name: "step_1", tokens: 10, cost: 0.001 });
t.setOutput({ done: true });
t.finish("success");

Guarantees (same as the Python SDK)

• Non-blocking — traces are enqueued instantly; delivery happens on a timer. Network latency never affects your function.
• Failure-isolated — delivery errors are logged via console.warn ([radar] …) and the batch dropped. The SDK never throws into your app.
• Batched — flushed every flushIntervalSeconds (default 2s) or when maxBatchSize (default 20) traces are queued.
• Context-propagating — logStep() attaches to the active trace via Node's AsyncLocalStorage, across await; nested traces link by parentTraceId.
• Redaction — redactFields (dot-notation) → [REDACTED] before sending.
• Bounded — inputs/outputs over maxPayloadBytes (default 50KB) are truncated.

Call radar.flush() to send now, or await radar.shutdown() on graceful exit (a best-effort flush is also attempted on beforeExit).

Build

npm run build      # tsc → dist/ (CommonJS + .d.ts)