Sentry Browser Sdk

All Skills > SDK Setup > Browser SDK

Sentry Browser SDK

Opinionated wizard that scans your project and guides you through complete Sentry setup for browser JavaScript — vanilla JS, jQuery, static sites, WordPress, and any JS project without a framework-specific SDK.

Invoke This Skill When

• User asks to "add Sentry to a website" or set up Sentry for plain JavaScript
• User wants to install @sentry/browser or configure the Loader Script
• User has a WordPress, Shopify, Squarespace, or static HTML site
• User wants error monitoring, tracing, session replay, or logging without a framework
• No framework-specific SDK applies

Note: SDK versions and APIs below reflect @sentry/browser ≥10.0.0.

Always verify against docs.sentry.io/platforms/javascript/ before implementing.

---

Phase 1: Detect

CRITICAL — Check for frameworks first. Framework-specific SDKs provide significantly better coverage and must be recommended before proceeding with @sentry/browser.

Step 1A: Framework Detection (Redirect If Found)

# Check for React
cat package.json 2>/dev/null | grep -E '"react"'

# Check for Next.js
cat package.json 2>/dev/null | grep '"next"'

# Check for Vue
cat package.json 2>/dev/null | grep '"vue"'

# Check for Angular
cat package.json 2>/dev/null | grep '"@angular/core"'

# Check for Svelte / SvelteKit
cat package.json 2>/dev/null | grep -E '"svelte"|"@sveltejs/kit"'

# Check for Remix
cat package.json 2>/dev/null | grep -E '"@remix-run/react"|"@remix-run/node"'

# Check for Nuxt
cat package.json 2>/dev/null | grep '"nuxt"'

# Check for Astro
cat package.json 2>/dev/null | grep '"astro"'

# Check for Ember
cat package.json 2>/dev/null | grep '"ember-source"'

# Check for Node.js server frameworks (wrong SDK entirely)
cat package.json 2>/dev/null | grep -E '"express"|"fastify"|"@nestjs/core"|"koa"'

If a framework is detected, stop and redirect:

Why redirect matters: Framework SDKs add router-aware transactions, error boundaries, component tracking, and often SSR coverage. Using @sentry/browser directly in a React or Next.js app loses all of that.

Only continue with @sentry/browser if no framework is detected.

Step 1B: Installation Method Detection

# Check if there's a package.json at all (bundler environment)
ls package.json 2>/dev/null

# Check package manager
ls package-lock.json yarn.lock pnpm-lock.yaml bun.lockb 2>/dev/null

# Check build tool
ls vite.config.ts vite.config.js webpack.config.js rollup.config.js esbuild.config.js 2>/dev/null
cat package.json 2>/dev/null | grep -E '"vite"|"webpack"|"rollup"|"esbuild"'

# Check for CMS or static site indicators
ls wp-config.php wp-content/ 2>/dev/null   # WordPress
ls _config.yml _config.yaml 2>/dev/null    # Jekyll
ls config.toml 2>/dev/null                 # Hugo
ls .eleventy.js 2>/dev/null                # Eleventy

# Check for existing Sentry
cat package.json 2>/dev/null | grep '"@sentry/'
grep -r "sentry-cdn.com\|js.sentry-cdn.com" . --include="*.html" -l 2>/dev/null | head -3

What to determine:

---

Phase 2: Recommend

Present a recommendation based on what you found. Lead with a concrete proposal, don't ask open-ended questions.

Recommended (core coverage):

• ✅ Error Monitoring — always; captures unhandled errors and promise rejections
• ✅ Tracing — recommended for any interactive site; tracks page load and user interactions
• ✅ Session Replay — recommended for user-facing apps; records sessions around errors

Optional (enhanced observability):

• ⚡ User Feedback — capture reports directly from users after errors
• ⚡ Logging — structured logs via Sentry.logger.*; requires npm or CDN logs bundle (not available via Loader Script)
• ⚡ Profiling — JS Self-Profiling API; beta, Chromium-only, requires Document-Policy: js-profiling response header

Feature recommendation logic:

Installation path recommendation:

Propose: "I recommend setting up Error Monitoring + Tracing + Session Replay using Path A (npm). Want me to also add Logging or User Feedback?"

---

Phase 3: Guide

Path A: npm / yarn / pnpm (Recommended — Bundler Projects)

Install

npm install @sentry/browser --save
# or
yarn add @sentry/browser
# or
pnpm add @sentry/browser

Create src/instrument.ts

Sentry must initialize before any other code runs. Put Sentry.init() in a dedicated sidecar file:

import * as Sentry from "@sentry/browser";

Sentry.init({
  dsn: import.meta.env.VITE_SENTRY_DSN, // Adjust per build tool (see table below)
  environment: import.meta.env.MODE,
  release: import.meta.env.VITE_APP_VERSION, // inject at build time

  dataCollection: {
    // To disable sending user data and HTTP bodies, uncomment the lines below. For more info visit:
    // https://docs.sentry.io/platforms/javascript/configuration/options/#dataCollection
    // userInfo: false,
    // httpBodies: [],
  },

  integrations: [
    Sentry.browserTracingIntegration(),
    Sentry.replayIntegration({
      maskAllText: true,
      blockAllMedia: true,
    }),
  ],

  // Tracing
  tracesSampleRate: 1.0, // lower to 0.1–0.2 in production
  tracePropagationTargets: ["localhost", /^https:\/\/yourapi\.io/],

  // Session Replay
  replaysSessionSampleRate: 0.1,
  replaysOnErrorSampleRate: 1.0,

  enableLogs: true,
});

DSN environment variable by build tool:

Entry Point Setup

Import instrument.ts as the very first import in your entry file:

// src/main.ts or src/index.ts
import "./instrument";  // ← MUST be first

// ... rest of your app

Source Maps Setup (Strongly Recommended)

Without source maps, stack traces show minified code. Set up the build plugin to upload source maps automatically:

No dedicated browser wizard: There is no npx @sentry/wizard -i browser flag. The closest is npx @sentry/wizard@latest -i sourcemaps which configures source map upload only for an already-initialized SDK.

Vite (`vite.config.ts`):

import { defineConfig } from "vite";
import { sentryVitePlugin } from "@sentry/vite-plugin";

export default defineConfig({
  build: { sourcemap: "hidden" },
  plugins: [
    // sentryVitePlugin MUST be last
    sentryVitePlugin({
      org: process.env.SENTRY_ORG,
      project: process.env.SENTRY_PROJECT,
      authToken: process.env.SENTRY_AUTH_TOKEN,
    }),
  ],
});

webpack (`webpack.config.js`):

const { sentryWebpackPlugin } = require("@sentry/webpack-plugin");

module.exports = {
  devtool: "hidden-source-map",
  plugins: [
    sentryWebpackPlugin({
      org: process.env.SENTRY_ORG,
      project: process.env.SENTRY_PROJECT,
      authToken: process.env.SENTRY_AUTH_TOKEN,
    }),
  ],
};

Rollup (`rollup.config.js`):

import { sentryRollupPlugin } from "@sentry/rollup-plugin";

export default {
  output: { sourcemap: "hidden" },
  plugins: [
    sentryRollupPlugin({
      org: process.env.SENTRY_ORG,
      project: process.env.SENTRY_PROJECT,
      authToken: process.env.SENTRY_AUTH_TOKEN,
    }),
  ],
};

esbuild (`build.js`):

const { sentryEsbuildPlugin } = require("@sentry/esbuild-plugin");

require("esbuild").build({
  entryPoints: ["src/index.ts"],
  bundle: true,
  sourcemap: "hidden",
  plugins: [
    sentryEsbuildPlugin({
      org: process.env.SENTRY_ORG,
      project: process.env.SENTRY_PROJECT,
      authToken: process.env.SENTRY_AUTH_TOKEN,
    }),
  ],
});

⚠️ esbuild plugin does not fully support splitting: true. Use sentry-cli instead if code splitting is enabled.

Using `sentry-cli` (any toolchain / CI):

# After your build step:
npx @sentry/cli sourcemaps inject ./dist
npx @sentry/cli sourcemaps upload ./dist

Add .env for auth (never commit):

SENTRY_AUTH_TOKEN=sntrys_...
SENTRY_ORG=my-org-slug
SENTRY_PROJECT=my-project-slug

---

Path B: Loader Script (WordPress, Static Sites, Shopify, Squarespace)

Best for: Sites without a build system. The Loader Script is a single <script> tag that lazily loads the full SDK, always stays up to date via Sentry's CDN, and buffers errors before the SDK loads.

Get the Loader Script: Sentry UI → Settings → Projects → (your project) → SDK Setup → Loader Script

Copy the generated tag and place it as the first script on every page:

<!DOCTYPE html>
<html>
  <head>
    <!-- Configure BEFORE the loader tag -->
    <script>
      window.sentryOnLoad = function () {
        Sentry.init({
          // DSN is already configured in the loader URL
          tracesSampleRate: 1.0,
          replaysSessionSampleRate: 0.1,
          replaysOnErrorSampleRate: 1.0,
        });
      };
    </script>

    <!-- Loader Script FIRST — before all other scripts -->
    <script
      src="https://js.sentry-cdn.com/YOUR_PUBLIC_KEY.min.js"
      crossorigin="anonymous"
    ></script>
  </head>
  ...
</html>

Loader loading modes:

Safe to call before SDK loads (buffered):

