Sentry Browser Sdk

# 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:

| Layer | Mechanism | Integration |
|-------|-----------|-------------|
| Uncaught synchronous exceptions | `window.onerror` | `globalHandlersIntegration` (default on) |
| Unhandled promise rejections | `window.onunhandledrejection` | `globalHandlersIntegration` (default on) |
| Errors in `setTimeout` / `setInterval` / `requestAnimationFrame` / `addEventListener` | Patched browser APIs | `browserApiErrorsIntegration` (default on) |
| Console errors (optional) | Patched `console.error` | `captureConsoleIntegration` (opt-in) |

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

```javascript
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:**

| Field | Type | Description |
|-------|------|-------------|
| `level` | `"fatal" \| "error" \| "warning" \| "log" \| "info" \| "debug"` | Severity override for this event |
| `tags` | `Record<string, string>` | Indexed, filterable key-value pairs |
| `extra` | `Record<string, unknown>` | Unindexed supplementary data |
| `user` | `{ id?, email?, username?, ip_address? }` | User identity |
| `contexts` | `Record<string, Record<string, unknown>>` | Named structured context blocks |
| `fingerprint` | `string[]` | Custom issue grouping key |

---

### `Sentry.captureMessage(message, levelOrContext?)`

Captures a plain-text message as a Sentry issue.

```javascript
// 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.

```javascript
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"],
});
```

---

#