@warlock.js/logger 4.1.15 → 4.2.0

package/skills/pick-log-channel/SKILL.md

@@ -1,139 +1,155 @@
----
-name: pick-log-channel
-description: 'Pick one of the three built-in channels — ConsoleLog (terminal), FileLog (plain text on disk), JSONFileLog (structured JSON for aggregators like Loki / Datadog / Elastic). Triggers: `ConsoleLog`, `FileLog`, `JSONFileLog`, `chunk`, `rotate`, `groupBy`, `maxFileSize`, `showContext`, `log.channel`; "log to a file", "rotate log files", "daily log chunks", "json logs for datadog / loki / elastic"; typical import `import { ConsoleLog, FileLog, JSONFileLog } from "@warlock.js/logger"`. Skip: custom sinks — `@warlock.js/logger/write-custom-log-channel/SKILL.md`; registration — `@warlock.js/logger/configure-logger/SKILL.md`; competing libs `winston-daily-rotate-file`, `pino-pretty`.'
----
-
-# Channels — which one to pick and how to configure it
-
-Three built-in channels. A channel is a destination for a log entry — the logger fans out every entry to every registered channel in parallel.
-
-## The decision
-
-| Need | Pick |
-|---|---|
-| Local dev, colored output in the terminal | `ConsoleLog` |
-| Plain text `.log` files on disk — humans read them | `FileLog` |
-| Structured `.json` files — a log aggregator (Loki / Datadog / Elastic) reads them | `JSONFileLog` |
-
-Most production setups use **two** channels: `ConsoleLog` + one file channel. Dev uses `ConsoleLog` only.
-
-## `ConsoleLog`
-
-Zero config. Colored, icon-prefixed lines to the terminal.
-
-```ts
-import { ConsoleLog } from "@warlock.js/logger";
-
-new ConsoleLog();
-// ⚙ (2024-03-15T10:22:00.000Z) [auth] [hashPassword] Hashing started
-// ℹ (2024-03-15T10:22:01.482Z) [users] [register] New user created
-// ✗ (2024-03-15T10:22:03.111Z) [payments] [charge] Card declined
-```
-
-Properties:
-- `name = "console"`, `terminal = true`
-- Accepts `ConsoleLogConfig` — `levels`, `filter`, `dateFormat`, `showContext`, `contextDepth`
-- If `message` is an object, a second `console.log(message)` is issued so Node's inspector can expand it
-
-### Showing context
-
-By default `ConsoleLog` drops the `context` payload (the file/JSON channels still keep it). Flip `showContext: true` to render it on a second line — useful in development:
-
-```ts
-new ConsoleLog({ showContext: true });
-
-log.info("payments", "charge", "card declined", { userId: 42, amount: 1999 });
-// ℹ (…) [payments] [charge] card declined
-//   ↳ { userId: 42, amount: 1999 }
-```
-
-Tune `contextDepth` (default `4`) to clamp how deep `util.inspect` recurses into nested objects.
-
-## `FileLog`
-
-Plain text. Buffers in memory, flushes to disk periodically.
-
-```ts
-import { FileLog } from "@warlock.js/logger";
-
-new FileLog({
-  storagePath: "./storage/logs",  // default: process.cwd() + "/storage/logs"
-  name: "app",                    // default: "app"
-  extension: "log",               // default: "log"
-  chunk: "daily",                 // "single" (default) | "daily" | "hourly"
-  rotate: true,                   // default: true
-  maxFileSize: 10 * 1024 * 1024,  // default: 10MB — triggers rotation
-  maxMessagesToWrite: 100,        // default: 100 — flush threshold
-  groupBy: ["level", "module"],   // optional subdirectory nesting
-});
-```
-
-Line format: `[date time] [level] [module][action]: message` — or a `[trace]` block when `message` is an `Error`.
-
-### Key gotchas
-
-- **Buffers!** Messages sit in memory until either `maxMessagesToWrite` is reached, 5 seconds pass, or `flushSync()` is called. A process that crashes without flushing loses buffered entries.
-- **`chunk: "daily"` picks a filename per day.** File name becomes `DD-MM-YYYY.log`. Combined with `rotate: true`, rotated archives get `Date.now()` suffixed.
-- **`groupBy` nests directories.** `groupBy: ["level", "module"]` produces `storage/logs/error/payments/app.log`. Order matters.
-- **Dispose channels you discard.** A live `FileLog` keeps a 5-second flush interval running. If you swap the channel list at runtime (reconfigure the logger), call `channel.dispose()` on the old instance — it clears that timer and drains the buffer one last time. Skipping it leaks one timer per discarded channel and keeps the event loop alive. (Channels that live for the whole process don't need this — process exit clears the timer.)
-
-## `JSONFileLog`
-
-Subclass of `FileLog` — same buffering, chunking, rotation, grouping. Output is a JSON object with a `messages` array:
-
-```json
-{
-  "messages": [
-    {
-      "content": "Card declined",
-      "level": "error",
-      "date": "15-03-2024 10:22:03",
-      "module": "payments",
-      "action": "charge",
-      "stack": [
-        "Error: Card declined",
-        "    at chargeCard (/app/src/payments.ts:42:11)"
-      ]
-    }
-  ]
-}
-```
-
-Differences from `FileLog`:
-- `name = "fileJson"` (**not** `"json"` — use this exact string for `log.channel("fileJson")`)
-- `extension` is always `"json"` — the option is silently ignored
-- Error `stack` is stored as `string[]` (split on newlines) — easy to query in aggregators
-- `content` holds the original user-supplied `message` (not a pre-formatted line)
-- Corrupted existing file → reinitialized to `{ messages: [] }` on next write (does not throw)
-- **Safe serialization by construction.** All writes go through `safe-stable-stringify` with a custom `Error` replacer — circular refs become `"[Circular]"`, BigInt is stringified, functions/symbols are dropped, nested `Error` instances expand to `{ name, message, stack, ...enumerable }`. A context payload with a class graph or circular reference will never throw during the write.
-
-## Shared config — `BasicLogConfigurations`
-
-Every channel constructor accepts at minimum:
-
-```ts
-type BasicLogConfigurations = {
-  levels?: LogLevel[];                       // whitelist — omit or [] to allow all
-  filter?: (data: LoggingData) => boolean;   // custom predicate
-  dateFormat?: { date?: string; time?: string }; // Day.js format strings
-  context?: (data) => Promise<Record<string, any>>; // reserved — not yet read
-};
-```
-
-Concrete file channels extend this with their storage/chunk/rotate/groupBy options via intersection.
-
-## Picking a channel by name at runtime
-
-```ts
-log.channel("console");   // → ConsoleLog | undefined
-log.channel("file");      // → FileLog | undefined
-log.channel("fileJson");  // ← note the name — NOT "json"
-```
-
-If two channels share a `name`, only one is reachable this way — the search returns the first match.
-
-## See also
-
-- [`@warlock.js/logger/configure-logger/SKILL.md`](@warlock.js/logger/configure-logger/SKILL.md) — registering channels at startup
-- [`@warlock.js/logger/filter-log-entries/SKILL.md`](@warlock.js/logger/filter-log-entries/SKILL.md) — `levels` and `filter` config in detail
-- [`@warlock.js/logger/write-custom-log-channel/SKILL.md`](@warlock.js/logger/write-custom-log-channel/SKILL.md) — extending `LogChannel` for custom sinks
+---
+name: pick-log-channel
+description: 'Pick one of the four built-in channels — ConsoleLog (terminal), FileLog (plain text on disk), JSONFileLog (structured JSON for aggregators like Loki / Datadog / Elastic), SentryLog (forwards errors + breadcrumbs to Sentry). Triggers: `ConsoleLog`, `FileLog`, `JSONFileLog`, `SentryLog`, `chunk`, `rotate`, `groupBy`, `maxFileSize`, `showContext`, `log.channel`; "log to a file", "rotate log files", "daily log chunks", "json logs for datadog / loki / elastic", "send logs to Sentry"; typical import `import { ConsoleLog, FileLog, JSONFileLog, SentryLog } from "@warlock.js/logger"`. Skip: Sentry-specific setup — `@warlock.js/logger/ship-logs-to-sentry/SKILL.md`; custom sinks — `@warlock.js/logger/write-custom-log-channel/SKILL.md`; registration — `@warlock.js/logger/configure-logger/SKILL.md`; competing libs `winston-daily-rotate-file`, `pino-pretty`.'
+---
+
+# Channels — which one to pick and how to configure it
+
+Four built-in channels (`SentryLog` needs the optional `@sentry/node` peer). A channel is a destination for a log entry — the logger fans out every entry to every registered channel in parallel.
+
+## The decision
+
+| Need | Pick |
+|---|---|
+| Local dev, colored output in the terminal | `ConsoleLog` |
+| Plain text `.log` files on disk — humans read them | `FileLog` |
+| Structured `.json` files — a log aggregator (Loki / Datadog / Elastic) reads them | `JSONFileLog` |
+| Errors & warnings into Sentry (events + breadcrumbs) | `SentryLog` |
+
+Most production setups use **two** channels: `ConsoleLog` + one file channel. Dev uses `ConsoleLog` only.
+
+## `ConsoleLog`
+
+Zero config. Colored, icon-prefixed lines to the terminal.
+
+```ts
+import { ConsoleLog } from "@warlock.js/logger";
+
+new ConsoleLog();
+// ⚙ (2024-03-15T10:22:00.000Z) [auth] [hashPassword] Hashing started
+// ℹ (2024-03-15T10:22:01.482Z) [users] [register] New user created
+// ✗ (2024-03-15T10:22:03.111Z) [payments] [charge] Card declined
+```
+
+Properties:
+- `name = "console"`, `terminal = true`
+- Accepts `ConsoleLogConfig` — `levels`, `filter`, `dateFormat`, `showContext`, `contextDepth`
+- If `message` is an object, a second `console.log(message)` is issued so Node's inspector can expand it
+
+### Showing context
+
+By default `ConsoleLog` drops the `context` payload (the file/JSON channels still keep it). Flip `showContext: true` to render it on a second line — useful in development:
+
+```ts
+new ConsoleLog({ showContext: true });
+
+log.info("payments", "charge", "card declined", { userId: 42, amount: 1999 });
+// ℹ (…) [payments] [charge] card declined
+//   ↳ { userId: 42, amount: 1999 }
+```
+
+Tune `contextDepth` (default `4`) to clamp how deep `util.inspect` recurses into nested objects.
+
+## `FileLog`
+
+Plain text. Buffers in memory, flushes to disk periodically.
+
+```ts
+import { FileLog } from "@warlock.js/logger";
+
+new FileLog({
+  storagePath: "./storage/logs",  // default: process.cwd() + "/storage/logs"
+  name: "app",                    // default: "app"
+  extension: "log",               // default: "log"
+  chunk: "daily",                 // "single" (default) | "daily" | "hourly"
+  rotate: true,                   // default: true
+  maxFileSize: 10 * 1024 * 1024,  // default: 10MB — triggers rotation
+  maxMessagesToWrite: 100,        // default: 100 — flush threshold
+  groupBy: ["level", "module"],   // optional subdirectory nesting
+});
+```
+
+Line format: `[date time] [level] [module][action]: message` — or a `[trace]` block when `message` is an `Error`.
+
+### Key gotchas
+
+- **Buffers!** Messages sit in memory until either `maxMessagesToWrite` is reached, 5 seconds pass, or `flushSync()` is called. A process that crashes without flushing loses buffered entries.
+- **`chunk: "daily"` picks a filename per day.** File name becomes `DD-MM-YYYY.log`. Combined with `rotate: true`, rotated archives get `Date.now()` suffixed.
+- **`groupBy` nests directories.** `groupBy: ["level", "module"]` produces `storage/logs/error/payments/app.log`. Order matters.
+- **Dispose channels you discard.** A live `FileLog` keeps a 5-second flush interval running. If you swap the channel list at runtime (reconfigure the logger), call `channel.dispose()` on the old instance — it clears that timer and drains the buffer one last time. Skipping it leaks one timer per discarded channel and keeps the event loop alive. (Channels that live for the whole process don't need this — process exit clears the timer.)
+
+## `JSONFileLog`
+
+Subclass of `FileLog` — same buffering, chunking, rotation, grouping. Output is a JSON object with a `messages` array:
+
+```json
+{
+  "messages": [
+    {
+      "content": "Card declined",
+      "level": "error",
+      "date": "15-03-2024 10:22:03",
+      "module": "payments",
+      "action": "charge",
+      "stack": [
+        "Error: Card declined",
+        "    at chargeCard (/app/src/payments.ts:42:11)"
+      ]
+    }
+  ]
+}
+```
+
+Differences from `FileLog`:
+- `name = "fileJson"` (**not** `"json"` — use this exact string for `log.channel("fileJson")`)
+- `extension` is always `"json"` — the option is silently ignored
+- Error `stack` is stored as `string[]` (split on newlines) — easy to query in aggregators
+- `content` holds the original user-supplied `message` (not a pre-formatted line)
+- Corrupted existing file → reinitialized to `{ messages: [] }` on next write (does not throw)
+- **Safe serialization by construction.** All writes go through `safe-stable-stringify` with a custom `Error` replacer — circular refs become `"[Circular]"`, BigInt is stringified, functions/symbols are dropped, nested `Error` instances expand to `{ name, message, stack, ...enumerable }`. A context payload with a class graph or circular reference will never throw during the write.
+
+## `SentryLog`
+
+Forwards entries to Sentry — `error` / `warn` become events (`captureException` for `Error` messages, `captureMessage` otherwise), every other level a breadcrumb (no quota). `@sentry/node` is an optional peer, lazily imported; pass an existing `client` or `options`.
+
+```ts
+import * as Sentry from "@sentry/node";
+import { SentryLog } from "@warlock.js/logger";
+
+new SentryLog({ client: Sentry, eventLevels: ["error", "warn"] });
+```
+
+Full guide — level mapping, init modes, shutdown draining: [`ship-logs-to-sentry`](@warlock.js/logger/ship-logs-to-sentry/SKILL.md).
+
+## Shared config — `BasicLogConfigurations`
+
+Every channel constructor accepts at minimum:
+
+```ts
+type BasicLogConfigurations = {
+  levels?: LogLevel[];                       // whitelist — omit or [] to allow all
+  filter?: (data: LoggingData) => boolean;   // custom predicate
+  dateFormat?: { date?: string; time?: string }; // Day.js format strings
+  context?: (data) => Promise<Record<string, any>>; // reserved — not yet read
+};
+```
+
+Concrete file channels extend this with their storage/chunk/rotate/groupBy options via intersection.
+
+## Picking a channel by name at runtime
+
+```ts
+log.channel("console");   // → ConsoleLog | undefined
+log.channel("file");      // → FileLog | undefined
+log.channel("fileJson");  // ← note the name — NOT "json"
+log.channel("sentry");    // → SentryLog | undefined
+```
+
+If two channels share a `name`, only one is reachable this way — the search returns the first match.
+
+## See also
+
+- [`@warlock.js/logger/configure-logger/SKILL.md`](@warlock.js/logger/configure-logger/SKILL.md) — registering channels at startup
+- [`@warlock.js/logger/filter-log-entries/SKILL.md`](@warlock.js/logger/filter-log-entries/SKILL.md) — `levels` and `filter` config in detail
+- [`@warlock.js/logger/ship-logs-to-sentry/SKILL.md`](@warlock.js/logger/ship-logs-to-sentry/SKILL.md) — the `SentryLog` channel in depth
+- [`@warlock.js/logger/write-custom-log-channel/SKILL.md`](@warlock.js/logger/write-custom-log-channel/SKILL.md) — extending `LogChannel` for custom sinks

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

@@ -0,0 +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