• Sentry.captureException()
• Sentry.captureMessage()
• Sentry.captureEvent()
• Sentry.addBreadcrumb()
• Sentry.withScope()

For other methods, use `Sentry.onLoad()`:

<script>
  window.Sentry && Sentry.onLoad(function () {
    Sentry.setUser({ id: "123" });
  });
</script>

Set release via global (optional):

<script>
  window.SENTRY_RELEASE = { id: "my-app@1.0.0" };
</script>

Loader Script limitations:

• ❌ No Sentry.logger.* (logging) — npm path only
• ❌ No framework-specific features (React ErrorBoundary, Vue Router tracking, etc.)
• ❌ Tracing headers only added to fetch calls made after SDK loads
• ❌ Version changes take a few minutes to propagate via CDN cache
• ⚠️ Use defer (not async) on all other scripts when using the loader

CSP requirements:

script-src: https://browser.sentry-cdn.com https://js.sentry-cdn.com
connect-src: *.sentry.io

---

Path C: CDN Bundles (Manual Script Tags)

Best for: Pages that can't use the Loader Script but need synchronous loading.

Pick the bundle that matches your feature needs and place it before all other scripts:

Errors only (minimal footprint):

<script
  src="https://browser.sentry-cdn.com/10.42.0/bundle.min.js"
  integrity="sha384-L/HYBH2QCeLyXhcZ0hPTxWMnyMJburPJyVoBmRk4OoilqrOWq5kU4PNTLFYrCYPr"
  crossorigin="anonymous"
></script>

Errors + Tracing:

<script
  src="https://browser.sentry-cdn.com/10.42.0/bundle.tracing.min.js"
  integrity="sha384-DIqcfVcfIewrWiNWfVZcGWExO5v673hkkC5ixJnmAprAfJajpUDEAL35QgkOB5gw"
  crossorigin="anonymous"
></script>

Errors + Session Replay:

<script
  src="https://browser.sentry-cdn.com/10.42.0/bundle.replay.min.js"
  integrity="sha384-sbojwIJFpv9duIzsI9FRm87g7pB15s4QwJS1m1xMSOdV1CF3pwgrPPEu38Em7M9+"
  crossorigin="anonymous"
></script>

Errors + Tracing + Replay (recommended full setup):

<script
  src="https://browser.sentry-cdn.com/10.42.0/bundle.tracing.replay.min.js"
  integrity="sha384-oo2U4zsTxaHSPXJEnXtaQPeS4Z/qbTqoBL9xFgGxvjJHKQjIrB+VRlu97/iXBtzw"
  crossorigin="anonymous"
></script>

Errors + Tracing + Replay + User Feedback:

<script
  src="https://browser.sentry-cdn.com/10.42.0/bundle.tracing.replay.feedback.min.js"
  integrity="sha384-SmHU39Qs9cua0KLtq3A6gis1/cqM1nZ6fnGzlvWAPiwhBDO5SmwFQV65BBpJnB3n"
  crossorigin="anonymous"
></script>

Full bundle (all features):

<script
  src="https://browser.sentry-cdn.com/10.42.0/bundle.tracing.replay.feedback.logs.metrics.min.js"
  integrity="sha384-gOjSzRxwpXpy0FlT6lg/AVhagqrsUrOWUO7jm6TJwuZ9YVHtYK0MBA2hW2FGrIGl"
  crossorigin="anonymous"
></script>

CDN bundle variants summary:

Initialize after the script tag:

<script>
  Sentry.init({
    dsn: "https://YOUR_KEY@o0.ingest.sentry.io/YOUR_PROJECT",
    environment: "production",
    release: "my-app@1.0.0",
    integrations: [
      Sentry.browserTracingIntegration(),
      Sentry.replayIntegration({
        maskAllText: true,
        blockAllMedia: true,
      }),
    ],
    tracesSampleRate: 1.0,
    tracePropagationTargets: ["localhost", /^https:\/\/yourapi\.io/],
    replaysSessionSampleRate: 0.1,
    replaysOnErrorSampleRate: 1.0,
  });
</script>

CDN CSP requirements:

script-src: https://browser.sentry-cdn.com https://js.sentry-cdn.com
connect-src: *.sentry.io

---

For Each Agreed Feature

Walk through features one at a time. Load the reference file, follow its steps, verify before moving on:

For each feature: Read ${SKILL_ROOT}/references/<feature>.md, follow steps exactly, verify it works.

---

Configuration Reference

Key Sentry.init() Options

Browser-Specific Options

dataCollection Option (v10.54+)

Fine-grained control over what data the SDK collects. Replaces the simple sendDefaultPii boolean with granular settings. When omitted, falls back to sendDefaultPii for backwards compatibility.

Example:

Sentry.init({
  dsn: "...",
  dataCollection: {
    userInfo: true,
    cookies: { deny: ["session_id", "auth_token"] },
    httpHeaders: {
      request: { deny: ["authorization", "cookie"] },
      response: true,
    },
    queryParams: { allow: ["utm_source", "utm_campaign"] },
  },
});

window.SENTRY_RELEASE Global (CDN / Loader Path)

Set the release version before the SDK loads:

<script>
  window.SENTRY_RELEASE = { id: "my-app@1.0.0" };
</script>

---

Verification

Trigger test events to confirm Sentry is receiving data:

npm / CDN path:

<!-- Add temporarily to your page -->
<button onclick="throw new Error('Sentry Browser Test Error')">
  Test Error
</button>

Performance verification (npm path):

import * as Sentry from "@sentry/browser";

Sentry.startSpan({ name: "Test Span", op: "test" }, () => {
  // your operation
});

Manual capture:

Sentry.captureException(new Error("Manual test"));
Sentry.captureMessage("Manual test message", "info");

Check the Sentry dashboard:

• Issues → error appears within seconds
• Traces → page load transaction visible
• Replays → session recording visible after page interaction
• Logs → structured log entries if logging enabled (npm or CDN logs bundle)

Set debug: true in Sentry.init() and check the browser console if nothing appears.

---

Phase 4: Cross-Link

After completing browser setup, check for a companion backend missing Sentry coverage:

ls ../backend ../server ../api ../go ../python 2>/dev/null
cat ../go.mod 2>/dev/null | head -3
cat ../requirements.txt ../pyproject.toml 2>/dev/null | head -3
cat ../Gemfile 2>/dev/null | head -3
cat ../pom.xml 2>/dev/null | grep '<artifactId>' | head -3
cat ../composer.json 2>/dev/null | head -3

If a backend exists without Sentry configured, suggest the matching skill:

---

Troubleshooting

Error Monitoring — Sentry Browser SDK

Minimum SDK: @sentry/browser ≥7.0.0

makeBrowserOfflineTransport requires @sentry/browser ≥7.48.0

linkedErrorsIntegration cause chain requires Error.cause support (Chrome 93+, Firefox 91+)

---

How Automatic Capture Works

The browser SDK hooks into the browser environment and captures errors from multiple layers automatically:

What Requires Manual Instrumentation

The global handlers only catch errors that escape your code. These are silently swallowed without manual calls:

• Errors caught by your own try/catch blocks
• Business-logic failures (validation errors, unexpected states)
• Async errors in .then() chains where .catch() is attached
• User-visible conditions that aren't exceptions (use captureMessage)

---

Core Capture APIs

Sentry.captureException(error, captureContext?)

Captures an exception and sends it to Sentry. Prefer Error objects — they include stack traces.

import * as Sentry from "@sentry/browser";

// Basic usage
try {
  riskyOperation();
} catch (err) {
  Sentry.captureException(err);
}

// With inline capture context
try {
  await chargeCard(order);
} catch (err) {
  Sentry.captureException(err, {
    level: "fatal",
    tags: { module: "checkout", payment_provider: "stripe" },
    extra: { orderId: order.id, amount: order.total },
    user: { id: "u_123", email: "user@example.com" },
    fingerprint: ["checkout-payment-fail"],
    contexts: {
      payment: { provider: "stripe", amount: 9999, currency: "usd" },
    },
  });
}

// Non-Error values are accepted but may lack stack traces
Sentry.captureException("Something went wrong as a string");

`CaptureContext` shape:

---

Sentry.captureMessage(message, levelOrContext?)

Captures a plain-text message as a Sentry issue.

// With a severity level (shorthand second argument)
Sentry.captureMessage("Something went wrong", "warning");
Sentry.captureMessage("Payment gateway timeout", "fatal");

// With full CaptureContext
Sentry.captureMessage("User performed invalid action", {
  level: "warning",
  user: { id: "u_456" },
  tags: { feature: "cart", action: "remove-item" },
  extra: { itemId: "sku_789" },
});

Set attachStacktrace: true in Sentry.init() to automatically attach a stack trace to message events.

---

Sentry.captureEvent(event)

Sends a fully constructed Sentry event object. Use captureException or captureMessage in application code; use captureEvent for custom integrations or forwarding from legacy loggers.

Sentry.captureEvent({
  message: "Legacy logger forwarded event",
  level: "warning",
  tags: { source: "legacy-logger", module: "billing" },
  extra: { rawLog: "something went wrong at line 42" },
  timestamp: Date.now() / 1000, // Unix timestamp in seconds
  fingerprint: ["legacy-billing-error"],
});

---

Utility APIs

// Get the event ID of the last sent error event
const eventId = Sentry.lastEventId();

// Flush all pending events before page unload / shutdown
await Sentry.flush(2000); // wait up to 2 seconds

