TypeScript SDK API Reference

Both

Complete API reference for the Traccia TypeScript SDK.

This page documents all public functions, classes, and decorators in the @traccia/sdk package.

Initialization

Traccia.init()

Initializes the Traccia SDK with options and registers it globally. Must be awaited before creating traces.

typescript
static async init(config?: SDKConfig): Promise<ITracerProvider>

Parameters:

apiKey — API key for Traccia Platform (optional if set in env)
endpoint — OTLP endpoint (default: env or http://localhost:4318/v1/traces)
sampleRate — Ratio of traces to sample (default: 1.0)
maxQueueSize — Max number of buffered spans
enableConsoleExporter — Print spans to console for debugging
autoInstrument — Automatically instrument supported libraries like Axios/Express (default: false)
enableTokenCounting — Count tokens for LLM operations
enableCostTracking — Calculate LLM costs based on tokens
pricingOverride — Override pricing tables
redactPii — Mask sensitive patterns automatically before export

Returns:

Promise resolving to the ITracerProvider.

Example:

typescript
import { Traccia } from "@traccia/sdk";


// Minimal initialization
await Traccia.init();


// With configuration
await Traccia.init({
    apiKey: "tr_live_xxxxxxxxxxxx",
    sampleRate: 0.1,
    autoInstrument: true,
    enableTokenCounting: true
});

stopTracing()

Gracefully shutdown the TracerProvider, flush pending spans, and clean up resources.

typescript
import { stopTracing } from "@traccia/sdk";


// Flush and shutdown
await stopTracing();

Tracing API

@observe()

Decorator to automatically create spans around method execution. Note: Requires TypeScript experimentalDecorators or Babel.

typescript
function observe(options?: ObserveOptions): MethodDecorator

Parameters:

name — Override the span name (defaults to class.methodName)
attributes — Static attributes to add to the span
skipArgs — Array of argument names to omit from the span
skipResult — Boolean, if true the return value is not captured

See @observe() Documentation for detailed usage.

Traccia.getTracer()

Get a tracer instance to start spans manually.

typescript
static getTracer(name?: string, version?: string): ITracer
typescript
import { Traccia } from "@traccia/sdk";


const tracer = Traccia.getTracer("my-service");


await tracer.startActiveSpan("operation", async (span) => {
    span.setAttribute("custom", "value");
    await doWork();
    span.end();
});

Traccia.getCurrentSpan()

Retrieve the currently active span in the async context.

typescript
import { Traccia } from "@traccia/sdk";


const span = Traccia.getCurrentSpan();
span?.setAttribute("step", "validation");

spanScope()

Start a span with explicit lifecycle control. Unlike startActiveSpan, the span is not ended automatically — call scope.end() when the operation completes. Use for long-lived operations such as streaming chat turns.

typescript
import { spanScope } from "@traccia/sdk";


async function handleStream() {
    const turn = spanScope("chat.turn", { attributes: { "span.type": "llm" } });
    try {
        await turn.runAsync(async () => {
            for await (const chunk of streamTokens()) {
                // child spans created here attach to chat.turn
            }
        });
    } catch (error) {
        turn.end(error);
        throw error;
    }
    turn.end();
}

runWithSpan() / runWithSpanAsync()

Run a function with a specific span set as the active parent. Used internally by spanScope().run() and spanScope().runAsync().

typescript
import { Traccia, runWithSpan, runWithSpanAsync } from "@traccia/sdk";


const tracer = Traccia.getTracer();
const span = tracer.startSpan("background_job");


// Sync
runWithSpan(span, () => processBatch());


// Async
await runWithSpanAsync(span, async () => processBatchAsync());
span.end();

Runtime Configuration

Functions to attach metadata (Session ID, User ID, Tenant ID) directly to the active root context.

typescript
import { Traccia } from "@traccia/sdk";


// Attach context to the active span context globally
Traccia.setSessionId("session-123");
Traccia.setUserId("user-456");
Traccia.setTenantId("tenant-789");

Instrumentation & HTTP Middlewares

expressMiddleware

Express middleware to auto-create spans for HTTP routes and extract incoming trace contexts.

typescript
import express from "express";
import { expressMiddleware } from "@traccia/sdk";


const app = express();
app.use(expressMiddleware());

patchAxios / createTracedAxios

Instrument Axios to inject trace context into outgoing HTTP headers.

typescript
import axios from "axios";
import { patchAxios } from "@traccia/sdk";


// Patch the global axios instance
patchAxios();

patchOpenAI / patchAnthropic

Manual instrumentation for LLM clients (automatically enabled if autoInstrument: true).

Prompts

Fetch versioned prompts from the Traccia library at runtime, compile {{variables}}, and stamp the active span with prompt identity. Narrative guide: Prompts in the SDK. Platform workflow: Platform Prompts.

Requires Traccia platform

Runtime fetch uses your workspace API key against the prompt-runtime API. Tracing-only setups can still compile an explicit fallback body.

loadPrompt()

typescript
async function loadPrompt(options: {
  name: string;
  label?: string;       // default "production"
  version?: number;     // mutually exclusive with label
  fallback?: Record<string, unknown>;
  forceRefresh?: boolean;
}): Promise<LoadedPrompt>

LoadedPrompt

name, type, version, versionId, label
text / messages — uncompiled body by type
config — model hint from the version
isFallback, isStale
compile(vars) — substitutes {{var}}; missing required → CompileError
spanAttributes() / applySpanAttributes() — also applied on successful compile
typescript
import { init, loadPrompt, observe } from "@traccia/sdk";


await init({
  apiKey: "tr_…",
  endpoint: "https://api.traccia.ai/v2/traces",
  promptCacheTtlS: 60,
});


const reply = observe({ type: "llm" })(async (question: string) => {
  const prompt = await loadPrompt({
    name: "support-reply",
    label: "production",
    fallback: {
      type: "chat",
      messages: [
        { role: "system", content: "You are a helpful assistant." },
        { role: "user", content: "{{question}}" },
      ],
    },
  });
  const messages = prompt.compile({ question });
  return callLlm(messages);
});

prefetchPrompts()

Warm the client cache at startup. Optional jitter spreads multi-replica stampedes.

typescript
async function prefetchPrompts(
  names: string[],
  opts?: { label?: string; jitterMs?: number },
): Promise<LoadedPrompt[]>


await prefetchPrompts(["support-reply", "billing-triage"], { jitterMs: 500 });

Cache, SWR, and init options

  • Default TTL ~60s; key is name + label or version
  • After expiry: return last good and refresh in the background (isStale)
  • Fetch failure with cache → last good. Without cache → fallback or throw PromptFetchError
promptCacheTtlS / TRACCIA_PROMPT_CACHE_TTL_S

Span attributes

traccia.prompt.id
traccia.prompt.name
traccia.prompt.version
traccia.prompt.version_id
traccia.prompt.label
traccia.prompt.is_fallback

Redaction allowlists these keys. Full catalog: Span Events & Attributes.

Evaluate

Offline experiments from code. Narrative guide: Evaluate in the SDK. Also available as Traccia.evaluate.

Requires Traccia platform

Dataset fetch, persist, and platform LLM-as-judge / code scorers use your workspace API key.

evaluate()

typescript
async function evaluate(opts: EvaluateOptions): Promise<EvaluateResult>


type EvaluateOptions = {
  name: string;
  data: string | Array<Record<string, unknown>>;
  task: (input: any) => unknown | Promise<unknown>;
  scorers?: Array<string | ScorerFn>;
  prompt?: string;
  maxConcurrency?: number;  // default 10
  persist?: boolean;        // default true
  providerKeys?: Record<string, string>;
  apiKey?: string;
  promptApiBase?: string;
  progress?: boolean;       // default true
  onItemComplete?: (done: number, total: number, row: Record<string, unknown>) => void;
};


type ScorerFn = (args: {
  input: unknown;
  output: unknown;
  expected?: unknown;
  metadata?: unknown;
}) => unknown | Promise<unknown>;

Parameters

name — Experiment name (required)
data — Dataset name/UUID, or inline rows { input, expected, metadata }. expected_output is an alias of expected. Task always receives input only.
task — (input) => output. Async is awaited.
scorers — Builtin ids exact_match, contains, json_valid; platform names/ids; and/or functions.
prompt — Optional prompt name for version ids and cell label (otherwise Task).
maxConcurrency — Parallel workers (default 10, must be ≥ 1)
persist — Create an Experiment (default true). Inline + persist creates sdk-eval/<name>/<id>.
providerKeys — BYO keys for platform LLM-as-judge
progress — Print N/M to stderr (default true)
onItemComplete — (done, total, row)

EvaluateResult

name, rows, aggregates, errors
url, experimentId, datasetId
persistError — scoring finished but save failed
summary()
Row payloads remain snake_case (item_id, latency_ms, trace_id).

Throws EvaluateError for configuration and API failures. Per-item failures are captured on the row.

typescript
import { init, evaluate, loadPrompt, EvaluateError } from "@traccia/sdk";


await init({ apiKey: "tr_…" });
const prompt = await loadPrompt({ name: "support-reply", label: "production" });


try {
  const result = await evaluate({
    name: "support-reply-v3",
    data: "support-golden",
    task: async (inp) => callModel(prompt.compile(inp)),
    scorers: ["exact_match", "Helpfulness"],
    prompt: "support-reply",
    providerKeys: { gemini: process.env.GEMINI_API_KEY! },
  });
  console.log(result.summary());
  console.log(result.url);
} catch (e) {
  if (e instanceof EvaluateError) throw e;
  throw e;
}

Governance

govern() requires Traccia platform

observe() works with any OTLP backend. govern() calls the Traccia agent-status API before each run. Tracing-only users should use observe().

govern()

Decorator or function wrapper combining observability with runtime policy enforcement. Policy URLs default from your tracing endpoint.

typescript
import { Traccia, govern, AgentBlockedError } from "@traccia/sdk";


await Traccia.init({ apiKey: "...", endpoint: "https://api.traccia.ai/v2/traces" });


const runAgent = govern({
  agentId: "my-agent",
  failOpen: false,
  name: "run_agent",
})(async (prompt: string) => callLlm(prompt));

disclosure()

Record Art. 50 transparency evidence on the current span after your UI informed the user.

typescript
import { disclosure } from "@traccia/sdk";


disclosure({ channel: "ui", disclosedToUser: true });

governanceHooks

Register lifecycle hooks for pre/post execution and policy violations.

typescript
import { governanceHooks } from "@traccia/sdk";


governanceHooks.registerHooks({
  onBeforeExecute: (span) => { /* ... */ },
  onAfterExecute: (span) => { /* ... */ },
});

guardrailSpan()

Wrapper to track guardrail evaluations.

typescript
import { guardrailSpan } from "@traccia/sdk";


await guardrailSpan("PII_Check", async (span) => {
    // Evaluation logic
}, { action: "block" });

RedactionSpanProcessor

Automatically strips configured sensitive patterns from attributes. Registered automatically via init({ redactPii: true }).

redactString / redactAttributes

Utility functions for manual redaction.

typescript
import { redactString, redactAttributes } from "@traccia/sdk";


const safeText = redactString("Email me at user@example.com");
// "Email me at [REDACTED_EMAIL]"


const safeObj = redactAttributes({ phone: "555-0199" });

Span Methods

When you have a span object (from tracer.startActiveSpan or getCurrentSpan), you can use these methods:

span.setAttribute(key: string, value: any)
span.addEvent(name: string, attributes?: Record<string, any>)
span.recordException(exception: Error)
span.setStatus(status: SpanStatus, description?: string)
span.end()

Next Steps

Evaluate in the SDK

Run a task and scorers over a dataset from TypeScript

@observe() Decorator Guide

Detailed decorator documentation with examples

Configuration Reference

Complete config options reference

Advanced SDK Topics

Manual spans, sampling, and more

© 2026 Traccia.