@tracelanedev/sdk

Instrumentation for TypeScript AI agents, built on the OpenTelemetry Node SDK. Spans are emitted via OTLP to your Tracelane ingest endpoint.

Install

npm install @tracelanedev/sdk
# or
pnpm add @tracelanedev/sdk

Fastest path — route through the gateway (no SDK)

For Tracelane Cloud, the shortest path to your first trace needs no SDK at all: point your existing client's base URL at the gateway and use your tlane_… key. The gateway routes the call and captures the trace.

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://gateway.tracelane.dev/v1",
  apiKey: process.env.TRACELANE_API_KEY!, // tlane_… from app.tracelane.dev
});

await client.chat.completions.create({
  model: "claude-sonnet-4-6",
  messages: [{ role: "user", content: "Hello" }],
});
// → Trace visible at https://app.tracelane.dev/traces within ~1 second

Use this SDK when you want to export OTLP spans to an endpoint you run — a self-hosted Tracelane ingest, or your own OTLP collector (Jaeger, Tempo, …).

SDK quick start (OTLP export)

Two steps: init() once at startup, then wrap each client with its instrument* function. There is no zero-config magic in v1 — wrapping is explicit, so what's traced is exactly what you opted in.

import { init, instrumentAnthropic } from "@tracelanedev/sdk";
import Anthropic from "@anthropic-ai/sdk";

// 1. Initialise once. endpoint + apiKey are REQUIRED (no env-var auto-read).
//    `endpoint` is an OTLP receiver YOU can reach — your collector, or a
//    self-hosted Tracelane ingest. (Tracelane Cloud's ingest is not a public
//    OTLP endpoint — use the gateway path above for Cloud.)
init({
  endpoint: process.env.OTEL_EXPORTER_OTLP_ENDPOINT ?? "http://localhost:4318",
  apiKey: process.env.TRACELANE_API_KEY!,
  serviceName: "my-agent",
});

// 2. Wrap the client — instrumentAnthropic patches it in place.
const client = new Anthropic();
instrumentAnthropic(client);

// 3. Use it normally — every call now emits a span.
await client.messages.create({
  model: "claude-sonnet-4-6",
  messages: [{ role: "user", content: "Hello" }],
  max_tokens: 128,
});

init() options

| Field | Required | Description | |---|---|---| | endpoint | yes | OTLP HTTP endpoint you can reach, e.g. http://localhost:4318 or a self-hosted ingest. Spans POST to ${endpoint}/v1/traces. | | apiKey | yes | Your tlane_… key. Sent as the x-tracelane-api-key header. | | serviceName | no | Resource service.name (default unknown-service). | | sampleRate | no | 0.0–1.0 (default 1.0 — full trace; the tail sampler decides). |

Call shutdown() on exit to flush pending spans (an automatic flush is also registered on beforeExit).

Streaming (v1 limitation)

Streamed calls (stream: true) pass through untouched and still produce a span with model + latency, marked tracelane.streaming = true. Token usage and finish reason are not captured for streamed responses yet — that lands in v1.1. A once-per-process runtime warning says exactly this.

Instrumented libraries

Each library has its own instrument*(client) function — import it from the package root or the matching subpath. Call it once, after constructing the client (or, for module-level libraries, after import).

| Import | Wrap with | What is traced | |---|---|---| | @anthropic-ai/sdk | instrumentAnthropic(client) | messages.create, streaming, tool use | | openai | instrumentOpenAI(client) | chat.completions, embeddings, Responses | | @openai/agents | instrumentOpenAIAgents(...) | agent steps, tool calls, handoffs | | langchain | instrumentLangGraph(graph) | chains, agents, tool calls | | @modelcontextprotocol/sdk | instrumentMCP(...) | tool_call, tool_result | | Vercel AI SDK | instrumentVercelAI(...) | generateText, streamText, generateObject |

Full list (one export per library): instrumentAnthropic, instrumentOpenAI, instrumentOpenAIAsync, instrumentLiteLLM, instrumentOpenRouter, instrumentLangGraph, instrumentOpenAIAgents, instrumentVercelAI, instrumentMCP, instrumentClaudeCode, instrumentCursor, instrumentPinecone, instrumentQdrant, instrumentComposio, instrumentBrowserbase, instrumentE2B, instrumentMem0, instrumentLetta, instrumentFirecrawl.

Zero-config autoInstrument() is not in v1 — calling it throws with a pointer to this explicit API. Auto-detection lands in v1.1.

Next.js App Router

Initialise in instrumentation.ts (runs once per server process):

// instrumentation.ts
export async function register() {
  if (process.env.NEXT_RUNTIME === "nodejs") {
    const { init } = await import("@tracelanedev/sdk");
    init({
      endpoint: "http://localhost:4318", // an OTLP receiver you run
      apiKey: process.env.TRACELANE_API_KEY!,
      serviceName: "my-nextjs-app",
    });
  }
}

Manual spans

The SDK sets up a standard OpenTelemetry tracer provider, so custom spans use @opentelemetry/api directly — no Tracelane-specific wrapper:

import { trace } from "@opentelemetry/api";

const tracer = trace.getTracer("my-agent");
const hits = await tracer.startActiveSpan("retrieval", async (span) => {
  span.setAttribute("retrieval.top_k", 10);
  const results = await vectorStore.search(query, { topK: 10 });
  span.end();
  return results;
});

Design invariants

• Telemetry goes to your configured endpoint only — the SDK never calls home.
• Instrumentation is additive — instrument* patches a client in place and does not modify the OpenAI/Anthropic module exports.
• Redaction — set TRACELANE_TRACE_CONTENT=false to redact prompt and completion text from captured traces (honored on the gateway path).
• Zero runtime dependencies beyond the OpenTelemetry SDK.

Documentation

Full docs at docs.tracelane.dev/sdk-typescript.

Stack

TypeScript 5.5+ strict, Biome (lint + format), Vitest.

License

Apache 2.0 — see LICENSE.