@warlock.js/logger 5.24.0 → 5.26.0

package/skills/redact-sensitive-log-fields/SKILL.md

@@ -1,156 +1,156 @@
----
-name: redact-sensitive-log-fields
-description: 'Strip secrets from log output — a built-in secret-key denylist on by default (DEFAULT_REDACT_KEYS), plus two-layer additive redaction via log.configure({redact: {paths, keys}}) (logger floor) + per-channel redact (more on top). Dotted glob paths (*, **). Triggers: `redact`, `paths`, `keys`, `defaultKeys`, `censor`, `log.setRedact`, `applyRedact`; "redact passwords in logs", "strip tokens from log output", "hide authorization headers", "scrub PII before logging", "turn off default redaction"; typical import `import { log } from "@warlock.js/logger"`. Skip: filtering — `@warlock.js/logger/filter-log-entries/SKILL.md`; custom sinks — `@warlock.js/logger/write-custom-log-channel/SKILL.md`; competing libs `pino.redact`, `fast-redact`.'
----
-
-# Redaction — keeping secrets out of logs
-
-Three layers: a **built-in key denylist that is on by default**, plus opt-in path globs configured at the logger and/or per channel.
-
-## Layer 0 — the default denylist (since 4.15.0, no configuration needed)
-
-Common secret **key names** are censored at any depth of `context`, `message`, and an `Error`'s own enumerable properties — before any of your config runs:
-
-```ts
-log.error("auth", "login", "failed", { headers: req.headers, body: req.body });
-// context.headers.authorization → "[REDACTED]"
-// context.body.password         → "[REDACTED]"
-// context.body.email            → untouched
-```
-
-Keys are matched **exactly**, on a normalized form (lower-cased, separators stripped) — so one entry covers `apiKey` / `api_key` / `API-KEY` / `x-api-key`. It is not substring matching: `tokenCount` and `passwordUpdatedAt` survive. Read the exact set from `DEFAULT_REDACT_KEYS`.
-
-```ts
-import { DEFAULT_REDACT_KEYS } from "@warlock.js/logger";
-
-log.configure({
-  redact: {
-    keys: ["internalRef"],   // union with the built-in set
-    defaultKeys: false,      // opt out of the built-in set entirely
-  },
-});
-```
-
-`defaultKeys: false` is an escape hatch, not a tuning knob — it restores the pre-4.15.0 behavior where a `password` in `context` reaches every sink in cleartext. Prefer adding a function `censor` if you only need to keep a prefix.
-
-**A channel cannot turn the default set off** (it can only add keys, or turn it back *on* if the logger-wide config disabled it) — same additive-only contract as paths, below. And `log.setRedact(undefined)` clears *your* paths, not the default denylist.
-
-Not reachable by any layer: secrets interpolated into a `message` string (`` `token=${t}` ``), `Map`/`Set`/`Buffer` contents, and getter-backed or non-enumerable properties.
-
-## Layers 1 & 2 — path globs, opt-in
-
-For anything the denylist can't name by key — a secret under an app-specific key, or a value you want partially masked rather than blanked.
-
-The model in one line:
-
-> Logger-wide redaction is the security floor. Per-channel redaction adds more paths. **No channel can ever undo a logger-wide redaction.**
-
-That guarantee is the whole point — once you've set `password` to redact at the logger, you can audit one place to know nothing leaks it, regardless of how many channels you add.
-
-## Logger-wide floor
-
-```ts
-import { log } from "@warlock.js/logger";
-
-log.configure({
-  redact: {
-    paths: [
-      "context.password",
-      "context.*.token",
-      "context.headers.authorization",
-    ],
-    censor: "[REDACTED]",  // default — string or function
-  },
-});
-
-// runtime equivalent:
-log.setRedact({ paths: ["context.password"] });
-log.setRedact(undefined);  // clear your paths (the default denylist stays on)
-```
-
-Every channel sees the redacted entry. Cheap: applied **once** before fan-out; channels share the redacted clone unless they add their own paths.
-
-## Per-channel additive
-
-```ts
-new SlackChannel({
-  webhook: "...",
-  redact: {
-    paths: ["context.user.email", "context.metadata.*"],
-    // censor inherited from logger-wide when omitted
-  },
-});
-```
-
-The channel's `paths` are **merged** with the logger floor — the channel runs a single combined redact pass, never replaces the floor. The channel's `censor` (if provided) wins for both its own and the logger's paths in this channel only; the logger floor still uses its own censor for other channels.
-
-### When to set redact per-channel
-
-- Loud destinations with broader audiences (Slack, Discord, error trackers, anything off your machine) — redact more aggressively.
-- Local-only destinations (FileLog you alone read, the dev terminal) — keep the floor minimal so you can debug.
-
-### When NOT to set it
-
-If you want raw context in your dev terminal, **don't add redact at the logger level** — set it only on the file/JSON/network channels. Logger-wide is the floor, so it applies everywhere; you can't opt a single channel out.
-
-## Path syntax
-
-Paths are dotted glob patterns evaluated against the full `LoggingData`:
-
-```
-type LoggingData = {
-  type: "info" | ...,
-  module: string,
-  action: string,
-  message: any,        // ← prefix paths with "message." to redact here
-  context?: object,    // ← prefix paths with "context." to redact here
-};
-```
-
-| Pattern | Matches |
-| --- | --- |
-| `context.password` | exactly `data.context.password` |
-| `context.*.token` | `data.context.<any>.token` (one segment in between) |
-| `**.password` | `data.context.password`, `data.context.user.password`, … any depth |
-| `message.apiKey` | when message is an object, `data.message.apiKey` |
-| `context.users.*.token` | array element redaction (`*` matches indices too) |
-
-Wildcards:
-
-- `*` — exactly one segment (any object key, any array index).
-- `**` — zero or more segments, greedily; matches at any depth.
-
-## Censor variants
-
-```ts
-// String — replace with a literal.
-{ censor: "[REDACTED]" }
-{ censor: "***" }
-
-// Function — receives original value + dotted path, returns the replacement.
-{
-  censor: (value, path) => {
-    if (typeof value !== "string") return "[REDACTED]";
-    return value.length > 4 ? `${value.slice(0, 2)}***${value.slice(-2)}` : "***";
-  },
-}
-```
-
-Function censors are called for every match — keep them cheap. The path is the actual matched location (e.g. `"context.users.0.token"` for an array hit).
-
-## Immutability
-
-`applyRedact` always returns a deep clone — your input data is never mutated. `Date` and `Error` instances are reconstructed (so `instanceof` checks still work). Circular references are tolerated.
-
-## What about the `message` field?
-
-If `message` is a plain object, paths under `message.*` work as expected. If `message` is a string (the most common case), redaction won't scan it — string scrubbing requires regex and is out of scope for this primitive. Wrap secrets in `context` and they'll be redacted reliably.
-
-## Performance notes
-
-- **No redact configured** → the default denylist still runs (since 4.15.0): a cheap presence scan for a denylisted key on every `log()` call, with the deep clone + censor pass skipped entirely when nothing matches. Only `{ defaultKeys: false }` (no `paths`, no extra `keys`) gets back to zero work.
-- **Logger-wide redact only** → one deep clone + one path-walk per `log()` call, shared by every channel.
-- **Channel adds paths** → that channel re-clones from the original input and runs the merged pass once. Other channels still share the cheaper logger-wide clone.
-- Each path is matched independently; cost grows linearly with `paths.length`.
-
-For most apps with `<10` redact paths and shallow context, the cost is below 100µs per entry. If you're logging millions of entries per second through paths like `**.something`, profile before scaling up — `**` is the only pattern that recurses through every key.
+---
+name: redact-sensitive-log-fields
+description: 'Strip secrets from log output — a built-in secret-key denylist on by default (DEFAULT_REDACT_KEYS), plus two-layer additive redaction via log.configure({redact: {paths, keys}}) (logger floor) + per-channel redact (more on top). Dotted glob paths (*, **). Triggers: `redact`, `paths`, `keys`, `defaultKeys`, `censor`, `log.setRedact`, `applyRedact`; "redact passwords in logs", "strip tokens from log output", "hide authorization headers", "scrub PII before logging", "turn off default redaction"; typical import `import { log } from "@warlock.js/logger"`. Skip: filtering — `@warlock.js/logger/filter-log-entries/SKILL.md`; custom sinks — `@warlock.js/logger/write-custom-log-channel/SKILL.md`; competing libs `pino.redact`, `fast-redact`.'
+---
+
+# Redaction — keeping secrets out of logs
+
+Three layers: a **built-in key denylist that is on by default**, plus opt-in path globs configured at the logger and/or per channel.
+
+## Layer 0 — the default denylist (since 4.15.0, no configuration needed)
+
+Common secret **key names** are censored at any depth of `context`, `message`, and an `Error`'s own enumerable properties — before any of your config runs:
+
+```ts
+log.error("auth", "login", "failed", { headers: req.headers, body: req.body });
+// context.headers.authorization → "[REDACTED]"
+// context.body.password         → "[REDACTED]"
+// context.body.email            → untouched
+```
+
+Keys are matched **exactly**, on a normalized form (lower-cased, separators stripped) — so one entry covers `apiKey` / `api_key` / `API-KEY` / `x-api-key`. It is not substring matching: `tokenCount` and `passwordUpdatedAt` survive. Read the exact set from `DEFAULT_REDACT_KEYS`.
+
+```ts
+import { DEFAULT_REDACT_KEYS } from "@warlock.js/logger";
+
+log.configure({
+  redact: {
+    keys: ["internalRef"],   // union with the built-in set
+    defaultKeys: false,      // opt out of the built-in set entirely
+  },
+});
+```
+
+`defaultKeys: false` is an escape hatch, not a tuning knob — it restores the pre-4.15.0 behavior where a `password` in `context` reaches every sink in cleartext. Prefer adding a function `censor` if you only need to keep a prefix.
+
+**A channel cannot turn the default set off** (it can only add keys, or turn it back *on* if the logger-wide config disabled it) — same additive-only contract as paths, below. And `log.setRedact(undefined)` clears *your* paths, not the default denylist.
+
+Not reachable by any layer: secrets interpolated into a `message` string (`` `token=${t}` ``), `Map`/`Set`/`Buffer` contents, and getter-backed or non-enumerable properties.
+
+## Layers 1 & 2 — path globs, opt-in
+
+For anything the denylist can't name by key — a secret under an app-specific key, or a value you want partially masked rather than blanked.
+
+The model in one line:
+
+> Logger-wide redaction is the security floor. Per-channel redaction adds more paths. **No channel can ever undo a logger-wide redaction.**
+
+That guarantee is the whole point — once you've set `password` to redact at the logger, you can audit one place to know nothing leaks it, regardless of how many channels you add.
+
+## Logger-wide floor
+
+```ts
+import { log } from "@warlock.js/logger";
+
+log.configure({
+  redact: {
+    paths: [
+      "context.password",
+      "context.*.token",
+      "context.headers.authorization",
+    ],
+    censor: "[REDACTED]",  // default — string or function
+  },
+});
+
+// runtime equivalent:
+log.setRedact({ paths: ["context.password"] });
+log.setRedact(undefined);  // clear your paths (the default denylist stays on)
+```
+
+Every channel sees the redacted entry. Cheap: applied **once** before fan-out; channels share the redacted clone unless they add their own paths.
+
+## Per-channel additive
+
+```ts
+new SlackChannel({
+  webhook: "...",
+  redact: {
+    paths: ["context.user.email", "context.metadata.*"],
+    // censor inherited from logger-wide when omitted
+  },
+});
+```
+
+The channel's `paths` are **merged** with the logger floor — the channel runs a single combined redact pass, never replaces the floor. The channel's `censor` (if provided) wins for both its own and the logger's paths in this channel only; the logger floor still uses its own censor for other channels.
+
+### When to set redact per-channel
+
+- Loud destinations with broader audiences (Slack, Discord, error trackers, anything off your machine) — redact more aggressively.
+- Local-only destinations (FileLog you alone read, the dev terminal) — keep the floor minimal so you can debug.
+
+### When NOT to set it
+
+If you want raw context in your dev terminal, **don't add redact at the logger level** — set it only on the file/JSON/network channels. Logger-wide is the floor, so it applies everywhere; you can't opt a single channel out.
+
+## Path syntax
+
+Paths are dotted glob patterns evaluated against the full `LoggingData`:
+
+```
+type LoggingData = {
+  type: "info" | ...,
+  module: string,
+  action: string,
+  message: any,        // ← prefix paths with "message." to redact here
+  context?: object,    // ← prefix paths with "context." to redact here
+};
+```
+
+| Pattern | Matches |
+| --- | --- |
+| `context.password` | exactly `data.context.password` |
+| `context.*.token` | `data.context.<any>.token` (one segment in between) |
+| `**.password` | `data.context.password`, `data.context.user.password`, … any depth |
+| `message.apiKey` | when message is an object, `data.message.apiKey` |
+| `context.users.*.token` | array element redaction (`*` matches indices too) |
+
+Wildcards:
+
+- `*` — exactly one segment (any object key, any array index).
+- `**` — zero or more segments, greedily; matches at any depth.
+
+## Censor variants
+
+```ts
+// String — replace with a literal.
+{ censor: "[REDACTED]" }
+{ censor: "***" }
+
+// Function — receives original value + dotted path, returns the replacement.
+{
+  censor: (value, path) => {
+    if (typeof value !== "string") return "[REDACTED]";
+    return value.length > 4 ? `${value.slice(0, 2)}***${value.slice(-2)}` : "***";
+  },
+}
+```
+
+Function censors are called for every match — keep them cheap. The path is the actual matched location (e.g. `"context.users.0.token"` for an array hit).
+
+## Immutability
+
+`applyRedact` always returns a deep clone — your input data is never mutated. `Date` and `Error` instances are reconstructed (so `instanceof` checks still work). Circular references are tolerated.
+
+## What about the `message` field?
+
+If `message` is a plain object, paths under `message.*` work as expected. If `message` is a string (the most common case), redaction won't scan it — string scrubbing requires regex and is out of scope for this primitive. Wrap secrets in `context` and they'll be redacted reliably.
+
+## Performance notes
+
+- **No redact configured** → the default denylist still runs (since 4.15.0): a cheap presence scan for a denylisted key on every `log()` call, with the deep clone + censor pass skipped entirely when nothing matches. Only `{ defaultKeys: false }` (no `paths`, no extra `keys`) gets back to zero work.
+- **Logger-wide redact only** → one deep clone + one path-walk per `log()` call, shared by every channel.
+- **Channel adds paths** → that channel re-clones from the original input and runs the merged pass once. Other channels still share the cheaper logger-wide clone.
+- Each path is matched independently; cost grows linearly with `paths.length`.
+
+For most apps with `<10` redact paths and shallow context, the cost is below 100µs per entry. If you're logging millions of entries per second through paths like `**.something`, profile before scaling up — `**` is the only pattern that recurses through every key.

