@danieljvdm/dev-kit 1.0.2 → 2.0.0

package/skills/sentry/references/sdks/svelte/logging.md

@@ -0,0 +1,344 @@
+# Logging — Sentry Svelte/SvelteKit SDK
+
+> Minimum SDK: `@sentry/sveltekit` ≥9.41.0+ / `@sentry/svelte` ≥9.41.0+ for
+> `Sentry.logger` API\
+> `consoleLoggingIntegration()`: requires ≥10.13.0+\
+> Scope-based attribute setters (`getIsolationScope`, `getGlobalScope`): requires
+> ≥10.32.0+
+
+> ⚠️ **Not available via CDN/loader snippet** — NPM install required.
+
+---
+
+## Enabling Logs
+
+`enableLogs` is opt-in.
+Add it to every `Sentry.init()` call where you want logs captured.
+
+### SvelteKit — both files
+
+```typescript
+// src/instrumentation.server.ts (or hooks.server.ts for legacy)
+import * as Sentry from "@sentry/sveltekit";
+
+Sentry.init({
+  dsn: process.env.SENTRY_DSN,
+  enableLogs: true,
+});
+```
+
+```typescript
+// src/hooks.client.ts
+import * as Sentry from "@sentry/sveltekit";
+
+Sentry.init({
+  dsn: import.meta.env.PUBLIC_SENTRY_DSN ?? import.meta.env.VITE_SENTRY_DSN,
+  enableLogs: true,
+});
+
+export const handleError = Sentry.handleErrorWithSentry();
+```
+
+### Standalone Svelte — main.ts
+
+```typescript
+import * as Sentry from "@sentry/svelte";
+
+Sentry.init({
+  dsn: import.meta.env.VITE_SENTRY_DSN,
+  enableLogs: true,
+});
+```
+
+---
+
+## Logger API — Six Levels
+
+```typescript
+import * as Sentry from "@sentry/sveltekit"; // or "@sentry/svelte"
+
+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", port: 5432 });
+```
+
+| Level   | Intent                                                                  |
+| ------- | ----------------------------------------------------------------------- |
+| `trace` | Fine-grained debugging, high-volume — filter aggressively in production |
+| `debug` | Development diagnostics                                                 |
+| `info`  | Normal operations, business milestones                                  |
+| `warn`  | Degraded state, near-limit conditions                                   |
+| `error` | Failures requiring attention                                            |
+| `fatal` | Critical failures, system-down conditions                               |
+
+**Attribute value types:** `string`, `number`, `boolean` only.
+
+---
+
+## Parameterized Messages (`logger.fmt`)
+
+Use `logger.fmt` tagged template literals to bind variables as **structured, searchable
+attributes** in Sentry:
+
+```typescript
+const userId = "user_123";
+const productName = "Widget Pro";
+const amount = 49.99;
+
+Sentry.logger.info(Sentry.logger.fmt`User ${userId} purchased ${productName} for $${amount}`);
+```
+
+Results in:
+
+```
+message.template:     "User %s purchased %s for $%s"
+message.parameter.0:  "user_123"
+message.parameter.1:  "Widget Pro"
+message.parameter.2:  49.99
+```
+
+This allows filtering in Sentry by any individual parameter value, not just the full
+message string.
+
+---
+
+## Console Capture Integration
+
+Automatically forwards `console.*` calls to Sentry as structured logs.
+Requires SDK ≥10.13.0.
+
+```typescript
+Sentry.init({
+  dsn: "...",
+  enableLogs: true,
+  integrations: [
+    Sentry.consoleLoggingIntegration({
+      levels: ["log", "warn", "error"], // which console levels to forward
+    }),
+  ],
+});
+
+// These are now automatically sent to Sentry:
+console.log("User action", { userId: 123, action: "checkout" });
+console.warn("High memory usage", 85, "%");
+console.error("Fetch failed", new Error("timeout"));
+```
+
+`console.log("Text", 123, true)` → `message.parameter.0 = 123`,
+`message.parameter.1 = true`
+
+### Consola integration (SvelteKit server-side)
+
+For apps using the `consola` logging library (common in SvelteKit SSR):
+
+```typescript
+// SDK >= 10.12.0
+import consola from "consola";
+import * as Sentry from "@sentry/sveltekit";
+
+const reporter = Sentry.createConsolaReporter();
+consola.addReporter(reporter);
+```
+
+---
+
+## Scope-Based Automatic Attributes (SDK ≥10.32.0)
+
+Attributes set on scopes are **automatically added to all subsequent logs** within that
+scope — no need to repeat them on every log call.
+
+### Global scope (process lifetime)
+
+```typescript
+// Set once at startup — applies everywhere, client and server
+Sentry.getGlobalScope().setAttributes({
+  service: "checkout-service",
+  version: "2.1.0",
+  region: "us-east-1",
+});
+```
+
+### Isolation scope (per-request in SvelteKit)
+
+SvelteKit creates a new isolation scope per server request.
+Set per-request context here:
+
+```typescript
+// src/hooks.server.ts — enrich every server log with request context
+import * as Sentry from "@sentry/sveltekit";
+import { sequence } from "@sveltejs/kit/hooks";
+
+export const handle = sequence(Sentry.sentryHandle(), async ({ event, resolve }) => {
+  Sentry.getIsolationScope().setAttributes({
+    org_id: event.locals.user?.orgId,
+    user_tier: event.locals.user?.tier,
+    request_id: event.request.headers.get("x-request-id") ?? undefined,
+  });
+  return resolve(event);
+});
+```
+
+### Current scope (narrowest, single operation)
+
+```typescript
+Sentry.withScope((scope) => {
+  scope.setAttribute("order_id", "ord_789");
+  scope.setAttribute("payment_method", "stripe");
+  Sentry.logger.info("Processing payment", { amount: 49.99 });
+  // order_id and payment_method are included in this log only
+});
+```
+
+---
+
+## Log Filtering with `beforeSendLog`
+
+```typescript
+Sentry.init({
+  dsn: "...",
+  enableLogs: true,
+  beforeSendLog: (log) => {
+    // Drop debug logs in production
+    if (log.level === "debug" || log.level === "trace") return null;
+
+    // Scrub sensitive attribute keys
+    if (log.attributes?.password) {
+      delete log.attributes.password;
+    }
+    if (log.attributes?.["credit_card"]) {
+      log.attributes["credit_card"] = "[REDACTED]";
+    }
+
+    // Drop health-check noise
+    if (log.attributes?.["http.target"] === "/health") return null;
+
+    return log;
+  },
+});
+```
+
+---
+
+## Auto-Generated Attributes
+
+The SDK adds these to every log without any developer action:
+
+| Attribute                                 | Source                         | Notes                                                          |
+| ----------------------------------------- | ------------------------------ | -------------------------------------------------------------- |
+| `environment`                             | `Sentry.init({ environment })` | —                                                              |
+| `release`                                 | `Sentry.init({ release })`     | —                                                              |
+| `sdk.name`, `sdk.version`                 | SDK internals                  | —                                                              |
+| `browser.name`, `browser.version`         | User-Agent                     | Client-side only                                               |
+| `user.id`, `user.name`, `user.email`      | `Sentry.setUser()`             | When `dataCollection.userInfo: true` (default in SDK ≥10.57.0) |
+| `sentry.trace.parent_span_id`             | Active tracing span            | If tracing is enabled                                          |
+| `sentry.replay_id`                        | Active replay session          | If Session Replay is enabled                                   |
+| `message.template`, `message.parameter.X` | `logger.fmt` usage             | —                                                              |
+| `sentry.origin`                           | Integration-generated logs     | —                                                              |
+
+---
+
+## Trace + Log Correlation
+
+When tracing is enabled alongside logging, logs are **automatically linked** to the
+current trace:
+
+```typescript
+Sentry.init({
+  dsn: "...",
+  enableLogs: true,
+  tracesSampleRate: 1.0,
+  integrations: [Sentry.browserTracingIntegration()],
+});
+
+// Inside an active span, logs get sentry.trace.parent_span_id automatically
+await Sentry.startSpan({ name: "process-order", op: "task" }, async () => {
+  Sentry.logger.info("Validating cart", { cartId: "cart_abc" });
+  // ^ this log is linked to the "process-order" span in Sentry UI
+  await validateCart();
+  Sentry.logger.info("Payment initiated", { gateway: "stripe" });
+});
+```
+
+Navigate from log → parent span, or from span → correlated logs, in the Sentry UI.
+
+---
+
+## SvelteKit Server-Side Logging
+
+On the server side, `enableLogs: true` in `instrumentation.server.ts` enables
+`Sentry.logger.*` in:
+
+- `hooks.server.ts` handle functions
+- `+page.server.ts` / `+layout.server.ts` load functions
+- API routes (`+server.ts`)
+
+```typescript
+// src/routes/api/orders/+server.ts
+import * as Sentry from "@sentry/sveltekit";
+import { json } from "@sveltejs/kit";
+
+export const POST = async ({ request }) => {
+  const body = await request.json();
+
+  Sentry.logger.info(Sentry.logger.fmt`Creating order for user ${body.userId}`);
+
+  try {
+    const order = await createOrder(body);
+    Sentry.logger.info("Order created", { orderId: order.id, total: order.total });
+    return json(order, { status: 201 });
+  } catch (err) {
+    Sentry.logger.error("Order creation failed", {
+      userId: body.userId,
+      reason: (err as Error).message,
+    });
+    throw err;
+  }
+};
+```
+
+---
+
+## Svelte vs SvelteKit: Key Differences
+
+| Concern                     | Standalone Svelte     | SvelteKit                                            |
+| --------------------------- | --------------------- | ---------------------------------------------------- |
+| `enableLogs` location       | Single `main.ts` init | Both `hooks.client.ts` + `instrumentation.server.ts` |
+| Server-side logging         | ❌ N/A                | ✅ Full — `Sentry.logger.*` in any server code       |
+| Isolation scope per request | ❌ N/A                | ✅ Set in `hooks.server.ts` for per-request context  |
+| `consoleLoggingIntegration` | Single init           | Both client and server inits                         |
+| `consola` reporter          | N/A (client-only)     | Server hooks or load functions                       |
+| Trace correlation           | Client spans only     | Client + server spans                                |
+
+---
+
+## Best Practices
+
+- Add `enableLogs: true` to **both** `hooks.client.ts` and `instrumentation.server.ts`
+  in SvelteKit — logging is not shared between the two init calls
+- Use `Sentry.logger.fmt` for any log that includes a variable — enables search by value
+  in Sentry
+- Set global attributes (`getGlobalScope().setAttributes()`) for service-level metadata
+  (service name, version, region)
+- Use `getIsolationScope().setAttributes()` in `hooks.server.ts` to enrich all logs for
+  a given request
+- Use `beforeSendLog` to drop `trace`/`debug` logs in production to control volume
+- Avoid logging raw sensitive data even with `beforeSendLog` — filter at the call site
+  when possible
+
+---
+
+## Troubleshooting
+
+| Issue                                        | Solution                                                                                             |
+| -------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| Logs not appearing in Sentry                 | Check `enableLogs: true` is set; logs require SDK ≥9.41.0                                            |
+| Server logs missing, client logs present     | Add `enableLogs: true` to `instrumentation.server.ts` (separate init from client)                    |
+| `logger.fmt` not creating parameters         | Ensure you’re calling `Sentry.logger.fmt` as a tagged template — not a function call                 |
+| Too many log entries (noise)                 | Use `beforeSendLog` to filter by level; increase `trace`/`debug` filter in production                |
+| Logs not linked to traces                    | Ensure tracing is enabled and active span exists when log is called                                  |
+| `consoleLoggingIntegration` requires upgrade | Upgrade to `@sentry/sveltekit` ≥10.13.0                                                              |
+| Scope attributes not appearing               | Upgrade to ≥10.32.0 for `getGlobalScope`/`getIsolationScope` APIs                                    |
+| Log attributes contain `undefined`           | Sentry only accepts `string \| number \| boolean` attribute values — filter undefined before passing |