Skip to content

Configuration

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.

Updated View as Markdown

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

init options

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. 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)
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
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
redactQueryParams [] Query parameters to redact, added to the default list
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
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:

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. 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.

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.

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.

Navigation

Type to search…

↑↓ navigate↵ selectEsc close