Initialization

Initialize the Traceway SDK once at application startup, before capturing any events.

Basic Initialization

import { init } from "@tracewayapp/frontend";
 
init("your-token@https://traceway.example.com/api/report");

With Options

import { init } from "@tracewayapp/frontend";
 
init("your-token@https://traceway.example.com/api/report", {
  debug: true,
  version: "1.2.3",
  debounceMs: 2000,
});

Options Reference

Auto-Capture Behavior

By default, the SDK does not automatically capture unhandled errors. You need to either:

1. Use a framework integration (React, Vue, Svelte) that provides automatic capture
2. Set up your own global error handler:

import { init, captureException } from "@tracewayapp/frontend";
 
init("your-token@https://traceway.example.com/api/report");
 
// Capture unhandled errors
window.addEventListener("error", (event) => {
  captureException(event.error);
});
 
// Capture unhandled promise rejections
window.addEventListener("unhandledrejection", (event) => {
  captureException(event.reason);
});

Error Filtering

By default, the SDK ignores common non-actionable errors: 4xx HTTP errors, network errors, and timeouts. These are typically expected application behavior (e.g., form validation returning 422, auth redirects from 401) rather than bugs that need tracking.

Default Behavior

The following patterns are ignored out of the box:

• "Failed to fetch" (Chrome), "Load failed" (Safari), "NetworkError when attempting to fetch resource" (Firefox), "Network Error" (Axios)
• "The operation was aborted" (AbortController), any message matching /timeout/i
• Axios 4xx errors matching /status code 4\d{2}/
• jQuery/custom 4xx errors matching /failed: 4\d{2}/

Capture All Errors

To opt out of default filtering and capture everything:

init("your-token@https://traceway.example.com/api/report", {
  ignoreErrors: [],
});

Custom Patterns

Pass your own patterns to replace the defaults. Strings match via includes(), RegExps match via .test():

init("your-token@https://traceway.example.com/api/report", {
  ignoreErrors: [
    "ResizeObserver loop",
    /status code 5\d{2}/,
  ],
});

Extending Default Patterns

Import DEFAULT_IGNORE_PATTERNS to add your own patterns on top of the defaults:

import { init, DEFAULT_IGNORE_PATTERNS } from "@tracewayapp/frontend";
 
init("your-token@https://traceway.example.com/api/report", {
  ignoreErrors: [
    ...DEFAULT_IGNORE_PATTERNS,
    "ResizeObserver loop",
  ],
});

beforeCapture Callback

For fine-grained control, use the beforeCapture callback. It receives the full exception object (including any attributes) and should return false to suppress:

init("your-token@https://traceway.example.com/api/report", {
  ignoreErrors: [],
  beforeCapture: (exception) => {
    // Suppress 401 errors based on attributes (e.g., from jQuery AJAX capture)
    if (exception.attributes?.status === "401") return false;
 
    // Suppress errors from third-party scripts
    if (exception.stackTrace.includes("third-party.js")) return false;
 
    return true;
  },
});

beforeCapture is checked after ignoreErrors — if a pattern already suppresses the error, the callback is not called. If the callback throws, the error is captured normally (safe default).

Debug Mode

When debug: true is set, the SDK logs all captured events to the browser console. This is useful during development to verify events are being captured correctly.

init("your-token@https://traceway.example.com/api/report", {
  debug: process.env.NODE_ENV === "development",
});

Custom Attributes (Global Scope)

The SDK auto-collects browser context (url, userAgent, viewport, etc.) on every session and exception. To attach app-level identifiers — userId, tenant, feature flags — call the imperative scope API once and they ride along every subsequent event:

import {
  setAttribute,
  setAttributes,
  removeAttribute,
  clearAttributes,
} from "@tracewayapp/frontend";
 
setAttribute("userId", "u_42");
setAttributes({ tenant: "acme", plan: "pro" });
 
// On logout / tenant switch:
clearAttributes();

Layering on each event: defaults < global scope < per-call. captureExceptionWithAttributes(err, { … }) still wins over global keys for the specific exception.

If recordAllSessions: true is on, calling setAttribute* mid-session also pushes a refresh upsert so the live session row picks up the new attributes immediately rather than waiting for close. See Sessions for the full attribute model.

Multiple Environments

For different environments, use separate project tokens:

const connectionString = process.env.NODE_ENV === "production"
  ? "prod-token@https://traceway.example.com/api/report"
  : "dev-token@https://traceway.example.com/api/report";
 
init(connectionString);