@getsnare/sdk

Browser SDK for Snare. Captures uncaught exceptions and unhandled rejections, batches them, and delivers them to your Snare project. Product analytics, session replay and distributed tracing are in the same package, each behind its own flag.

There is a Node counterpart at @getsnare/sdk-node for backend processes, with the same public API and no window dependency.

Install

npm install @getsnare/sdk

Usage

import { init } from "@getsnare/sdk";

init({ projectId: "proj_abc123", apiKey: "snare_sdk_..." });

That is the whole required setup. From this point every uncaught exception and unhandled rejection is reported, with the console output leading up to it and a breadcrumb trail of navigations, clicks and network calls.

To report a handled error yourself:

import { captureException } from "@getsnare/sdk";

try {
  riskyCall();
} catch (error) {
  captureException(error, { tags: { checkout: "step-2" } });
}

Releases and sourcemaps

Set release to whatever string your deploy pipeline already produces, and upload your sourcemaps under that same string. Snare matches the two to turn a minified stack into your original source. Without a release, an event cannot be matched to a sourcemap.

init({
  projectId: "proj_abc123",
  apiKey: "snare_sdk_...",
  release: process.env.NEXT_PUBLIC_BUILD_SHA,
  environment: "production", // this is the default
});

Optional capture

Everything below is off unless you turn it on. Each one changes what leaves the browser, so none of them are defaults.

init({
  projectId: "proj_abc123",
  apiKey: "snare_sdk_...",
  autocapture: true,     // pageviews, clicks, inputs, web vitals, rage and dead clicks
  identity: true,        // a durable cross-session id, stored in localStorage
  sessionReplay: true,   // DOM recording, uploaded only when an exception fires
});

Session replay records into a rolling in-memory buffer and uploads only on an exception, never continuously. Password inputs are always masked. Add the snare-block, snare-ignore or snare-mask class to exclude anything else.

Breadcrumbs are the exception to the opt-in rule and default to on. They stay in a capped in-memory buffer and are sent only attached to an exception you are already receiving. Clicks record a selector, never text or input values; network crumbs record method, URL and status, never bodies. Pass breadcrumbs: false to turn them off.

Identifying users

import { identify, resetIdentity } from "@getsnare/sdk";

identify("user_123", { plan: "pro" });
resetIdentity(); // on sign out

identify() is a no-op unless identity: true was passed to init().

Tracing

With tracePropagationTargets set, outgoing requests to those origins carry a traceparent header, so a browser error and the backend request that caused it land on the same trace.

init({
  projectId: "proj_abc123",
  apiKey: "snare_sdk_...",
  tracePropagationTargets: ["https://api.example.com"],
});

List only origins you control. A cross-origin server that does not allow the header will fail the request outright.

API

| Export | Purpose | | --- | --- | | init(options) | Start capturing. Call once, as early as possible. | | captureException(error, options?) | Report a handled error. | | capture(eventName) | Record a custom product event. | | identify(distinctId, traits?) | Attach a durable identity. | | resetIdentity() | Forget it, on sign out. | | addManualBreadcrumb(crumb) | Add your own breadcrumb. | | stopSessionReplay() | Stop recording for this session. | | getCurrentTraceId() | The trace id, to log on your own side. |

License

MIT