Sazabi Browser SDK

Capture what happens in your users' browsers with @sazabi/browser, the official Sazabi browser SDK. It emits a session-scoped stream of navigation, interactions, console output, JavaScript errors, and network calls as OTLP log records, and injects W3C trace context into your API requests so a frontend symptom and its backend cause share a trace id.

About

@sazabi/browser is a zero-dependency browser library you install in your own web app. It lets you:

• Follow a single visitor's session across tabs, from first page load to error
• Catch uncaught exceptions and unhandled promise rejections with stack traces
• See rage clicks and dead clicks — the interactions that signal frustration
• Join frontend network calls to backend logs on a shared trace_id
• Use AI to investigate a browser session end to end

The SDK is configured with your intake URL alone. The URL embeds a write-only public key, which is why it is safe to ship in a browser bundle: it can write telemetry into your project and never read from it.

What gets captured

Every event carries session.id, session.window_id, session.distinct_id, web.page.url, and a web.event_type naming the kind of event:

By default the SDK also mirrors console.error and console.warn into the stream, leaving the original console behavior untouched.

Session replay recordings and Core Web Vitals are not captured.

Configuration

Privacy controls

• Input values are never captured — not even value lengths. An input event records which field was engaged, for how long, how many edits, and whether content was pasted; never keystrokes or contents. Request and response bodies are never captured either.
• Element names come from developer-authored sources only — aria-label, <label>, placeholder, and button captions — and only for interactive elements. Clicks on plain containers, where user content lives, record selectors only.
• Mask or rename any element. Add data-sazabi-mask to suppress text capture for an element's whole subtree, or data-sazabi-name to set its reported name explicitly.
• Consent gating. Pass consent: () => boolean | Promise<boolean> and the SDK installs no listeners, no patches, and makes no network calls until it resolves true. identify() calls made while consent is pending are buffered and applied when capture starts.
• Client-asserted identity. session.distinct_id is whatever the browser claims. Treat it as a claim, not as proof of identity — the same is true of every field on these events, since the intake URL is extractable from any page that ships it.
• Reversible by construction. Every patch is transparent, idempotent, and reversible; SDK failures are invisible to your app, and shutdown() restores the original functions.

Prerequisites

• A web app you can add an npm dependency to and redeploy.
• A Sazabi project.

Set up in the dashboard

npm install @sazabi/browser

// Import first, because a module that runs earlier can capture the native
// fetch/XHR/history references before the SDK wraps them.
import "@sazabi/browser/register";

import { init } from "@sazabi/browser";

init({
  intakeUrl: "<your intake URL>",
  serviceName: "my-web-app",
  serviceVersion: process.env.GIT_SHA,
  environment: "production",
});

init({
  // …
  network: {
    allowlist: ["https://api.example.com"],
  },
});

import { addEvent, identify, log, reset } from "@sazabi/browser";

identify("user_123", { plan: "pro" }); // on sign-in — internal id, not an email
addEvent("checkout_started", { cartValue: 42 }); // custom mark
log("ERROR", "checkout failed", { orderId }); // app log line
reset(); // on sign-out

Set up with the CLI

You can also register the Sazabi Browser SDK log source with the Sazabi CLI (installed and authenticated — see CLI reference).

Registering the source mints the same intake URL the dashboard shows above — the only value the SDK needs:

sazabi log-sources create sazabi_browser_sdk --mode connectionless

Verify

1. Use your app: load it and click through a few pages. The SDK flushes every 5 seconds, and again when the tab is hidden or closed, so events land within about 10 seconds.

2. Check the browser: in the network tab, filter for intake — POSTs to /v1/logs should return 200.

3. Confirm arrival: open the Intake page in the Sazabi dashboard and confirm records from the Sazabi Browser SDK source appear, or ask the agent in a thread: "Show me recent browser sessions."

Troubleshooting

No requests to intake at all — Confirm init() runs before your framework mounts. Check the browser console for the [@sazabi/browser] configuration warning, which means intakeUrl or serviceName was empty. If you pass a consent callback, confirm it resolves true.

Requests return 401 — The intake URL's embedded key was deactivated, or the URL belongs to another project. Check the log stream in Settings > Log streams and copy the current intake URL.

Some requests are missing from the stream — Another library captured native fetch before the SDK did. Move import "@sazabi/browser/register"; to the true first line of your entry module. The SDK falls back to resource-timing data for these requests and emits a one-time instrumentation-gap diagnostic per origin.

Network events have no trace id — traceparent is injected only into same-origin requests and origins you added to network.allowlist. For cross-origin APIs, confirm the response allows the traceparent request header in CORS.

Stream shows Inactive — Not an error: it means no telemetry arrived in the last hour. If you expected telemetry, check that the build calling init() has deployed and someone has loaded the app since, that a consent gate is not resolving false, and that build-time configuration did not inline an empty string for intakeUrl (init() warns once in the console and disables itself).

Log stream states

Each log stream for this source has a status visible in Settings > Log streams, derived from recent telemetry activity on the log stream's key:

Further reading