package/skills/ship-logs-to-sentry/SKILL.md

@@ -1,118 +1,118 @@
----
-name: ship-logs-to-sentry
-description: 'Forward log entries to Sentry with the SentryLog channel — error/warn become events (captureException/captureMessage), every other level a breadcrumb (no quota). @sentry/node is an OPTIONAL peer, lazily imported. Triggers: `SentryLog`, `@sentry/node`, `eventLevels`, `flushTimeout`, `Sentry.flush`, `captureException`, `addBreadcrumb`, `withScope`; "send logs to Sentry", "report errors to Sentry", "Sentry log channel", "Sentry breadcrumbs from logs", "log channel for Sentry"; typical import `import { SentryLog } from "@warlock.js/logger"`. Skip: file/console channels — `@warlock.js/logger/pick-log-channel/SKILL.md`; custom sinks — `@warlock.js/logger/write-custom-log-channel/SKILL.md`; graceful-shutdown flushing — `@warlock.js/logger/flush-logs-on-shutdown/SKILL.md`; Slack alerting recipe.'
----
-
-# Ship logs to Sentry — the `SentryLog` channel
-
-`SentryLog` forwards log entries to Sentry. It's the one built-in channel that needs an external SDK, so `@sentry/node` is an **optional peer** — install it only if you use this channel:
-
-```bash
-npm install @sentry/node
-```
-
-## Two ways to wire it
-
-### Reuse an existing Sentry client (existing apps)
-
-If your app already calls `Sentry.init(...)`, pass the namespace as `client`. The channel forwards through it and never re-imports or re-initializes the SDK:
-
-```ts
-import * as Sentry from "@sentry/node";
-import { log, SentryLog } from "@warlock.js/logger";
-
-Sentry.init({ dsn: process.env.SENTRY_DSN, environment: "production" });
-
-log.addChannel(new SentryLog({ client: Sentry }));
-```
-
-### Let the channel initialize Sentry (new apps)
-
-Pass `options`; the channel lazily imports `@sentry/node` and calls `Sentry.init` once — guarded so it never clobbers an existing client:
-
-```ts
-import { log, SentryLog } from "@warlock.js/logger";
-
-log.addChannel(
-  new SentryLog({
-    options: {
-      dsn: process.env.SENTRY_DSN,
-      environment: process.env.NODE_ENV,
-      release: process.env.GIT_SHA,
-    },
-  }),
-);
-```
-
-With neither `client` nor `options`, the channel reuses whatever global Sentry client the host already initialized.
-
-## How levels map to Sentry
-
-This is the quota-control decision. Only `eventLevels` create Sentry **events** (which consume your error quota); every other level becomes a **breadcrumb** that rides along with the next event for free.
-
-| Logger level | Default | Sentry call |
-|---|---|---|
-| `fatal` | event | `captureException` for an `Error` message, else `captureMessage(…, "fatal")` |
-| `error` | event | `captureException` for an `Error` message, else `captureMessage(…, "error")` |
-| `warn` | event | `captureMessage(…, "warning")` |
-| `success` | breadcrumb | `addBreadcrumb({ level: "info" })` |
-| `info` | breadcrumb | `addBreadcrumb({ level: "info" })` |
-| `debug` | breadcrumb | `addBreadcrumb({ level: "debug" })` |
-
-- **Errors keep their stack.** A `message` that is an `Error` goes through `captureException`, so Sentry parses the real stack and groups correctly — never pre-stringify the error.
-- **`module` / `action` become tags** and the entry's `context` becomes a structured Sentry context, both scoped to that single event via `withScope`.
-- **`success` has no Sentry severity** — it's reported as `info`.
-
-### Tuning what becomes an event
-
-```ts
-// Only errors create events; warnings drop to breadcrumbs.
-new SentryLog({ client: Sentry, eventLevels: ["error"] });
-
-// Errors + warnings + an info stream as events (noisier, more quota).
-new SentryLog({ client: Sentry, eventLevels: ["error", "warn", "info"] });
-```
-
-`levels` and `filter` from `BasicLogConfigurations` apply first — a channel-level `levels: ["error", "warn"]` drops everything else before it reaches Sentry at all.
-
-## Draining on shutdown
-
-Sentry sends events asynchronously over the network, so a synchronous flush can't wait on them. `SentryLog.flush()` calls `Sentry.flush(timeout)`; drain it on your graceful-shutdown path:
-
-```ts
-async function shutdown() {
-  await httpServer.close();
-  await log.flush();   // SentryLog.flush() → Sentry.flush(flushTimeout)
-  process.exit(0);
-}
-
-process.once("SIGTERM", shutdown);
-```
-
-`flushTimeout` (default `2000` ms) bounds the wait so an unreachable Sentry can't hang shutdown. `autoFlushOn` uses the **synchronous** `flushSync()`, which does *not* drain Sentry — wire `await log.flush()` yourself. See [`flush-logs-on-shutdown`](@warlock.js/logger/flush-logs-on-shutdown/SKILL.md).
-
-## If `@sentry/node` isn't installed
-
-The channel never crashes your app: the dynamic import failure is swallowed, the install instructions are written to stderr **once**, and entries are dropped silently thereafter. So registering `SentryLog` in shared config is safe even in an environment where Sentry isn't installed.
-
-## Config reference
-
-| Option | Type | Default | Description |
-|---|---|---|---|
-| `client` | Sentry namespace / forwarder | — | Reuse an already-initialized Sentry instance. |
-| `options` | `SentryInitOptions` | — | Sentry init options (mirrors `@sentry/node`'s `NodeOptions`) — used when the channel owns Sentry. |
-| `eventLevels` | `LogLevel[]` | `["fatal", "error", "warn"]` | Levels sent as events; the rest become breadcrumbs. |
-| `flushTimeout` | `number` | `2000` | Ms `flush()` waits for the transport to drain. |
-| `levels`, `filter`, `dateFormat`, `redact` | — | — | Inherited from `BasicLogConfigurations`. |
-
-## Don't do
-
-- **Don't double-init Sentry.** Pass *either* `client` *or* `options`, not both. The channel guards against double-init, but a single owner of `Sentry.init` is cleaner.
-- **Don't send every level as an event.** `eventLevels` with `info`/`debug`/`success` will flood your Sentry quota — keep them as breadcrumbs.
-- **Don't rely on `autoFlushOn` for Sentry.** It's synchronous; a network channel needs `await log.flush()`.
-
-## See also
-
-- [`@warlock.js/logger/flush-logs-on-shutdown/SKILL.md`](@warlock.js/logger/flush-logs-on-shutdown/SKILL.md) — `await log.flush()` on shutdown
-- [`@warlock.js/logger/pick-log-channel/SKILL.md`](@warlock.js/logger/pick-log-channel/SKILL.md) — the console / file channels
-- [`@warlock.js/logger/write-custom-log-channel/SKILL.md`](@warlock.js/logger/write-custom-log-channel/SKILL.md) — build your own sink
+---
+name: ship-logs-to-sentry
+description: 'Forward log entries to Sentry with the SentryLog channel — error/warn become events (captureException/captureMessage), every other level a breadcrumb (no quota). @sentry/node is an OPTIONAL peer, lazily imported. Triggers: `SentryLog`, `@sentry/node`, `eventLevels`, `flushTimeout`, `Sentry.flush`, `captureException`, `addBreadcrumb`, `withScope`; "send logs to Sentry", "report errors to Sentry", "Sentry log channel", "Sentry breadcrumbs from logs", "log channel for Sentry"; typical import `import { SentryLog } from "@warlock.js/logger"`. Skip: file/console channels — `@warlock.js/logger/pick-log-channel/SKILL.md`; custom sinks — `@warlock.js/logger/write-custom-log-channel/SKILL.md`; graceful-shutdown flushing — `@warlock.js/logger/flush-logs-on-shutdown/SKILL.md`; Slack alerting recipe.'
+---
+
+# Ship logs to Sentry — the `SentryLog` channel
+
+`SentryLog` forwards log entries to Sentry. It's the one built-in channel that needs an external SDK, so `@sentry/node` is an **optional peer** — install it only if you use this channel:
+
+```bash
+npm install @sentry/node
+```
+
+## Two ways to wire it
+
+### Reuse an existing Sentry client (existing apps)
+
+If your app already calls `Sentry.init(...)`, pass the namespace as `client`. The channel forwards through it and never re-imports or re-initializes the SDK:
+
+```ts
+import * as Sentry from "@sentry/node";
+import { log, SentryLog } from "@warlock.js/logger";
+
+Sentry.init({ dsn: process.env.SENTRY_DSN, environment: "production" });
+
+log.addChannel(new SentryLog({ client: Sentry }));
+```
+
+### Let the channel initialize Sentry (new apps)
+
+Pass `options`; the channel lazily imports `@sentry/node` and calls `Sentry.init` once — guarded so it never clobbers an existing client:
+
+```ts
+import { log, SentryLog } from "@warlock.js/logger";
+
+log.addChannel(
+  new SentryLog({
+    options: {
+      dsn: process.env.SENTRY_DSN,
+      environment: process.env.NODE_ENV,
+      release: process.env.GIT_SHA,
+    },
+  }),
+);
+```
+
+With neither `client` nor `options`, the channel reuses whatever global Sentry client the host already initialized.
+
+## How levels map to Sentry
+
+This is the quota-control decision. Only `eventLevels` create Sentry **events** (which consume your error quota); every other level becomes a **breadcrumb** that rides along with the next event for free.
+
+| Logger level | Default | Sentry call |
+|---|---|---|
+| `fatal` | event | `captureException` for an `Error` message, else `captureMessage(…, "fatal")` |
+| `error` | event | `captureException` for an `Error` message, else `captureMessage(…, "error")` |
+| `warn` | event | `captureMessage(…, "warning")` |
+| `success` | breadcrumb | `addBreadcrumb({ level: "info" })` |
+| `info` | breadcrumb | `addBreadcrumb({ level: "info" })` |
+| `debug` | breadcrumb | `addBreadcrumb({ level: "debug" })` |
+
+- **Errors keep their stack.** A `message` that is an `Error` goes through `captureException`, so Sentry parses the real stack and groups correctly — never pre-stringify the error.
+- **`module` / `action` become tags** and the entry's `context` becomes a structured Sentry context, both scoped to that single event via `withScope`.
+- **`success` has no Sentry severity** — it's reported as `info`.
+
+### Tuning what becomes an event
+
+```ts
+// Only errors create events; warnings drop to breadcrumbs.
+new SentryLog({ client: Sentry, eventLevels: ["error"] });
+
+// Errors + warnings + an info stream as events (noisier, more quota).
+new SentryLog({ client: Sentry, eventLevels: ["error", "warn", "info"] });
+```
+
+`levels` and `filter` from `BasicLogConfigurations` apply first — a channel-level `levels: ["error", "warn"]` drops everything else before it reaches Sentry at all.
+
+## Draining on shutdown
+
+Sentry sends events asynchronously over the network, so a synchronous flush can't wait on them. `SentryLog.flush()` calls `Sentry.flush(timeout)`; drain it on your graceful-shutdown path:
+
+```ts
+async function shutdown() {
+  await httpServer.close();
+  await log.flush();   // SentryLog.flush() → Sentry.flush(flushTimeout)
+  process.exit(0);
+}
+
+process.once("SIGTERM", shutdown);
+```
+
+`flushTimeout` (default `2000` ms) bounds the wait so an unreachable Sentry can't hang shutdown. `autoFlushOn` uses the **synchronous** `flushSync()`, which does *not* drain Sentry — wire `await log.flush()` yourself. See [`flush-logs-on-shutdown`](@warlock.js/logger/flush-logs-on-shutdown/SKILL.md).
+
+## If `@sentry/node` isn't installed
+
+The channel never crashes your app: the dynamic import failure is swallowed, the install instructions are written to stderr **once**, and entries are dropped silently thereafter. So registering `SentryLog` in shared config is safe even in an environment where Sentry isn't installed.
+
+## Config reference
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `client` | Sentry namespace / forwarder | — | Reuse an already-initialized Sentry instance. |
+| `options` | `SentryInitOptions` | — | Sentry init options (mirrors `@sentry/node`'s `NodeOptions`) — used when the channel owns Sentry. |
+| `eventLevels` | `LogLevel[]` | `["fatal", "error", "warn"]` | Levels sent as events; the rest become breadcrumbs. |
+| `flushTimeout` | `number` | `2000` | Ms `flush()` waits for the transport to drain. |
+| `levels`, `filter`, `dateFormat`, `redact` | — | — | Inherited from `BasicLogConfigurations`. |
+
+## Don't do
+
+- **Don't double-init Sentry.** Pass *either* `client` *or* `options`, not both. The channel guards against double-init, but a single owner of `Sentry.init` is cleaner.
+- **Don't send every level as an event.** `eventLevels` with `info`/`debug`/`success` will flood your Sentry quota — keep them as breadcrumbs.
+- **Don't rely on `autoFlushOn` for Sentry.** It's synchronous; a network channel needs `await log.flush()`.
+
+## See also
+
+- [`@warlock.js/logger/flush-logs-on-shutdown/SKILL.md`](@warlock.js/logger/flush-logs-on-shutdown/SKILL.md) — `await log.flush()` on shutdown
+- [`@warlock.js/logger/pick-log-channel/SKILL.md`](@warlock.js/logger/pick-log-channel/SKILL.md) — the console / file channels
+- [`@warlock.js/logger/write-custom-log-channel/SKILL.md`](@warlock.js/logger/write-custom-log-channel/SKILL.md) — build your own sink