> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sazabi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Instrument your frontend

> Instrument a browser app with @sazabi/browser to capture errors, console output, network activity, and interaction events — or forward from a Sentry or PostHog SDK you already run.

You can send browser-side telemetry — errors, console output, network activity, and interaction events — to the same Sazabi intake your backend uses. For most apps, use the Sazabi browser SDK (`@sazabi/browser`): it captures a semantic event stream and injects W3C trace context into outgoing requests so browser events correlate with your backend logs. By the end of this guide you will have the SDK initialized and confirmed events arriving. Setup takes a few minutes plus a deploy.

## Ways to instrument the frontend

* **The Sazabi browser SDK (recommended).** First-party capture with backend correlation — the richest browser data, at the cost of adding one SDK to your app. The rest of this guide sets it up. Do not use it when you do not control the frontend build.
* **The Sentry SDK.** Already instrumenting the browser with Sentry? Point the Sentry SDK's DSN at your project's intake URL so Sentry envelopes arrive as records — you keep Sentry's event shape rather than the browser SDK's semantic stream. See [Sentry SDK source](https://docs.sazabi.com/catalogs/log-sources/send-to-an-endpoint/sentry-sdk.md).
* **The PostHog SDK.** Already running `posthog-js`? Repoint its API host at your project's intake URL so its analytics and session events arrive as records. See [PostHog SDK source](https://docs.sazabi.com/catalogs/log-sources/send-to-an-endpoint/posthog-sdk.md).

You can also run the browser SDK alongside an existing provider — everything lands in the same searchable set of log records.

## What the browser SDK captures

* **Errors and console** — uncaught errors and unhandled rejections, plus `console.error` and `console.warn` output mirrored as log events.
* **Network** — `fetch` and `XHR` requests, with a request-id response header attached as a join key against platform logs when present.
* **Interaction events** — clicks (including rage and dead clicks) and per-field input engagement episodes. The SDK records element selectors and a developer-facing element name, never values or keystrokes.
* **Navigation** — SPA route changes and full page loads.
* **Session identity** — a cross-tab session id and per-tab window id, plus a client-asserted distinct id you set with `identify()`.

## Set up the SDK

Install the package and call `init()` once, as early as possible in your app's startup, before the code you want to observe runs.

```bash title="Terminal" theme={"system"}
bun add @sazabi/browser
```

```ts title="observability.ts" theme={"system"}
import { init } from "@sazabi/browser";

init({
  intakeUrl: import.meta.env.VITE_SAZABI_INTAKE_URL,
  serviceName: "web-app",
});
```

Like every other log source, the SDK is configured with your intake URL alone — copy it from the Sazabi Browser SDK source under [**Settings > Log streams**](https://app.sazabi.com/settings/log-source-providers) (create the source there if your project has none, or with `sazabi log-sources create sazabi_browser_sdk --mode manual`). The URL embeds a write-only public key, which is why it is safe to ship in a browser bundle.

`init()` takes two required options — `intakeUrl` and `serviceName` — plus optional ones such as `serviceVersion`, `environment`, `consent`, `network`, `console`, and `input`, and exposes `identify()` / `reset()` for user identity. For every option, method signature, and the exact call semantics, see the **[Browser SDK reference](https://docs.sazabi.com/reference/browser-sdk.md)** — this guide does not repeat them.

## Correlate with backend logs

By default the SDK injects a W3C `traceparent` header into same-origin requests, and stamps the record trace id on the resulting network event. When your backend also sends logs to Sazabi with the same trace context, the agent can line up a browser action with the backend work it triggered.

Cross-origin injection is opt-in because the target must allowlist the header in CORS. Add matching URL patterns to `init()`'s `network.allowlist` option when you want it (for example `network: { allowlist: ["https://api.example.com"] }`); see [Browser SDK reference](https://docs.sazabi.com/reference/browser-sdk.md) for the full `network` option.

## Verify

Confirm real browser events reach your project.

1. Deploy or run the app with `init()` active, then open it in a browser.
2. Trigger an event the SDK captures — for example, click a button, then force a `console.error("sazabi browser sdk test")` from your app or the devtools console.
3. Filter to `service.name` equal to the `serviceName` you configured (`web-app` in the examples above). In a thread, ask the Sazabi agent for logs from that service, or run `sazabi logs ask "logs from web-app" --since 1h`.
4. You should see records with `app.event_type` values such as `click`, `pointer`, `error`, `navigation`, or `network`, and your test `log` record. Events batch and flush about every five seconds (and on page hide), so allow up to roughly a minute after the interaction.

If nothing appears, check that you pasted the complete intake URL from the source's setup screen and that the browser's network tab shows requests to your intake host returning 2xx.

## Troubleshooting

* **No events at all.** Confirm `init()` runs in the browser (not only during SSR), that all three required options are set, and that no `consent` gate is holding capture dormant.
* **Requests rejected.** Confirm `intakeUrl` is the complete intake URL copied from the source's setup screen — a partial or hand-built URL is rejected.
* **Backend correlation missing.** Ensure your backend forwards logs with the incoming trace context, and add cross-origin API hosts to `network.allowlist`.

## Further reading

> [card] [Browser SDK reference](https://docs.sazabi.com/reference/browser-sdk.md)
>
> Every init option and method.

> [card] [Send traces](https://docs.sazabi.com/guides/instrument/traces.md)
>
> How trace context correlates browser and backend.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.