Sentry Svelte Sdk

# Error Monitoring — Sentry Svelte/SvelteKit SDK

> Minimum SDK: `@sentry/sveltekit` ≥7.0.0+ / `@sentry/svelte` ≥7.0.0+

---

## How Automatic Capture Works

| Layer | Mechanism | Fires when... |
|-------|-----------|---------------|
| **Client (both)** | `globalHandlersIntegration` | `window.onerror`, unhandled `Promise` rejections |
| **Client (both)** | `browserApiErrorsIntegration` | Errors thrown in `setTimeout`, `setInterval`, `requestAnimationFrame` |
| **Server (SvelteKit)** | `handleErrorWithSentry()` in `hooks.server.ts` | Any unhandled error in a server hook, load function, or route handler |
| **Server (SvelteKit)** | `sentryHandle()` | Instruments incoming requests; captures errors from the request pipeline |
| **Client (SvelteKit)** | `handleErrorWithSentry()` in `hooks.client.ts` | Any unhandled navigation or client-side error SvelteKit surfaces |

No configuration beyond the `Sentry.init()` call is required for baseline error capture.

---

## SvelteKit Error Hooks

### `hooks.client.ts`

```typescript
import * as Sentry from "@sentry/sveltekit";

Sentry.init({ dsn: import.meta.env.VITE_SENTRY_DSN, sendDefaultPii: true });

// Sentry captures first; your handler runs after
const myErrorHandler = ({ error, event }: { error: unknown; event: unknown }) => {
  console.error("Client error:", error);
};

export const handleError = Sentry.handleErrorWithSentry(myErrorHandler);

// Works with no argument too:
// export const handleError = Sentry.handleErrorWithSentry();
```

### `hooks.server.ts`

```typescript
import * as Sentry from "@sentry/sveltekit";
import { sequence } from "@sveltejs/kit/hooks";

// Sentry.init() is in instrumentation.server.ts (modern) or here (legacy)

const myErrorHandler = ({ error, event }: { error: unknown; event: unknown }) => {
  console.error("Server error:", error);
};

export const handleError = Sentry.handleErrorWithSentry(myErrorHandler);

// sentryHandle() instruments requests and creates root spans
export const handle = Sentry.sentryHandle();

// Composing multiple handles:
// export const handle = sequence(Sentry.sentryHandle(), authHandle, logHandle);
```

### `handleErrorWithSentry()` callback signature

```typescript
export const handleError = Sentry.handleErrorWithSentry(
  (input: {
    error: unknown;
    event: RequestEvent | NavigationEvent;
    status?: number;
    message?: string;
  }) => {
    // Your logic runs AFTER Sentry has already captured the error
  }
);
```

---

## Manual Error Capture

```typescript
import * as Sentry from "@sentry/sveltekit"; // or "@sentry/svelte"

// Capture an Error object
try {
  await riskyOperation();
} catch (err) {
  Sentry.captureException(err);
}

// Capture with extra context
try {
  await riskyOperation();
} catch (err) {
  Sentry.captureException(err, {
    tags: { feature: "checkout", region: "eu" },
    extra: { cartId: "abc-123", itemCount: 3 },
    level: "error",   // "fatal" | "error" | "warning" | "info" | "debug"
  });
}

// Plain message (not tied to an exception)
Sentry.captureMessage("User exceeded rate limit", "warning");

// Isolated scope — doesn't pollute global state
Sentry.withScope((scope) => {
  scope.setTag("component", "PaymentForm");
  scope.setUser({ id: "42", email: "user@example.com" });
  Sentry.captureException(new Error("Payment failed"));
});
```

---

## Context Enrichment

### User Context

```typescript
// Set globally — persists until cleared
Sentry.setUser({
  id: "user-123",
  email: "jane@example.com",
  username: "jdoe",
  ip_address: "{{ auto }}",  // auto-infer from request
  plan: "enterprise",        // custom fields accepted
});

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

### Tags (searchable, indexed)

```typescript
Sentry.setTag("release.channel", "beta");
Sentry.setTags({
  "feature.flag": "new-checkout",
  region: "us-east-1",
  version: "2.1.0",
});
```

Key constraints: ≤32 chars, alphanumeric + `_`, `.`, `:`, `-`. Value: ≤200 chars, no newlines.

### Context Objects (structur