// Flush and disable the SDK permanently
await Sentry.close(2000);

// Check if SDK is initialized and enabled
if (Sentry.isEnabled()) { /* ... */ }

---

Scope Management

Sentry uses three nested scope types. Data from all three is merged before each event is sent.

Merge priority (later overrides earlier):

Global Scope → Isolation Scope → Current Scope → Event-level CaptureContext

Browser note: In a browser there is no per-request isolation, so the isolation scope effectively behaves like the global scope. The distinction matters in server-side runtimes (Node.js, Deno, Cloudflare Workers).

---

withScope — Per-Event Scoping (Recommended)

Forks the current scope, runs your callback with the fork, and discards it when done. This is the preferred way to attach data to a single event without polluting broader scope.

Sentry.withScope((scope) => {
  scope.setTag("transaction_id", "txn_abc123");
  scope.setExtra("requestPayload", { amount: 50, currency: "USD" });
  scope.setLevel("warning");
  scope.setUser({ id: "u_789" });
  scope.setFingerprint(["payment-error", "stripe"]);
  Sentry.captureException(new Error("Payment failed"));
  // scope is discarded after this callback
});

// Events captured here are NOT affected by the above scope
Sentry.captureMessage("This event has no payment tags");

---

Scope Methods

Every scope instance exposes the same enrichment API:

// Isolation scope — persists for all subsequent events on this page
Sentry.getIsolationScope().setUser({ id: "u_123", email: "user@example.com" });
Sentry.getIsolationScope().setTag("app_version", "3.4.1");

// Global scope — applied to every event in the app
Sentry.getGlobalScope().setTag("datacenter", "us-east-1");
Sentry.getGlobalScope().setContext("build", {
  commit: "abc1234",
  buildDate: "2026-03-03",
});

// Scope method reference
scope.setUser({ id, email, username, ip_address });  // setUser(null) to clear
scope.setTag("key", "value");
scope.setTags({ key1: "v1", key2: "v2" });
scope.setExtra("key", value);
scope.setExtras({ key1: v1, key2: v2 });
scope.setContext("name", { key: value });  // setContext("name", null) to remove
scope.setLevel("warning");
scope.setFingerprint(["my-group-key"]);
scope.addBreadcrumb({ category: "auth", message: "User logged in" });
scope.addEventProcessor((event) => { /* modify or drop */ return event; });
scope.clear(); // reset all scope data

---

Event Enrichment

Tags — Indexed, Searchable Key-Value Pairs

Tags power filtering, search, and tag distribution maps in the Sentry UI.

Constraints: Key ≤32 chars (a-zA-Z0-9_.:-, no spaces). Value ≤200 chars, no newlines.

// Single tag — applied to all subsequent events (isolation scope)
Sentry.setTag("page_locale", "de-at");
Sentry.setTag("subscription_tier", "pro");
Sentry.setTag("feature_flag", "new_checkout_enabled");

// Multiple tags at once
Sentry.setTags({
  environment: "staging",
  region: "eu-west-1",
  api_version: "v3",
});

// Scoped tag — only on this one event
Sentry.withScope((scope) => {
  scope.setTag("retry_attempt", "3");
  Sentry.captureException(new Error("Max retries exceeded"));
});

---

Context — Rich Unindexed Structured Data

Context is not indexed or searchable but displays in full on the event details page. Use it for rich structured data you need for debugging but don't need to filter on.

Sentry.setContext("shopping_cart", {
  itemCount: 3,
  totalAmount: 149.99,
  currency: "USD",
  couponApplied: "SAVE10",
});

Sentry.setContext("device", {
  platform: navigator.platform,
  language: navigator.language,
  screenWidth: screen.width,
  screenHeight: screen.height,
});

// Clear a context by passing null
Sentry.setContext("shopping_cart", null);

Depth limit: Nested context objects are normalized to 3 levels deep by default. Use normalizeDepth in init() to change this.

---

User Information

// Set user on login
Sentry.setUser({
  id: "user_abc123",
  email: "alice@example.com",
  username: "alice",
  subscription: "premium", // arbitrary extra field
  org: "acme-corp",
});

// Clear user on logout
Sentry.setUser(null);

// Auto-infer IP address (requires sendDefaultPii: true in init)
Sentry.setUser({ ip_address: "{{auto}}" });

---

initialScope — Set Context at Startup

// Object form
Sentry.init({
  dsn: "___PUBLIC_DSN___",
  initialScope: {
    tags: { "app.version": "1.2.3", region: "us-west" },
    user: { id: 42, email: "john.doe@example.com" },
  },
});

// Callback form (full Scope API access)
Sentry.init({
  dsn: "___PUBLIC_DSN___",
  initialScope: (scope) => {
    scope.setTags({ a: "b", c: "d" });
    scope.setContext("device", { platform: navigator.platform });
    return scope;
  },
});

---

Breadcrumbs

Breadcrumbs create a trail of events leading up to an issue. They're buffered locally and attached to the next event sent to Sentry.

Automatic Breadcrumbs

Manual Breadcrumbs

// Authentication event
Sentry.addBreadcrumb({
  category: "auth",
  message: "User authenticated",
  level: "info",
  data: { userId: user.id, method: "oauth2", provider: "google" },
});

// Navigation event
Sentry.addBreadcrumb({
  type: "navigation",
  category: "navigation",
  data: { from: "/home", to: "/checkout" },
});

// Custom action
Sentry.addBreadcrumb({
  category: "cart",
  message: "Item added to cart",
  level: "info",
  data: { itemId: "sku_123", quantity: 2, price: 29.99 },
});

// Feature flag
Sentry.addBreadcrumb({
  type: "debug",
  category: "feature-flag",
  message: "New checkout flow enabled",
  level: "debug",
  data: { flag: "checkout_v2", value: true },
});

Breadcrumb schema:

---

Breadcrumb Configuration

Sentry.init({
  dsn: "___PUBLIC_DSN___",
  maxBreadcrumbs: 50, // default: 100

  beforeBreadcrumb(breadcrumb, hint) {
    // Drop UI click breadcrumbs
    if (breadcrumb.category === "ui.click") return null;

    // Enrich XHR breadcrumbs with request body size
    if (breadcrumb.type === "http" && hint?.xhr) {
      breadcrumb.data = {
        ...breadcrumb.data,
        requestBodySize: hint.xhr.requestBody?.length ?? 0,
      };
    }

    // Drop console.debug noise in production
    if (breadcrumb.category === "console" && breadcrumb.level === "debug") {
      return null;
    }

    return breadcrumb;
  },

  integrations: [
    Sentry.breadcrumbsIntegration({
      console: true,
      dom: { serializeAttribute: ["data-testid", "aria-label"] },
      fetch: true,
      history: true,
      xhr: true,
      sentry: true,
    }),
  ],
});

---

Hooks — beforeSend, beforeSendTransaction, beforeBreadcrumb

beforeSend — Modify or Drop Error Events

Called last, just before an error event is sent. All scope data has already been applied. Return the event to send it, or null to drop it.

Sentry.init({
  dsn: "___PUBLIC_DSN___",

  beforeSend(event, hint) {
    const err = hint.originalException;

    // --- Drop known noisy errors ---
    if (event.exception?.values?.[0]?.value?.includes("ResizeObserver")) {
      return null;
    }

    // --- Drop browser extension errors ---
    if (event.exception?.values?.[0]?.stacktrace?.frames?.some(
      (frame) => frame.filename?.includes("extension://")
    )) {
      return null;
    }

    // --- PII scrubbing ---
    if (event.user?.email) {
      delete event.user.email;
    }

    // --- Custom fingerprinting based on original exception ---
    if (err instanceof NetworkError) {
      event.fingerprint = ["network-error", err.statusCode?.toString() ?? "unknown"];
    }

    // --- Add extra context from the original exception ---
    if (err instanceof ApiError) {
      event.extra = {
        ...event.extra,
        requestId: err.requestId,
        endpoint: err.endpoint,
      };
    }

    return event;
  },
});

`hint` object properties:

---

beforeSendTransaction — Modify or Drop Transaction Events

Same as beforeSend but for performance transaction events.

Sentry.init({
  beforeSendTransaction(event) {
    // Drop health check transactions
    if (event.transaction === "/health" || event.transaction === "/ping") {
      return null;
    }

    // Scrub PII from transaction name
    event.transaction = event.transaction?.replace(/\/users\/\d+/, "/users/:id");

    return event;
  },
});

---

Event Processors

Event processors intercept every event before it's sent. Unlike beforeSend, multiple processors can be registered and run in series.

// Global event processor — runs on ALL events
Sentry.addEventProcessor((event, hint) => {
  // Add build metadata to every event
  event.tags = {
    ...event.tags,
    build_sha: BUILD_SHA,
    deploy_env: DEPLOY_ENV,
  };

  // Drop events with no stack trace in production
  if (
    IS_PRODUCTION &&
    !event.exception?.values?.[0]?.stacktrace?.frames?.length
  ) {
    return null;
  }

  return event;
});

// Scope-level processor — only applies within withScope
Sentry.withScope((scope) => {
  scope.addEventProcessor((event) => {
    event.tags = { ...event.tags, source: "checkout-flow" };
    return event;
  });
  Sentry.captureException(new Error("Checkout failed"));
});

Key differences vs. `beforeSend`:

---

Fingerprinting

Every event has a fingerprint array. Events with the same fingerprint are grouped into the same issue.

