SDK API reference

This page is a centralized, searchable cheat sheet for the browser SDK (@obsunified/analytics-sdk) and server-side SDKs (@obsunified/telemetry-sdk, Go, and Rust).

SDK initialization

Browser / client-side

Initialize the browser SDK to track page views, click interactions, and frontend exceptions. DOM session replay is opt-in: call startReplay() from useAnalytics() when you want it.

import { AnalyticsProvider, useAnalytics } from "@obsunified/analytics-sdk/react";

function Root() {
  return (
    <AnalyticsProvider
      collectorUrl="https://obs.my-app.com"
      apiKey="your-public-ingest-key"
      trackPageViews={true}
      captureErrors={true}
    >
      <App />
    </AnalyticsProvider>
  );
}

function ReplayButton() {
  const { startReplay } = useAnalytics();
  return <button onClick={() => startReplay()}>Record this session</button>;
}

declare function App(): null;

For non-React hosts:

import { installAutoCorrelate, UsageTracker } from "@obsunified/analytics-sdk";

const tracker = new UsageTracker({
  collectorUrl: "https://obs.my-app.com",
  apiKey: "your-public-ingest-key",
});

// Mode A: mints an interaction_id on click/submit/keydown and injects
// `x-obs-interaction` on outbound fetch/XHR. Returns a cleanup function.
const stopAutoCorrelate = installAutoCorrelate();

Initialize the standard telemetry exporter pipeline once at application startup (or per request in serverless runtimes). Passing environment, serviceVersion, commitSha, and configDigest stamps release lineage on every span for AutoSRE cohort attribution.

import { initObservability, recordFeatureFlag } from "@obsunified/telemetry-sdk";

initObservability({
  collectorUrl: "https://obs.my-app.com",
  apiKey: process.env.OBS_INGEST_KEY!,
  serviceName: "checkout-api",
  environment: process.env.OBS_ENVIRONMENT ?? "prod",
  serviceVersion: process.env.OBS_SERVICE_VERSION ?? "1.2.0",
  commitSha: process.env.OBS_COMMIT_SHA,
  configDigest: process.env.OBS_CONFIG_DIGEST,
  flushIntervalMs: 5000,
});

// Stamp feature-flag evaluations onto the active span and cohort context:
recordFeatureFlag("new_checkout_flow", true, { providerName: "launchdarkly" });

Click-to-trace context

Server-side HTTP ingress

Extract x-obs-interaction, bind it onto the active trace context, and flush buffered spans/logs/AI calls before serverless isolates terminate. The interaction id must be a 26-character uppercase Crockford-base32 ULID (for example 01JAQ8K3Z9X7M2N4P6Q8R0S1T3); the browser SDK generates valid ids, and the server SDK silently drops malformed x-obs-interaction values.

import {
  createRequestSpan,
  flushAICalls,
  flushLogs,
  flushSpans,
  runWithSpan,
  stampInteractionFromRequest,
} from "@obsunified/telemetry-sdk";

declare const req: { method: string; path: string; headers: Headers };

const span = createRequestSpan("my-service", `${req.method} ${req.path}`);
stampInteractionFromRequest(span, req);

try {
  await runWithSpan(span, async () => {
    // Child spans, logs, and feature flags created here inherit the interaction id.
  });
} finally {
  span.end();
  await Promise.all([flushSpans(), flushLogs(), flushAICalls()]);
}

Client-side async continuity

Auto-correlation handles synchronous handlers and shallow await chains. For debounces, timers, and state-machine ticks, capture and restore the interaction context.

import {
  currentInteractionId,
  withInteractionContext,
} from "@obsunified/analytics-sdk";

const clickId = currentInteractionId();

setTimeout(() => {
  withInteractionContext(clickId!, () => {
    fetch("/api/long-running-task");
  });
}, 300);

AI and LLM span tracking

OpenInference-style spans (recommended)

import { startLLMSpan, startToolSpan } from "@obsunified/telemetry-sdk";

declare function myLLMApiCall(): Promise<{ text: string; prompt_tokens: number; completion_tokens: number }>;
declare function searchDb(): Promise<unknown>;

const llmSpan = startLLMSpan({
  name: "user-query-completion",
  model: "gpt-4o",
  provider: "openai",
  input: "What is the capital of France?",
});

try {
  const result = await myLLMApiCall();
  llmSpan.setOutput(result.text);
  llmSpan.setTokens({
    prompt: result.prompt_tokens,
    completion: result.completion_tokens,
    total: result.prompt_tokens + result.completion_tokens,
  });
  llmSpan.setCost(0.0035);
} finally {
  llmSpan.end();
}

const toolSpan = startToolSpan({
  name: "pg-vector-search",
  parameters: { query: "paris coordinates" },
});

try {
  const data = await searchDb();
  toolSpan.setOutput(data);
} finally {
  toolSpan.end();
}

Agent Action Graph helpers

startAgentRun(opts, fn) is async: it opens the run, calls fn(run), and closes the run when fn settles (a thrown error marks the run failed and is rethrown). agentId and agentName are required. Use run.withAction(...) (or the standalone withAction) to scope an action; withAction takes ActionContextOptions (actionId, rootActionId, causedByActionId, interactionId, agentRunId, actorType, actorId). The autonomy level is set on the run via autonomyLevel.

import { startAgentRun } from "@obsunified/telemetry-sdk";

await startAgentRun(
  {
    agentId: "triage-agent",
    agentName: "Triage agent",
    goal: "Classify the incoming incident",
    autonomyLevel: "read_only",
  },
  async (run) => {
    await run.withAction({ actorType: "agent", actorId: "triage-agent" }, async () => {
      // Child spans, LLM calls, and tool calls inside this callback link to the action graph.
    });
    run.setOutcome("classified");
  },
);

Cloudflare Workers wrappers

Import these from @obsunified/telemetry-sdk/cloudflare to avoid pulling heavy ambient type dependencies into Node.js environments.

import { wrapD1, wrapFetch, wrapR2 } from "@obsunified/telemetry-sdk/cloudflare";

declare const env: {
  DATABASE: Parameters<typeof wrapD1>[0];
  STORAGE_BUCKET: Parameters<typeof wrapR2>[0];
};

const db = wrapD1(env.DATABASE);
const bucket = wrapR2(env.STORAGE_BUCKET, { bucketName: "blobs" });
const telemetryFetch = wrapFetch(globalThis.fetch);

Cross-language mapping

Concept / action	TypeScript SDK	Go SDK	Rust SDK
Exporter init	`initObservability(config)`	`obs.Init(ctx, config)`	`obs_unified::init(config)`
HTTP stamp	`stampInteractionFromRequest(span, req)`	`obs.StampInteraction(ctx, r)`	`obs_unified::stamp_interaction(span, req)`
LLM tracking span	`startLLMSpan(options)`	`obs.StartLLMSpan(ctx, name, opts)`	`obs_unified::start_llm_span(name, opts)`
Tool tracking span	`startToolSpan(options)`	`obs.StartToolSpan(ctx, name, opts)`	`obs_unified::start_tool_span(name, opts)`
Project id	`extraHeaders: { "x-project-id": id }`	`obs.SetProjectID(ctx, id)`	`obs_unified::set_project_id(id)`
Capture exception	`annotateErrorSpan(span, error)`	`obs.AnnotateError(ctx, span, err)`	`obs_unified::annotate_error(span, err)`