---
title: "Configuration"
description: "The browser SDK's init options and functions, tracing requests to your APIs, naming views, beforeSend recipes, and what the SDK does when something goes wrong."
---

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

# Configuration

The framework packages take the same options as `init`: `<EzghRum>`'s props in Next.js,
`createEzghRum(…)` in Vue and `provideEzghRum(…)` in Angular.

## `init` options

```ts
import { init } from "@ezghcloud/rum";

init({
  token: "ezgh_ct_…",
  release: "2026.10.13-4f2a9c1",
  allowedTracingUrls: [/^https:\/\/api\.example\.com\//],
});
```

| Option | Default | Meaning |
| --- | --- | --- |
| `token` | Required | The [client token](/observability/rum/client-tokens). Without a valid one, the SDK stays off and says so in the console |
| `release` | None | Your build's version, stored as `service.version`. Set it: it matches errors to your source maps' release, and without it, any new error on a resolved issue reopens it, however old the page that sent it ([regressions](/observability/rum/issues#states)) |
| `endpoint` | `https://obs-browser.ezghcloud.com` | Where data is sent |
| `tunnel` | None | A first-party URL to send through instead, such as `/_ezgh`; see [Tunnel](/observability/rum/tunnel) |
| `sessionSampleRate` | `100` | The percentage of sessions recorded, 0 to 100, decided once per session |
| `allowedTracingUrls` | `[]` | Strings (URL prefixes), regular expressions or functions `(url) => boolean`. Matching requests get `traceparent` (and `tracestate` when the page has one) |
| `trackResources` | `false` | A span for each resource the page loads (scripts, styles, images), under `documentLoad` |
| `trackLongTasks` | `true` | Long tasks are counted per view |
| `captureConsole` | `["error", "warn"]` | The console levels kept as breadcrumbs on errors (`error`, `warn`, `info`, `log`, `debug`). They're never sent as logs |
| `trackingConsent` | `"granted"` | With `"pending"`, nothing is collected, stored or sent until `consent.grant()`; see [Privacy and consent](/observability/rum/privacy#consent) |
| `redactQueryParams` | `[]` | Query parameters to redact, added to the [default list](/observability/rum/privacy#urls) |
| `beforeSend` | None | `(event) => event \| null`: change a record's attributes, or drop it with `null` |

Call `init` once, as early as you can. A second call does nothing.

## Functions

| Function | What it does |
| --- | --- |
| `setUser({ id })` | Adds `user.id` to later records, up to 256 characters. Issues count users by it |
| `clearUser()` | Stops adding `user.id` |
| `setAttributes({ … })` | Adds attributes to later records: at most 32. Attributes the SDK sets itself can't be replaced |
| `addAction(name, attributes?)` | Records an action: an `interaction` span named `name`, ended when the requests it starts are done, and a breadcrumb |
| `captureException(error, { fingerprint?, attrs? })` | Reports an error you caught. `fingerprint` groups it into the issue of your choice; see [How errors are grouped](/observability/rum/issues#how-errors-are-grouped) |
| `startView(name)` | Starts a view named `name`, for pages the router doesn't announce |
| `consent.grant()`, `consent.revoke()` | Starts the SDK after `trackingConsent: "pending"`; stops it and clears the session |
| `getSessionId()` | The current session's ID, to link support tickets or your own logs to a session timeline |
| `flush()` | Sends what's queued now. Returns a promise |

None of them throws, and all do nothing before `init`, after `consent.revoke()`, or once the SDK
has turned itself off.

## Tracing to your APIs

Requests whose URL matches `allowedTracingUrls` carry a W3C `traceparent` header (and
`tracestate`, when the page has a `<meta name="tracestate">`), so your backend's spans join the browser's trace:

```ts
init({
  token: "ezgh_ct_…",
  release: import.meta.env.VITE_RELEASE,
  allowedTracingUrls: ["https://api.example.com/", /^https:\/\/[a-z]+\.example\.com\/graphql$/],
});
```

- Your API's CORS must allow the headers: `Access-Control-Allow-Headers: traceparent, tracestate`.
  Otherwise the browser refuses the request. Only list URLs whose CORS allows them.
- Your backend's own OpenTelemetry SDK continues the trace, and sends its spans as it does today;
  see [Traces](/observability/traces). Send both to the same environment, and the trace shows
  the click, the browser's request and every backend span below it.
- The page load joins your server's trace when the server renders
  `<meta name="traceparent" content="00-…">` in the page, as Next.js does with
  [`withEzghRum`](/observability/rum/quick-start).

## Name views

A view is named by its route template, so `/users/8412` and `/users/77` are one view,
`/users/:id`:

- The React, Next.js, Vue and Angular packages use your router's templates.
- Otherwise, the SDK replaces path segments that are all digits, UUIDs or hex of 8 characters or
  more with `:id`.
- `startView("/checkout/:step")` names a view yourself.

Names are at most 128 characters. Each view is in the `ezgh.rum.view.name` attribute of every
record, and in the generated metrics' `view_name` label.

## `beforeSend` recipes

`beforeSend` gets each span and log record before it's queued: `{ kind, name, attributes }`, where
`kind` is `"span"` or `"log"`, and `name` is the span's name or the log's `event.name`
(`exception`, `ezgh.rum.view`). Change `attributes` and return the event, or return `null` to
drop it. If the function throws, the record is dropped.

```ts
init({
  token: "ezgh_ct_…",
  release: import.meta.env.VITE_RELEASE,
  beforeSend(event) {
    // Drop errors thrown by browser extensions.
    const stack = String(event.attributes["exception.stacktrace"] ?? "");
    if (event.name === "exception" && /(chrome|moz|safari-web)-extension:\/\//.test(stack)) return null;
    // Remove an account number from paths: /accounts/123456/settings → /accounts/:account/settings
    for (const key of ["url.path", "url.full"]) {
      const value = event.attributes[key];
      if (typeof value === "string") event.attributes[key] = value.replace(/\/accounts\/[^/?]+/, "/accounts/:account");
    }
    return event;
  },
});
```

## When something goes wrong

The SDK never throws into your page and never retries forever:

- Every hook it installs is guarded. After 10 internal errors on a page, it turns itself off for
  that page.
- `401` or `403` (an unknown or deleted token, or an origin the token doesn't allow) stops
  sending for the page. Sent directly to EZGH, these answers have no CORS headers, so the browser
  reports a network error; after 5 network failures in a row with nothing delivered, the SDK
  stops sending for the page too.
- `429` waits for `Retry-After`. When the token's daily budget is spent, `Retry-After` is the next
  UTC midnight, and the SDK stops sending from that browser until then, in every tab.
- Offline or while waiting, it keeps up to 1 MB of records in memory, dropping the oldest first.
  Nothing is written to disk.
- Data is sent every 10 seconds or 50 records, gzipped where the browser can, and when the page
  is hidden, with `sendBeacon` or a `keepalive` request. EZGH never reads cookies from these
  requests.

Browser support: Chrome and Edge 96 or later, Firefox 100 or later, Safari 15.4 or later.

Source: https://docs.ezghcloud.com/observability/rum/configuration/index.mdx