Extending Default Grouping

Use {{ default }} to keep Sentry's default grouping and add extra discriminators:

Sentry.init({
  beforeSend(event, hint) {
    const err = hint.originalException;

    if (err instanceof ApiError) {
      // Keep default grouping but split further by RPC function + error code
      event.fingerprint = ["{{ default }}", err.functionName, String(err.errorCode)];
    }

    return event;
  },
});

Overriding Default Grouping

Omit {{ default }} to completely replace the auto-generated fingerprint (collapses all matching errors into one issue):

Sentry.init({
  beforeSend(event, hint) {
    const err = hint.originalException;

    if (err?.message?.includes("timeout")) {
      event.fingerprint = ["network-timeout"];
    }

    if (err?.name === "ChunkLoadError") {
      event.fingerprint = ["chunk-load-failure"];
    }

    return event;
  },
});

Inline Fingerprint on Capture

Sentry.captureException(err, {
  fingerprint: ["payment-gateway", "stripe", err.code],
});

Sentry.captureMessage("Rate limit exceeded", {
  fingerprint: ["rate-limit", endpoint],
});

// Group by HTTP method + path + status code
Sentry.withScope((scope) => {
  scope.setFingerprint([method, path, String(err.statusCode)]);
  Sentry.captureException(err);
});

Fingerprint variables:

---

Event Filtering

ignoreErrors — Pattern-Based Filtering

Sentry.init({
  ignoreErrors: [
    // String (partial match):
    "ResizeObserver loop limit exceeded",
    "fb_xd_fragment",
    "Non-Error exception captured",

    // Regex (full control):
    /^Network Error$/,
    /ChunkLoadError/,
    /Loading chunk \d+ failed/,
    /^Script error\.?$/,
  ],
});

allowUrls / denyUrls — Filter by Script Origin

These filter based on stack frame URLs (where the code lives), not the page URL.

Sentry.init({
  // Only capture errors from your own scripts
  allowUrls: [
    /https?:\/\/((cdn|www)\.)?myapp\.com/,
  ],

  // Never capture errors from these script origins
  denyUrls: [
    /extensions\//i,
    /^chrome:\/\//i,
    /^moz-extension:\/\//i,
    /^safari-extension:\/\//i,
    /ads\.doubleclick\.net/,
  ],
});

sampleRate — Error Volume Reduction

Sentry.init({
  sampleRate: 0.25, // Capture 25% of errors (randomly sampled)
});

---

Default Integrations

Auto-Enabled Browser Integrations (9 total)

Modifying Default Integrations

// Disable a single default integration by name
Sentry.init({
  integrations: (defaults) =>
    defaults.filter((i) => i.name !== "Breadcrumbs"),
});

// Reconfigure a default integration
Sentry.init({
  integrations: [
    Sentry.breadcrumbsIntegration({ console: false }),
    Sentry.linkedErrorsIntegration({ limit: 10 }),
    Sentry.globalHandlersIntegration({ onunhandledrejection: false }),
    Sentry.browserSessionIntegration({ lifecycle: "page" }),
  ],
});

// Disable ALL defaults (start from scratch)
Sentry.init({
  defaultIntegrations: false,
  integrations: [
    Sentry.globalHandlersIntegration(),
    Sentry.linkedErrorsIntegration(),
  ],
});

Adding Integrations After init()

// Lazy-add after init
Sentry.addIntegration(Sentry.reportingObserverIntegration());

// Dynamic import from npm (recommended with bundlers)
const { captureConsoleIntegration } = await import("@sentry/browser");
Sentry.addIntegration(captureConsoleIntegration({ levels: ["error", "warn"] }));

---

Transport

Default Transport

The browser SDK uses a fetch-based transport. Events are sent as POST requests to the Sentry ingestion endpoint.

Offline Transport — IndexedDB Queue

Stores events when offline and replays them when the browser reconnects:

import { makeBrowserOfflineTransport, makeFetchTransport } from "@sentry/browser";
import * as Sentry from "@sentry/browser";

Sentry.init({
  dsn: "___PUBLIC_DSN___",
  transport: makeBrowserOfflineTransport(makeFetchTransport),
});

Tunneling — Bypass Ad-Blockers

Route all Sentry traffic through your own server endpoint:

Sentry.init({
  dsn: "___PUBLIC_DSN___", // Still required for header generation
  tunnel: "https://myapp.com/sentry-tunnel",
});

Your server endpoint forwards the payload to Sentry's ingestion URL. See Dealing with Ad-Blockers for a full tunneling server implementation.

Custom Transport

import { createTransport } from "@sentry/core";
import * as Sentry from "@sentry/browser";

function makeCustomFetchTransport(options) {
  function makeRequest(request) {
    return fetch(options.url, {
      body: request.body,
      method: "POST",
      referrerPolicy: "origin",
      headers: {
        ...options.headers,
        "X-Custom-Header": "my-value",
      },
    }).then((response) => ({
      statusCode: response.status,
      headers: {
        "x-sentry-rate-limits": response.headers.get("X-Sentry-Rate-Limits"),
        "retry-after": response.headers.get("Retry-After"),
      },
    }));
  }

  return createTransport(options, makeRequest);
}

Sentry.init({
  dsn: "___PUBLIC_DSN___",
  transport: makeCustomFetchTransport,
});

---

Best Practices

• Set user context after authentication — call Sentry.setUser() after login completes, not in Sentry.init.
• Clear user on logout — always call Sentry.setUser(null) when the user signs out.
• Use `withScope` for per-event context — avoid mutating the isolation scope for temporary data.
• Use tags for filterable data, context for debugging data — tags are indexed; context is not.
• Filter noise early — use ignoreErrors and denyUrls to drop known-bad events before beforeSend.
• Avoid capturing in render paths — wrap Sentry calls in event handlers or try/catch blocks.
• Set `release` and `environment` — required for source map resolution and environment-aware alerting.
• Use `beforeSend` for PII scrubbing — never send emails, credit card numbers, or passwords as tags/extra.
• Use `{{ default }}` in fingerprints to extend, not replace, Sentry's grouping when appropriate.

---

Troubleshooting

Logging — Sentry Browser SDK

Minimum SDK: @sentry/browser ≥9.41.0 for Sentry.logger API and enableLogs

consoleLoggingIntegration(): requires ≥10.13.0+

Scope-based attributes (getGlobalScope, getIsolationScope): requires ≥10.32.0+

⚠️ NPM or CDN logs bundle required — Sentry logging is not available via the Loader Script. Use npm/yarn/pnpm (@sentry/browser) or a CDN bundle with .logs. in its name (e.g., bundle.logs.metrics.min.js).

---

Enabling Logs

enableLogs is opt-in and must be explicitly set in Sentry.init():

import * as Sentry from "@sentry/browser";

Sentry.init({
  dsn: "___PUBLIC_DSN___",
  enableLogs: true, // Required — logging is disabled by default
});

Without enableLogs: true, all Sentry.logger.* calls are silently no-ops and nothing is sent to Sentry.

---

Logger API — Six Levels

import * as Sentry from "@sentry/browser";

Sentry.logger.trace("Entering processOrder", { fn: "processOrder", orderId: "ord_1" });
Sentry.logger.debug("Cache lookup", { key: "user:123", hit: false });
Sentry.logger.info("Order created", { orderId: "order_456", total: 99.99 });
Sentry.logger.warn("Rate limit approaching", { current: 95, max: 100 });
Sentry.logger.error("Payment failed", { reason: "card_declined", userId: "u_1" });
Sentry.logger.fatal("Database unavailable", { host: "db-primary" });

Attribute value types: string, number, boolean only — undefined, arrays, and objects are not accepted.

---

Parameterized Messages — Sentry.logger.fmt

The fmt tagged template literal binds each interpolated variable as a structured, searchable attribute in Sentry:

const userId = "user_123";
const productName = "Widget Pro";
const amount = 49.99;

Sentry.logger.info(
  Sentry.logger.fmt`User ${userId} purchased ${productName} for $${amount}`
);

This produces:

message.template:     "User %s purchased %s for $%s"
message.parameter.0:  "user_123"
message.parameter.1:  "Widget Pro"
message.parameter.2:  49.99

Each parameter is independently searchable in Sentry's log explorer. You can filter by message.parameter.0 = "user_123" without matching the full message string.

⚠️ logger.fmt must be used as a tagged template literal — not as a function call. Sentry.logger.fmt("text") will not produce structured parameters.

When to use fmt vs plain attributes

---

Console Integration (consoleLoggingIntegration) — SDK ≥10.13.0

Capture console.log, console.warn, console.error, and other console calls as Sentry logs automatically:

import * as Sentry from "@sentry/browser";

Sentry.init({
  dsn: "___PUBLIC_DSN___",
  enableLogs: true,
  integrations: [
    Sentry.consoleLoggingIntegration({ levels: ["log", "warn", "error"] }),
  ],
});

// These are now automatically sent to Sentry
console.log("User logged in", { userId: 123 });
console.warn("Slow network detected");
console.error("API request failed");

The integration intercepts console.* calls and converts them to structured Sentry logs. Interpolated values are extracted as message.parameter.N attributes.

Available levels: "log", "info", "warn", "error", "debug", "trace".

---

Filtering Logs (beforeSendLog)

Filter or modify logs before they are sent to Sentry:

