Browser SDK

Installation

npm install @obtrace/sdk-browser

Built on OpenTelemetry

The Browser SDK uses @opentelemetry/sdk-trace-web under the hood to instrument fetch, XMLHttpRequest, document loads, and user interactions. This gives you distributed tracing from the browser to your backend services with W3C trace context propagation.

Session replay, Web Vitals collection, and console capture remain obtrace-specific features layered on top of the OTel foundation.

Zero-Config Setup (Recommended)

One import. No configuration object. The SDK reads your environment variables automatically.

import '@obtrace/sdk-browser/auto'

Set these environment variables (Vite example shown, but NEXT_PUBLIC_ and REACT_APP_ prefixes also work):

Obtrace treats the project app name as the canonical identity. Example: if the project app is core and it has alias web, browser traffic may send serviceName: "web", but ingest normalizes it to core. Names outside the configured app name and aliases are rejected.

The /auto entry point does everything: initializes the SDK, patches window.fetch globally so all HTTP calls are instrumented, captures errors, console output, Web Vitals, and session replay.

To access the SDK instance later:

import { getObtrace } from '@obtrace/sdk-browser/auto'
 
const ob = getObtrace()
ob?.log("info", "checkout.started")

React Setup

For React apps that want typed helper functions:

import { obtrace } from '@obtrace/sdk-browser/react'
 
export const ob = obtrace({
  apiKey: import.meta.env.VITE_OBTRACE_API_KEY,
  serviceName: "core",
})

The React wrapper also exports convenience functions that work without holding a reference to the SDK instance:

import { obtraceLog, obtraceMetric, obtraceError } from '@obtrace/sdk-browser/react'
 
obtraceLog("info", "page.loaded")
obtraceMetric("search.results", 42)
obtraceError(new Error("something broke"))

The obtrace() call also patches window.fetch globally.

Manual Setup

For full control over configuration:

import { initBrowserSDK } from "@obtrace/sdk-browser/browser";
 
export const ob = initBrowserSDK({
  apiKey: import.meta.env.VITE_OBTRACE_API_KEY,
  serviceName: "core",
});

Import ob wherever you need it. Initialize once at app startup, before any user interaction.

initBrowserSDK returns an object with these methods:

What Gets Captured Automatically

After calling initBrowserSDK, the SDK enables OpenTelemetry browser instrumentations and installs obtrace-specific hooks with zero additional code from you:

Web Vitals

Measured via PerformanceObserver and sent as metrics:

Error Capture

• window.onerror events are logged at error level with filename, line, and column
• Unhandled promise rejections are logged at error level with the rejection reason

Console Capture

All console.debug, console.info, console.warn, and console.error calls are intercepted and forwarded as logs at the matching level. The original console output still works normally.

Session Replay

Enabled by default. Uses rrweb to record DOM mutations, mouse movements, scrolls, and input events. Recordings are chunked and sent to /ingest/replay/chunk.

Privacy defaults:

• All inputs are masked
• Password, email, phone, token, and credit card fields are redacted
• Elements with the CSS class ob-block are excluded from recording
• Text in elements with the CSS class ob-mask is masked

Navigation Tracking

Route changes via pushState, replaceState, popstate, and hashchange are captured as replay events with the current URL and page title.

Page Lifecycle

The SDK automatically flushes telemetry and replay data when:

• The page becomes hidden (visibilitychange)
• The page is about to unload (beforeunload, uses sendBeacon for reliability)

Adding Custom Telemetry

Logs

log(level, message, context?) sends a structured log. Levels: debug, info, warn, error, fatal. The current sessionId is automatically attached.

import { ob } from "../obtrace";
 
function handleSubmit(cart: Cart) {
  ob.log("info", "checkout.started", {
    attrs: { item_count: cart.items.length, total: cart.total },
  });
}

Errors

captureException(error, context?) extracts the error name and message and logs it at error level. Session and trace context are attached automatically.

try {
  await submitOrder(cart);
} catch (err) {
  ob.captureException(err, {
    attrs: { step: "payment", cart_id: cart.id },
  });
}

Metrics

metric(name, value, unit?, context?) records a numeric value. Use it for performance and business measurements.

const start = performance.now();
await loadProductCatalog();
ob.metric("catalog.load_ms", performance.now() - start, "ms");
 
ob.metric("search.results_count", results.length);

Custom Replay Events

captureReplayEvent(type, payload) attaches a custom event to the session replay timeline. Use it to mark significant user actions.

ob.captureReplayEvent("user_action", {
  action: "added_to_cart",
  product_id: product.id,
  price: product.price,
});

Context Object

Every manual call accepts an optional context object:

interface SDKContext {
  traceId?: string;
  spanId?: string;
  traceState?: string;
  baggage?: string;
  sessionId?: string;
  routeTemplate?: string;
  endpoint?: string;
  method?: string;
  statusCode?: number;
  attrs?: Record<string, string | number | boolean>;
}

The sessionId is auto-injected by the browser SDK. The attrs field is for arbitrary key-value pairs.

HTTP Instrumentation

If you use the /auto or /react entry point, window.fetch is patched globally. Every fetch() call in your app is automatically instrumented with no extra code.

If you use the manual initBrowserSDK entry point, fetch is also patched by default (controlled by the instrumentGlobalFetch config option). You can also get an instrumented fetch wrapper explicitly:

import { ob } from "./obtrace";
 
const fetcher = ob.instrumentFetch();

Every instrumented fetch call produces:

• A span named browser.fetch POST (or whatever the method is) with http.method, http.url, http.status_code, http.duration_ms, and replay_id
• A log entry with the request outcome
• A network replay event (visible in the session replay timeline)
• A recipe step for request replay (used by Obtrace's replay analysis)
• Automatic W3C traceparent header injection for backend trace correlation

Failed requests also produce an error log and a network_error replay event.

Configuration Reference

Validation Checklist

After deploying, verify these:

• Open the Obtrace UI and confirm logs appear under the canonical project app for this frontend
• Check that Web Vitals metrics (web_vital_lcp_ms, etc.) appear after a page load
• Trigger a JavaScript error in a test environment -- an error log should appear with file and line info
• Use the instrumented fetch to make an API call -- a span and network replay event should appear
• Navigate between pages -- replay events with the new URL should appear
• Open the session replay viewer and confirm the recording plays back correctly
• Verify your ingest endpoint allows CORS from your frontend origin
• Check that sensitive inputs (passwords, emails) are masked in the replay

CORS

Your Obtrace ingest endpoint must accept requests from your frontend origin. The SDK sends to these endpoints:

• POST /otlp/v1/logs
• POST /otlp/v1/traces
• POST /otlp/v1/metrics
• POST /ingest/replay/chunk
• POST /ingest/replay/recipes

If you see failed requests in the browser console, check that your ingest-edge service has the correct CORS configuration for your domain.

Privacy Controls

To exclude a DOM element from session replay, add the ob-block class:

<div class="ob-block">
  This content will not appear in replays.
</div>

To mask text content while preserving layout:

<p class="ob-mask">
  This text will be replaced with asterisks in replays.
</p>

Sensitive input fields (password, email, phone, token, credit card) are automatically redacted regardless of CSS classes.