Sentry.init({
  dsn: "___PUBLIC_DSN___",
  enableLogs: true,
  beforeSendLog: (log) => {
    // Drop debug logs in production
    if (log.level === "debug" || log.level === "trace") {
      return null;
    }

    // Scrub sensitive attributes
    if (log.attributes?.password) {
      delete log.attributes.password;
    }

    if (log.attributes?.credit_card) {
      log.attributes.credit_card = "[REDACTED]";
    }

    return log;
  },
});

The log object shape

Return null to drop the log. Return the (optionally modified) log object to send it.

---

Structured Attributes

Every Sentry.logger.* call accepts an attributes object as its second argument:

Sentry.logger.info("Checkout completed", {
  orderId: "ord_789",
  userId: "usr_123",
  cartValue: 149.99,
  itemCount: 3,
  paymentMethod: "stripe",
});

Attributes become searchable and filterable in Sentry's log explorer. Prefer one comprehensive log with all relevant context over many small scattered logs.

---

Scope-Based Automatic Attributes (SDK ≥10.32.0)

Attributes set on scopes are automatically added to all logs emitted within that scope.

Global scope — entire session

// Set once at app startup — persists for the lifetime of the page
Sentry.getGlobalScope().setAttributes({
  service: "checkout",
  version: "2.1.0",
  region: "us-east-1",
});

Isolation scope — logical session context

// Set after user authenticates
Sentry.getIsolationScope().setAttributes({
  org_id: user.orgId,
  user_tier: user.tier,
});

Current scope — single operation

Sentry.withScope((scope) => {
  scope.setAttribute("order_id", "ord_789");
  Sentry.logger.info("Processing payment", { amount: 49.99 });
  // order_id is included on this log only
});

Constraint: Scope attributes accept only string, number, and boolean values.

---

Auto-Generated Attributes

These are added by the SDK to every log without any developer configuration:

---

Log-to-Trace Correlation

When tracing is enabled, logs are automatically linked to the active span:

Sentry.init({
  dsn: "___PUBLIC_DSN___",
  enableLogs: true,
  tracesSampleRate: 1.0,
  integrations: [Sentry.browserTracingIntegration()],
});

// Logs emitted inside a span are linked to it automatically
await Sentry.startSpan({ name: "checkout-flow", op: "ui.action" }, async () => {
  Sentry.logger.info("Validating cart", { cartId: "cart_abc" });
  await validateCart();
  Sentry.logger.info("Initiating payment", { gateway: "stripe" });
  await initiatePayment();
});
// Both logs above have sentry.trace.parent_span_id set to the checkout-flow span ID

In the Sentry UI:

• From a log → click the trace link to jump to the parent span and full trace
• From a trace span → click "Logs" to see all logs emitted during that span
• From a replay → logs are shown inline with the user session recording

---

When to Use Each API

Use Sentry.logger.* for structured, searchable observability data. Use captureException for actual errors that need issue grouping and stack traces.

---

Log Level Guide

---

Troubleshooting

Browser Profiling — Sentry Browser SDK

Minimum SDK: @sentry/browser ≥10.27.0 (Beta)

⚠️ Beta status — breaking changes may occur. Browser support is limited to Chromium-based browsers only (Chrome, Edge). Firefox and Safari are not supported.

---

What Browser Profiling Captures

Sentry's browser profiler uses the JS Self-Profiling API to capture:

• JavaScript call stacks — function names and source file locations (deobfuscated via source maps)
• CPU time per function — how much time is spent in each function
• Flame graphs — aggregated across real user sessions, not just local dev
• Linked profiles — every profile is attached to a trace, enabling navigation from span → flame graph in Sentry

Sampling rate: 100Hz (10ms intervals) — runs unobtrusively in production.

---

Browser Compatibility

⚠️ Sampling bias: Profile data is collected only from Chromium users. Firefox and Safari sessions are silently excluded — no error is thrown, no overhead is added.

---

Required HTTP Header

Every document response must include this header or profiling silently fails:

Document-Policy: js-profiling

Without this header, the JS Self-Profiling API is blocked by the browser and no profiles are collected.

Platform-Specific Header Setup

Vercel (`vercel.json`):

{
  "headers": [
    {
      "source": "/(.*)",
      "headers": [{ "key": "Document-Policy", "value": "js-profiling" }]
    }
  ]
}

Netlify (`netlify.toml`):

[[headers]]
  for = "/*"
  [headers.values]
    Document-Policy = "js-profiling"

Netlify (`_headers` file):

/*
  Document-Policy: js-profiling

Express / Node.js:

app.use((req, res, next) => {
  res.set("Document-Policy", "js-profiling");
  next();
});

Nginx:

add_header Document-Policy "js-profiling";

---

Basic Setup

import * as Sentry from "@sentry/browser";

Sentry.init({
  dsn: "___PUBLIC_DSN___",
  integrations: [
    Sentry.browserTracingIntegration(),
    Sentry.browserProfilingIntegration(),
  ],
  tracesSampleRate: 1.0,
  profileSessionSampleRate: 1.0, // Profile 100% of sessions (lower in production)
});

Profiling requires tracing to be active. browserTracingIntegration() and a tracesSampleRate > 0 are both required.

---

Configuration Options

profilesSampleRate vs profileSessionSampleRate

---

Profiling Modes

Trace Mode (Automatic)

Profiler starts and stops automatically in sync with every active root span (trace). Recommended for general-purpose production profiling.

Sentry.init({
  dsn: "___PUBLIC_DSN___",
  integrations: [
    Sentry.browserTracingIntegration(),
    Sentry.browserProfilingIntegration(),
  ],
  tracesSampleRate: 1.0,
  profileSessionSampleRate: 0.1, // Profile 10% of sessions
  profileLifecycle: "trace",     // Profile automatically with each trace
});

Manual Mode (Default)

Start and stop the profiler explicitly around specific code you want to measure.

Sentry.init({
  dsn: "___PUBLIC_DSN___",
  integrations: [
    Sentry.browserTracingIntegration(),
    Sentry.browserProfilingIntegration(),
  ],
  tracesSampleRate: 1.0,
  profileSessionSampleRate: 1.0,
  profileLifecycle: "manual", // default
});

// Somewhere in your application
Sentry.uiProfiler.startProfiler();

doExpensiveWork();
renderComplexChart();

Sentry.uiProfiler.stopProfiler();

Use manual mode when you know exactly which operations to measure and want to avoid profiling overhead during unrelated work.

---

Production Sampling Strategy

Profiling adds CPU overhead. Use conservative rates in production:

Sentry.init({
  dsn: "___PUBLIC_DSN___",
  integrations: [
    Sentry.browserTracingIntegration(),
    Sentry.browserProfilingIntegration(),
  ],
  tracesSampleRate: 0.2,           // Sample 20% of traces
  profileSessionSampleRate: 0.1,   // Profile 10% of sessions
  profileLifecycle: "trace",
});

profileSessionSampleRate is evaluated once per session (page load), not per trace. A session either profiles all its traces or none of them.

---

Best Practices

• Start with `profileLifecycle: "trace"` — automatic profiling with traces requires no extra instrumentation
• Set `profileSessionSampleRate` to 0.1–0.2 in production to limit overhead
• Upload source maps — profiling data shows minified names without source maps; the flame graph is much more useful with them
• Use manual mode when investigating a specific known bottleneck (e.g., a slow chart render or complex animation)
• Combine with tracing — profiles are always linked to a trace, so you can navigate from a slow span to its flame graph
• Don't profile static hosts without header support — GitHub Pages and some CDNs cannot serve custom HTTP response headers; profiling will silently not work

---

Known Limitations

---

Troubleshooting

Session Replay — Sentry Browser SDK

Minimum SDK: @sentry/browser ≥7.27.0

replayCanvasIntegration available since SDK ≥7.50.0

beforeAddRecordingEvent available since SDK ≥7.53.0

beforeErrorSampling available since SDK ≥7.56.0

Node 12+ required; browsers newer than IE11

---

Basic Setup

import * as Sentry from "@sentry/browser";

Sentry.init({
  dsn: "___PUBLIC_DSN___",
  replaysSessionSampleRate: 0.1,   // 10% of all sessions recorded in full
  replaysOnErrorSampleRate: 1.0,   // 100% of sessions with errors buffered and sent
  integrations: [Sentry.replayIntegration()],
});

---

Sampling Rates

replaysSessionSampleRate vs. replaysOnErrorSampleRate

How Sampling Works

1. replaysSessionSampleRate is checked first at session start.

• If sampled → full session recording starts immediately, sent to Sentry in real-time chunks (Session mode).
• If not sampled → recording is buffered in memory (last 60 seconds only) (Buffer mode).

2. If an error occurs in a buffered session:

• replaysOnErrorSampleRate is checked.
• If sampled → 60-second buffer + rest of session is sent to Sentry.
• If not sampled → buffer is discarded.

When data leaves the browser:

Recommended rates by traffic volume:

Tip: Keep replaysOnErrorSampleRate at 1.0 — error sessions provide the most debugging value.

Dev tip: Set replaysSessionSampleRate: 1.0 during development to capture every session.

---

replayIntegration() — Configuration Reference

General Options

Privacy Options

Network Options

---

Privacy & Masking

Three Privacy Methods

HTML Attribute Usage

<!-- Mask text content -->
<p class="sentry-mask">Sensitive user data</p>
<p data-sentry-mask>Sensitive user data</p>

<!-- Block entire element (credit card form, PII section) -->
<div class="sentry-block">
  <input type="text" placeholder="Credit card number" />
</div>
<div data-sentry-block>Blocked content</div>

<!-- Ignore input events (no keystrokes recorded) -->
<input class="sentry-ignore" type="password" />
<input data-sentry-ignore type="text" placeholder="SSN" />

<!-- Unmask when maskAllText=true -->
<p class="sentry-unmask">Safe to show in replay</p>
<p data-sentry-unmask>Safe to show</p>

<!-- Unblock media when blockAllMedia=true -->
<img class="sentry-unblock" src="product-image.png" alt="Product" />
<img data-sentry-unblock src="logo.svg" alt="Logo" />

Configuration Examples

Disable all default masking (show everything):

Sentry.replayIntegration({
  maskAllText: false,
  blockAllMedia: false,
});

Mask and block specific selectors:

Sentry.replayIntegration({
  mask: [".user-pii", "[data-sensitive]", "#account-details"],
  unmask: [".replay-safe"],
  block: ["#payment-form", ".credit-card-widget"],
  unblock: [".product-image"],
  ignore: [".password-field", "[type='password']"],
});

Custom masking function:

Sentry.replayIntegration({
  maskFn: (text) => text.replace(/\S/g, "X"), // Replace non-whitespace with X
});

Custom recording event filter:

Sentry.replayIntegration({
  beforeAddRecordingEvent: (event) => {
    // Drop any event tagged "foo"
    if (event.data.tag === "foo") return null;

    // Only capture network events for 500 errors
    if (
      event.data.tag === "performanceSpan" &&
      (event.data.payload.op === "resource.fetch" ||
        event.data.payload.op === "resource.xhr") &&
      event.data.payload.data.statusCode !== 500
    ) {
      return null;
    }

    return event;
  },
});

---

Network Capture

By default, Session Replay captures basic information about all outgoing fetch and XHR requests (URL, size, method, status code).

Request/response bodies and additional headers require explicit opt-in (SDK ≥7.50.0):

Sentry.replayIntegration({
  networkDetailAllowUrls: [window.location.origin],
});

Advanced — multiple patterns with custom headers:

Sentry.replayIntegration({
  networkDetailAllowUrls: [
    window.location.origin,
    "api.example.com",
    /^https:\/\/api\.example\.com/,
  ],
  networkCaptureBodies: true,        // default: true — capture request/response bodies
  networkRequestHeaders: ["Cache-Control", "X-Request-ID"],
  networkResponseHeaders: ["Referrer-Policy", "X-Trace-ID"],
});

Constraints:

• Bodies are truncated to 150,000 characters maximum
• networkDetailDenyUrls takes precedence over networkDetailAllowUrls
• Set networkCaptureBodies: false to keep header capture while disabling body capture

---

Canvas Recording

Canvas elements are not captured by default. Add replayCanvasIntegration() to enable:

import * as Sentry from "@sentry/browser";

Sentry.init({
  dsn: "___PUBLIC_DSN___",
  replaysSessionSampleRate: 0.1,
  replaysOnErrorSampleRate: 1.0,
  integrations: [
    Sentry.replayIntegration(),
    Sentry.replayCanvasIntegration(),
  ],
});

⚠️ There is currently no PII scrubbing in canvas recordings. Review canvas content carefully before enabling.

3D / WebGL Canvases — Manual Snapshot Mode

For WebGL or 3D canvases, use manual snapshotting to optimize performance:

Sentry.replayCanvasIntegration({
  enableManualSnapshot: true,
});

// Call in your render loop to capture the canvas
function paint() {
  const canvasRef = document.querySelector("#my-canvas");
  Sentry.getClient()
    ?.getIntegrationByName("ReplayCanvas")
    ?.snapshot(canvasRef);
}

WebGPU Canvases

Sentry.replayCanvasIntegration({
  enableManualSnapshot: true,
});

function paint() {
  const canvasRef = document.querySelector("#my-canvas");
  const canvasIntegration =
    Sentry.getClient()?.getIntegrationByName("ReplayCanvas");

  canvasIntegration?.snapshot(canvasRef, {
    skipRequestAnimationFrame: true,
  });
}

---

Lazy Loading

Defer loading the Replay bundle to avoid impacting initial page load:

// Initialize Sentry without Replay
Sentry.init({
  dsn: "___PUBLIC_DSN___",
  integrations: [],
});

// Lazy-load Replay later (e.g., after user interaction or route change)
import("@sentry/browser").then((lazySentry) => {
  Sentry.addIntegration(lazySentry.replayIntegration({
    maskAllText: true,
    blockAllMedia: true,
  }));
});

For Loader Script users (CDN), use lazyLoadIntegration:

window.sentryOnLoad = function () {
  Sentry.init({ dsn: "___PUBLIC_DSN___" });

  Sentry.lazyLoadIntegration("replayIntegration")
    .then((replayIntegration) => {
      Sentry.addIntegration(replayIntegration());
    })
    .catch(() => {
      // Network error — Replay not enabled
    });
};

---

Session Modes & Manual Control

Session Initialization Modes

Session mode: sessions end after 15 minutes of inactivity or 60 minutes maximum duration, then reinitialize.

Buffer mode: stores ~2–5 MB in memory (lightweight DOM event logs: clicks, scrolls, mutations — not video files). On sampled error, the 60-second buffer + subsequent recording are uploaded.

---

Manual Session Control API

Sentry.init({
  dsn: "___PUBLIC_DSN___",
  replaysSessionSampleRate: 0,
  replaysOnErrorSampleRate: 0,
  integrations: [Sentry.replayIntegration()],
});

const replay = Sentry.getReplay();

replay.start();           // Start recording in session mode
replay.startBuffering();  // Start recording in buffer mode

await replay.flush();     // Upload pending data (keeps recording active)
await replay.stop();      // Flush data and end session permanently

const replayId = replay.getReplayId(); // Get current replay ID for external linking

---

Deferred Initialization (External Sampling Service)

Use when you want to determine sampling rates via an external feature flag service before starting the SDK:

async function initReplay(sessionSampleRate, errorSampleRate) {
  const client = Sentry.getClient();
  const options = client.getOptions();
  options.replaysSessionSampleRate = sessionSampleRate;
  options.replaysOnErrorSampleRate = errorSampleRate;

  const replay = Sentry.replayIntegration({
    maskAllText: true,
    blockAllMedia: true,
  });

  client.addIntegration(replay);
}

// Call after fetching remote config
fetchFeatureFlags().then((flags) => {
  initReplay(flags.replaySessionRate, flags.replayErrorRate);
});

---

Custom Sampling Patterns

Employee-only recordings:

Sentry.init({
  dsn: "___PUBLIC_DSN___",
  replaysSessionSampleRate: 0.1,
  replaysOnErrorSampleRate: 1.0,
  integrations: [Sentry.replayIntegration()],
});

// Force-flush replay for internal employees
if (loggedInUser.isEmployee) {
  const replay = Sentry.getReplay();
  replay.flush();
}

URL-specific recording:

Sentry.init({
  dsn: "___PUBLIC_DSN___",
  replaysSessionSampleRate: 0,
  replaysOnErrorSampleRate: 0,
  integrations: [Sentry.replayIntegration()],
});

navigation.addEventListener("navigate", (event) => {
  const url = new URL(event.destination.url);
  const replay = Sentry.getReplay();
  if (url.pathname.startsWith("/checkout/")) {
    replay.start();
  } else {
    replay.stop();
  }
});

Error filtering in buffer mode:

Sentry.replayIntegration({
  beforeErrorSampling: (event) => {
    // Skip replay capture for this specific error type
    return !event.exception?.values?.[0]?.value?.includes("drop me");
  },
});

---

Support Widget Integration

Link replay sessions to support tickets:

Sentry.init({
  dsn: "___PUBLIC_DSN___",
  replaysSessionSampleRate: 0.1,
  replaysOnErrorSampleRate: 0.5,
  integrations: [Sentry.replayIntegration()],
});

MySupportWidget.on("open", async () => {
  const replay = Sentry.getReplay();
  await replay.flush();
  const replayId = replay.getReplayId();

  MySupportWidget.setTag("replayId", replayId);
  // Replay URL format:
  // https://<org-slug>.sentry.io/replays/<replay-id>/
});

---

Performance Impact

Buffer Mode is Lightweight

Buffer mode stores ~2–5 MB in memory — these are DOM event logs (clicks, scrolls, mutations), not video files. The real-time encoding is handled by a WebWorker.

Mutation Limits

Protect against performance degradation from excessive DOM mutations:

Sentry.replayIntegration({
  mutationBreadcrumbLimit: 1000, // Emit breadcrumb warning at this threshold
  mutationLimit: 1500,           // Stop recording at this threshold
});

Custom Compression Worker

Reduces bundle size and avoids CSP violations by self-hosting the compression worker:

Sentry.replayIntegration({
  workerUrl: "/assets/sentry-replay-worker.min.js",
});

Bundler plugin optimization (excludes worker from main bundle):

sentryVitePlugin({
  bundleSizeOptimizations: {
    excludeReplayWorker: true,
  },
});

Content Security Policy

Session Replay uses a WebWorker for compression. Add to your CSP:

worker-src 'self' blob:;
child-src 'self' blob:;

Safari ≤15.4 requires child-src. Use a self-hosted workerUrl as an alternative.

---

Best Practices

• Keep `replaysOnErrorSampleRate` at `1.0` — error sessions are the highest value for debugging.
• Use `maskAllText: true` in production — default behavior, protects PII. Only disable for internal tools.
• Opt-in to network details explicitly — set networkDetailAllowUrls only for your own API origins, not third-party services.
• Never enable `replayCanvasIntegration` without reviewing canvas content — there is no automatic PII scrubbing for canvas.
• Test masking before deploying — use replaysSessionSampleRate: 1.0 in staging and review replays to verify PII is hidden.
• Use `workerUrl` to self-host the compression worker if you have strict CSP or want to reduce bundle size.
• Use `beforeAddRecordingEvent` to filter out high-frequency recording events that don't add debugging value.
• Set `minReplayDuration` to avoid sending trivially short sessions (default: 5s is usually fine).

---

Troubleshooting

Tracing — Sentry Browser SDK

Minimum SDK: @sentry/browser ≥7.0.0

enableInp defaults to true as of SDK ≥8.0.0 (was false in 7.x)

enableLongAnimationFrame available since SDK ≥8.18.0

inheritOrSampleWith in tracesSampler available since SDK ≥9.0.0

profileSessionSampleRate replaces profilesSampleRate as of SDK ≥10.27.0

---

Minimal Setup

import * as Sentry from "@sentry/browser";

Sentry.init({
  dsn: "___PUBLIC_DSN___",
  integrations: [Sentry.browserTracingIntegration()],
  tracesSampleRate: 0.2, // Capture 20% of all transactions
});

Disabling tracing: Omit both tracesSampleRate and tracesSampler. Setting tracesSampleRate: 0 does not disable tracing — it simply never sends any traces.

---

browserTracingIntegration() — Configuration Reference

All options are passed as a single object to browserTracingIntegration().

Page Load & Navigation

HTTP Request Instrumentation

Interaction & Long Task Instrumentation

Timing & Timeouts

Propagation & Filtering

Full Configuration Example

import * as Sentry from "@sentry/browser";

Sentry.init({
  dsn: "___PUBLIC_DSN___",
  integrations: [
    Sentry.browserTracingIntegration({
      // Page / navigation spans
      instrumentPageLoad: true,
      instrumentNavigation: true,
      markBackgroundSpan: true,
      linkPreviousTrace: "in-memory",

      // HTTP spans
      traceFetch: true,
      traceXHR: true,
      enableHTTPTimings: true,
      shouldCreateSpanForRequest: (url) => !url.match(/\/health\/?$/),

      // INP / long-task spans
      enableInp: true,
      interactionsSampleRate: 0.5,
      enableLongTask: true,
      enableLongAnimationFrame: true,

      // Timeouts
      idleTimeout: 1000,
      finalTimeout: 30000,
      childSpanTimeout: 15000,

      // Propagation
      tracePropagationTargets: ["localhost", /^https:\/\/api\.yourapp\.com/],

      // Normalise dynamic URL segments in transaction names
      beforeStartSpan: (context) => ({
        ...context,
        name: location.pathname
          .replace(/\/[a-f0-9]{32}/g, "/<hash>")
          .replace(/\/\d+/g, "/<id>"),
      }),
    }),
  ],
  tracesSampleRate: 1.0,
});

---

Automatic Instrumentation

When browserTracingIntegration() is active, the following are captured automatically:

Page Loads

A root pageload span covers the full page-load lifecycle. Child spans are attached for:

• Web Vitals: LCP, CLS, TTFB
• Resource loads: CSS, JS, images, fonts (each as a resource.* child span)
• HTTP requests made during load

Navigations (SPA Route Changes)

Each client-side route change (via the History API) produces a new navigation root span, along with any HTTP requests and web vitals captured during that navigation.

Fetch / XHR Requests

Every outgoing fetch or XMLHttpRequest produces an http.client child span containing: request duration, HTTP status code, and URL.

Use shouldCreateSpanForRequest to exclude URLs you don't want traced:

Sentry.browserTracingIntegration({
  shouldCreateSpanForRequest: (url) => {
    return !url.includes("/health") && !url.includes("/metrics");
  },
});

Web Vitals

Long Tasks

Main-thread tasks blocking the browser for more than 50 ms are recorded as ui.long-task child spans.

Custom Router Integration

To integrate with a router that manages its own history, disable automatic span creation and call the low-level helpers directly:

const client = Sentry.init({
  integrations: [
    Sentry.browserTracingIntegration({
      instrumentNavigation: false,
      instrumentPageLoad: false,
    }),
  ],
});

// Initial page load
let pageLoadSpan = Sentry.startBrowserTracingPageLoadSpan(client, {
  name: window.location.pathname,
  attributes: {
    [Sentry.SEMANTIC_ATTRIBUTE_SENTRY_SOURCE]: "url",
  },
});

myRouter.on("routeChange", (route) => {
  if (pageLoadSpan) {
    // Update the name of the in-flight page-load span
    pageLoadSpan.updateName(route.name);
    pageLoadSpan.setAttribute(Sentry.SEMANTIC_ATTRIBUTE_SENTRY_SOURCE, "route");
    pageLoadSpan = undefined;
  } else {
    // Start a navigation span for subsequent route changes
    Sentry.startBrowserTracingNavigationSpan(client, {
      op: "navigation",
      name: route.name,
      attributes: {
        [Sentry.SEMANTIC_ATTRIBUTE_SENTRY_SOURCE]: "route",
      },
    });
  }
});

---

Custom Spans

Three functions are available for manual instrumentation. All accept the same options object.

startSpan(options, callback) — Auto-ending Span (Recommended)

Creates an active span that ends automatically when the callback returns (sync or async).

// Synchronous
const result = Sentry.startSpan({ name: "process-checkout", op: "function" }, () => {
  return processCheckoutData();
});

// Asynchronous
const data = await Sentry.startSpan(
  { name: "fetch-user-profile", op: "http.client" },
  async () => {
    const response = await fetch("/api/user/profile");
    return response.json();
  }
);

// With attributes
const result = await Sentry.startSpan(
  {
    name: "query-products",
    op: "db",
    attributes: {
      "db.system": "postgresql",
      "db.table": "products",
      "db.query.count": 50,
    },
  },
  () => db.query("SELECT * FROM products LIMIT 50")
);

---

startSpanManual(options, callback) — Manually-ended Active Span

Creates an active span that must be ended explicitly by calling span.end(). Use when the span's end is decoupled from the callback's return (e.g., event-driven code).

function attachUploadTracing(input) {
  input.addEventListener("change", (event) => {
    Sentry.startSpanManual({ name: "file-upload", op: "file.upload" }, (span) => {
      const file = event.target.files[0];
      span.setAttribute("file.size", file.size);
      span.setAttribute("file.type", file.type);

      const upload = uploadFile(file);
      upload.on("complete", () => {
        span.setStatus({ code: 1 }); // ok
        span.end();
      });
      upload.on("error", (err) => {
        span.setStatus({ code: 2 }); // error
        span.end();
      });
    });
  });
}

---

startInactiveSpan(options) — Manually-ended Inactive Span

Creates a span that is not set as the active span. Useful for parallel work sharing a common parent.

const span1 = Sentry.startInactiveSpan({ name: "task-a", op: "function" });
const span2 = Sentry.startInactiveSpan({ name: "task-b", op: "function" });

await Promise.all([workA(), workB()]);

span1.end();
span2.end();

---

Span Options

---

Operation Types

Use well-known op values so the Sentry UI presents appropriate icons and filtering:

---

Working with Span Attributes and Status

// Set attributes at creation
Sentry.startSpan(
  {
    name: "process-payment",
    attributes: { "payment.provider": "stripe", "payment.amount": 9999 },
  },
  () => processPayment()
);

// On an existing span
const span = Sentry.getActiveSpan();
if (span) {
  span.setAttribute("key", "value");
  span.setAttributes({ key1: "val1", key2: 42 });
}

// Update span name (SDK ≥8.47.0)
Sentry.updateSpanName(span, "New Name");

// Set span status
span.setStatus({ code: 1 }); // 0 = unknown, 1 = ok, 2 = error
span.setHttpStatus(404);

---

Distributed Tracing

Distributed tracing connects browser activity to backend requests, enabling a single timeline across services.

How It Works

Sentry propagates two HTTP headers on every outgoing request matching tracePropagationTargets:

CORS: Both headers must be added to your server's Access-Control-Allow-Headers — otherwise browsers or gateways will strip them.

tracePropagationTargets Configuration

Sentry.init({
  dsn: "___PUBLIC_DSN___",
  integrations: [Sentry.browserTracingIntegration()],
  tracesSampleRate: 1.0,
  tracePropagationTargets: [
    "localhost",
    /^https:\/\/api\.yourapp\.com/,
  ],
});

Rules:

• String entries = exact substring match against the full URL
• RegExp entries = tested against the full URL (including scheme and port)
• Port numbers matter — a service on port 8080 requires a separate entry
• Set to [] to disable header propagation entirely

Common patterns:

// E-commerce with multiple backend services
tracePropagationTargets: [
  "https://api.myecommerce.com",
  "https://auth.myecommerce.com",
];

// Mixed absolute URLs and relative API paths
tracePropagationTargets: [
  "https://api.myapp.com",
  /^\/api\//,
];

// Disable all header propagation
tracePropagationTargets: [];

---

Continuing a Server-Initiated Trace

When your server renders the HTML, emit the current trace context as <meta> tags. The browserTracingIntegration reads them automatically on page load and continues the same trace:

<meta name="sentry-trace"
  content="12345678901234567890123456789012-1234567890123456-1" />
<meta name="baggage"
  content="sentry-trace_id=12345678901234567890123456789012,sentry-environment=production,sentry-sample_rate=1" />

---

Manual Trace Propagation (Non-HTTP Channels)

For WebSockets, message queues, or any non-HTTP transport:

const traceData = Sentry.getTraceData();

webSocket.send(
  JSON.stringify({
    payload: myData,
    metadata: {
      sentryTrace: traceData["sentry-trace"],
      baggage: traceData["baggage"],
    },
  })
);

---

Sampling

tracesSampleRate — Uniform Sampling

Sentry.init({
  tracesSampleRate: 0.2, // Sample 20% of transactions
});

• Range: 0 – 1 (random, uniform percentage)
• 0 = send no traces (tracing is still "active"; omit both options to fully disable)
• 1 = send 100% of traces

tracesSampler — Dynamic / Context-Aware Sampling

A function that receives a SamplingContext and returns a sample rate (0–1) or a boolean.

Sentry.init({
  tracesSampler: ({ name, attributes, inheritOrSampleWith }) => {
    // Never sample health checks
    if (name.includes("healthcheck") || name.includes("/health")) return 0;

    // Always sample authentication flows
    if (name.includes("auth") || name.includes("login")) return 1;

    // Sample checkout at high rate (business critical)
    if (name.includes("checkout")) return 0.5;

    // For everything else, inherit the parent's decision or default to 20%
    return inheritOrSampleWith(0.2);
  },
});

SamplingContext Properties

Sampling Precedence

1. `tracesSampler` — highest priority (if defined) 2. Parent sampling decision — used when no sampler is defined but a parent trace exists 3. `tracesSampleRate` — fallback uniform rate

INP-Specific Sampling

interactionsSampleRate applies an additional multiplier on top of tracesSampleRate for INP interaction spans:

Sentry.init({
  tracesSampleRate: 0.5,
  integrations: [
    Sentry.browserTracingIntegration({
      enableInp: true,
      interactionsSampleRate: 0.1, // Effective rate: 50% × 10% = 5% of interactions
    }),
  ],
});

---

Best Practices

• Set `tracePropagationTargets` explicitly — the default (localhost + /) is rarely correct for production. Define your API origins precisely.
• Use `beforeStartSpan` to normalize transaction names — avoid high cardinality from dynamic URLs (/users/123 → /users/<id>).
• Use `shouldCreateSpanForRequest` to exclude noise — skip health checks, analytics pixels, and third-party beacons.
• Prefer `startSpan` over `startInactiveSpan` — the auto-ending behavior prevents runaway spans.
• Set `op` on custom spans — the Sentry UI uses op for icons, grouping, and performance charts.
• Use `inheritOrSampleWith` in `tracesSampler` — ensures sampling decisions are deterministically propagated from parent to child traces.
• Add CORS headers on your servers — sentry-trace and baggage must be in Access-Control-Allow-Headers and Access-Control-Expose-Headers.
• Tune `idleTimeout` for your SPA — if your navigation transitions are slow (>1s), increase idleTimeout to avoid premature span termination.

---

Troubleshooting

User Feedback — Sentry Browser SDK

Minimum SDK: @sentry/browser ≥7.85.0 for feedbackIntegration()

Screenshot capture: requires ≥8.0.0

Self-hosted Sentry: requires version ≥24.4.2

---

Two Approaches

Both approaches can be used together. The widget is general-purpose; the crash modal is specifically for error-linked feedback.

---

Approach 1: Feedback Widget (feedbackIntegration)

Basic Setup

import * as Sentry from "@sentry/browser";

Sentry.init({
  dsn: "___PUBLIC_DSN___",
  integrations: [
    Sentry.feedbackIntegration({
      colorScheme: "system", // "light" | "dark" | "system"
    }),
  ],
});

A "Report a Bug" button appears in the bottom-right corner by default. Clicking it opens a modal form.

Lazy Loading via Loader Script

window.sentryOnLoad = function () {
  Sentry.init({ dsn: "___PUBLIC_DSN___" });

  Sentry.lazyLoadIntegration("feedbackIntegration")
    .then((feedbackIntegration) => {
      Sentry.addIntegration(
        feedbackIntegration({
          colorScheme: "system",
        }),
      );
    })
    .catch(() => {
      // Network error — User Feedback widget not loaded
    });
};

CDN Bundle Options

<!-- Feedback only (lightest bundle) -->
<script
  src="https://browser.sentry-cdn.com/10.42.0/bundle.feedback.min.js"
  crossorigin="anonymous"
></script>

<!-- With tracing and replay -->
<script
  src="https://browser.sentry-cdn.com/10.42.0/bundle.tracing.replay.feedback.min.js"
  crossorigin="anonymous"
></script>

Configuration Options

Appearance

Form Fields

Positioning

Behaviour

Pre-fill User Information

Sentry.init({
  dsn: "___PUBLIC_DSN___",
  integrations: [
    Sentry.feedbackIntegration({
      // Pre-fill form with logged-in user's details
    }),
  ],
});

// After authentication
Sentry.setUser({
  email: "user@example.com",
  name: "Jane Smith",
});

When Sentry.setUser() is called, the feedback form auto-populates name and email fields.

Manual Widget Control (Custom Button)

Disable auto-inject and open the widget programmatically from your own button:

Sentry.init({
  dsn: "___PUBLIC_DSN___",
  integrations: [
    Sentry.feedbackIntegration({
      autoInject: false, // Don't render Sentry's trigger button
    }),
  ],
});

// Open the widget from your own UI element
document.getElementById("my-feedback-btn").addEventListener("click", () => {
  const feedback = Sentry.getFeedback();
  if (feedback) {
    feedback.openDialog();
  }
});

---

Approach 2: Programmatic Feedback (captureFeedback)

Use a completely custom form UI and submit feedback via the API:

// Minimal — only message is required
Sentry.captureFeedback({
  name: "Jane Smith",
  email: "jane@example.com",
  message: "The checkout button doesn't work on mobile.",
});

With Tags and Attachments

// Attach a screenshot as a file
const screenshotDataUrl = "data:image/jpeg;base64,...";
const res = await fetch(screenshotDataUrl);
const buffer = await res.arrayBuffer();

Sentry.captureFeedback(
  {
    name: "Jane Smith",
    email: "jane@example.com",
    message: "The checkout button doesn't work on mobile.",
  },
  {
    captureContext: {
      tags: { page: "checkout", device: "mobile" },
    },
    attachments: [
      {
        filename: "screenshot.png",
        data: new Uint8Array(buffer),
      },
    ],
  },
);

Linking Feedback to a Specific Error

try {
  await submitOrder();
} catch (err) {
  const eventId = Sentry.captureException(err);

  Sentry.captureFeedback({
    message: "Something went wrong during checkout.",
    associatedEventId: eventId, // Links this feedback to the captured error
  });
}

captureFeedback Parameters

---

Approach 3: Crash-Report Modal (showReportDialog)

Show a modal prompting users to describe what happened when an error occurs. Ideal for "something went wrong" pages or after unhandled errors.

Basic Setup

Sentry.init({
  dsn: "___PUBLIC_DSN___",
  beforeSend(event) {
    if (event.exception && event.event_id) {
      Sentry.showReportDialog({ eventId: event.event_id });
    }
    return event;
  },
});

On a 500 Error Page

<script>
  Sentry.init({ dsn: "___PUBLIC_DSN___" });
</script>

<script>
  // eventId is provided by your server-side Sentry SDK after capturing the error
  Sentry.showReportDialog({ eventId: "{{ sentry_event_id }}" });
</script>

After Manual captureException

try {
  await riskyOperation();
} catch (err) {
  const eventId = Sentry.captureException(err);
  Sentry.showReportDialog({ eventId });
}

showReportDialog Options

The modal collects: user name, email, and a description — paired with the original captured error event.

---

Screenshot Capture

• Available on SDK v8.0.0+
• Enabled by default via enableScreenshot: true on feedbackIntegration()
• Auto-hidden on mobile devices
• Screenshots count against your attachment quota (1GB standard)

Sentry.feedbackIntegration({
  enableScreenshot: true, // default — can set false to disable
});

---

Session Replay Integration

When Session Replay is configured alongside User Feedback, submitted feedback links to the user's replay:

Sentry.init({
  dsn: "___PUBLIC_DSN___",
  replaysOnErrorSampleRate: 1.0, // Buffer replays for error sessions
  integrations: [
    Sentry.replayIntegration(),
    Sentry.feedbackIntegration({ colorScheme: "system" }),
  ],
});

The system buffers up to 30 seconds when the feedback widget opens. This enables viewing the replay alongside the submitted feedback in Sentry.

---

Best Practices

• Use `feedbackIntegration()` for proactive collection — don't wait for errors; a persistent feedback button catches issues that never throw exceptions
• Pre-fill user info — call Sentry.setUser() after login so users don't have to type their email each time
• Combine crash modal with `beforeSend` — automatic prompting after errors maximizes feedback capture
• Link programmatic feedback to events — use associatedEventId so feedback appears alongside error context in Sentry
• Set `autoInject: false` for branded UI — implement your own trigger button to match your design system
• Keep `showReportDialog` for 500 pages — server-rendered error pages are the primary use case; pass the server-side event ID to the client

---

Troubleshooting