@venizia/ignis-docs 0.2.0 → 0.2.1-1

package/content/extensions/helpers/logger/index.md

@@ -1,173 +1,69 @@
-# Logger
-
-Winston-based logging with scoped prefixes, multiple transports (console, daily-rotating files, UDP), and a zero-allocation high-frequency logger for performance-critical paths.
-
-## Quick Reference
-
-| Class | Extends | Use Case |
-|-------|---------|----------|
-| `Logger` | -- | General-purpose scoped logger with caching |
-| `LoggerFactory` | -- | Factory that builds `Logger` instances from scope arrays |
-| `HfLogger` | -- | Zero-allocation ring-buffer logger for hot paths (~100-300ns) |
-| `HfLogFlusher` | -- | Background flusher for `HfLogger` entries |
-| `DgramTransport` | `winston-transport.Transport` | Custom Winston transport that sends logs over UDP |
-
-#### Import Paths
+---
+title: Logger
+description: Scoped, cached logging via LoggerFactory - Winston by default, with console, daily-rotating file, and UDP transports built in
+difficulty: beginner
+---
 
-```typescript
-// Core classes
-import { Logger, LoggerFactory, ApplicationLogger } from '@venizia/ignis-helpers';
-
-// High-frequency logger
-import { HfLogger, HfLogFlusher } from '@venizia/ignis-helpers';
-
-// Constants & types
-import { LogLevels, LoggerFormats } from '@venizia/ignis-helpers';
-import type { TLogLevel, TLoggerFormat } from '@venizia/ignis-helpers';
-
-// Custom logger utilities
-import {
-  defineCustomLogger,
-  defineLogFormatter,
-  defineJsonLoggerFormatter,
-  definePrettyLoggerFormatter,
-  applicationLogFormatter,
-  applicationLogger,
-} from '@venizia/ignis-helpers';
-import type { IFileTransportOptions, ICustomLoggerOptions } from '@venizia/ignis-helpers';
-
-// UDP transport
-import { DgramTransport } from '@venizia/ignis-helpers';
-import type { IDgramTransportOptions } from '@venizia/ignis-helpers';
-```
+# Logger
 
-## Creating an Instance
+IGNIS gives every helper a scoped `ILogger`. `LoggerFactory` builds it from one registered provider - Winston by default, with console, daily-rotating file, and UDP transports built in.
 
-### Using LoggerFactory (Recommended)
+## In one example
 
-`LoggerFactory.getLogger` accepts an array of scope strings, joins them with `-`, and returns a cached `Logger` instance.
+The smallest real use: get a scoped logger and log with it.
 
 ```typescript
 import { LoggerFactory } from '@venizia/ignis-helpers';
 
-const logger = LoggerFactory.getLogger(['MyService']);
-logger.info('Service initialized');
-// Output: [MyService] Service initialized
-
-const scopedLogger = LoggerFactory.getLogger(['Payment', 'Stripe']);
-scopedLogger.info('Charge created');
-// Output: [Payment-Stripe] Charge created
-```
-
-> [!TIP]
-> `LoggerFactory` is how `BaseHelper` creates its internal logger. Every helper in the framework gets a scoped logger automatically through this path.
-
-### Using Logger.get() Directly
-
-```typescript
-import { Logger } from '@venizia/ignis-helpers';
-
-const logger = Logger.get('MyService');
-logger.info('Direct logger access');
-// Output: [MyService] Direct logger access
+const logger = LoggerFactory.getLogger(['UserService']);
+logger.info('User created');
+// Output: [UserService] User created
 ```
 
-Pass a custom Winston logger instance as the second parameter to use your own transport configuration:
-
-```typescript
-import { Logger, defineCustomLogger, applicationLogFormatter } from '@venizia/ignis-helpers';
-
-const customWinstonLogger = defineCustomLogger({
-  loggerFormatter: applicationLogFormatter,
-  transports: {
-    info: { file: { prefix: 'custom', folder: './logs' } },
-    error: { file: { prefix: 'custom-error', folder: './logs' } },
-  },
-});
+`LoggerFactory` is how `BaseHelper` creates its internal logger, so every helper in the framework gets a scoped logger the same way, for free.
 
-const logger = Logger.get('MyService', customWinstonLogger);
-```
+## How it works
 
-Custom loggers are cached under a separate key (`scope:custom`), so a default and custom logger for the same scope can coexist.
+- **Typed against `ILogger`.** Every consumer - including `BaseHelper.logger` - gets the `ILogger` interface, never a concrete class. Winston is the default provider behind it, selected in `factory.ts`.
+- **Provider-based.** `LoggerFactory.use({ provider })` selects the app's logger engine once, at the entrypoint. Winston is the default; [pino](/extensions/helpers/logger/pino) is the throughput option. Every factory-issued logger follows the registration, even one captured at import time.
+- **Scoped and cached.** `LoggerFactory.getLogger(scopes)` joins the scopes with `-` and caches the result per scope. The same scope always returns the same instance. `BaseHelper` calls this in its constructor, so every helper's `this.logger` comes pre-scoped.
+- **Custom-backed loggers are the exception.** `Logger.get(scope, customWinstonLogger)` (from the `/winston` sub-path) is NOT cached. Each call returns a fresh wrapper over the instance you passed in.
+- **Method scoping.** `.for(methodName)` returns a child logger scoped to `<scope>-<methodName>` (also cached), so each line shows where it came from.
+- **Level floor.** `APP_ENV_LOGGER_LEVEL` (default `debug`) sets the logger-level floor. Transports without their own level inherit it.
+- **`debug()` is gated.** It emits only when `DEBUG=true` and `NODE_ENV` is unset or listed in `Environment.COMMON_ENVS`. Extend that set via `APP_ENV_EXTRA_LOG_ENVS`. The check runs once at module load - runtime env changes need a restart.
 
-### Logger Caching
+**Log levels**
 
-Both methods use internal caching -- the same scope always returns the same `Logger` instance:
+Five levels, each with a direct method: `debug`, `info`, `warn`, `error`, `emerg`. The generic `.log(level, ...)` remains for picking the level dynamically. What each level means, and when to use it, is in the [level guide](/extensions/helpers/logger/reference#what-each-level-means).
 
-```typescript
-const logger1 = Logger.get('MyService');
-const logger2 = Logger.get('MyService');
-// logger1 === logger2 (same instance)
-```
+**Transports**
 
-### ApplicationLogger Alias
+| Transport | Turns on when |
+|-----------|---------------|
+| Console | Always |
+| Daily-rotating file | `APP_ENV_LOGGER_FOLDER_PATH` is set |
+| UDP (`DgramTransport`) | All four UDP `APP_ENV_LOGGER_DGRAM_*` variables are set |
 
-`ApplicationLogger` is exported as both a value and a type alias for `Logger`, providing backward compatibility:
-
-```typescript
-import { ApplicationLogger } from '@venizia/ignis-helpers';
+Output shape (plain text or JSON) follows `APP_ENV_LOGGER_FORMAT`. Color codes appear only on the console, and only in a development `NODE_ENV` - file and UDP output never carries ANSI escapes. See [Color](./reference#color) to override.
 
-const logger = ApplicationLogger.get('MyService');
-```
+For extreme hot paths, `HfLogger` is a separate ring-buffer logger outside this pipeline, with its own [usage guide](/extensions/helpers/logger/hf-logger). The [Full reference](/extensions/helpers/logger/reference) covers everything else, including the `ApplicationLogger` facade.
 
-## Usage
+## Common tasks
 
-### Log Levels
+### Get a scoped logger
 
-The `Logger` class exposes direct methods for `info`, `warn`, `error`, `emerg`, and `debug`. Other levels (`alert`, `http`, `verbose`, `silly`) are accessible through the generic `log()` method.
+Use `LoggerFactory.getLogger` with an array of scope segments, or `ApplicationLogger.get` with a single string. Both cache by scope and follow the registered provider.
 
 ```typescript
-logger.info('User created');
-logger.warn('Rate limit approaching');
-logger.error('Failed to process payment');
-logger.emerg('System out of memory');
-logger.debug('Query took 12ms');            // Requires DEBUG=true
-logger.log('alert', 'Threshold exceeded');  // Generic method for any level
-```
+import { ApplicationLogger, LoggerFactory } from '@venizia/ignis-helpers';
 
-The `LogLevels` class defines all available levels and provides validation:
-
-```typescript
-import { LogLevels } from '@venizia/ignis-helpers';
-import type { TLogLevel } from '@venizia/ignis-helpers';
-
-LogLevels.ERROR;   // 'error'
-LogLevels.ALERT;   // 'alert'
-LogLevels.EMERG;   // 'emerg'
-LogLevels.WARN;    // 'warn'
-LogLevels.INFO;    // 'info'
-LogLevels.HTTP;    // 'http'
-LogLevels.VERBOSE; // 'verbose'
-LogLevels.DEBUG;   // 'debug'
-LogLevels.SILLY;   // 'silly'
-
-LogLevels.isValid('info');    // true
-LogLevels.isValid('unknown'); // false
-
-const level: TLogLevel = 'info';
+const scoped = LoggerFactory.getLogger(['Payment', 'Stripe']); // [Payment-Stripe]
+const direct = ApplicationLogger.get('MyService');             // [MyService]
 ```
 
-#### Winston Level Priority
+### Scope logs to a method
 
-The `defineCustomLogger` function configures Winston with these numeric priorities by default:
-
-| Level | Priority | Color |
-|-------|----------|-------|
-| `error` | 0 | red |
-| `alert` | 0 | red |
-| `emerg` | 0 | red |
-| `warn` | 1 | yellow |
-| `info` | 2 | green |
-| `http` | 3 | magenta |
-| `verbose` | 4 | gray |
-| `debug` | 5 | blue |
-| `silly` | 6 | gray |
-
-Lower numeric values have higher priority. `error`, `alert`, and `emerg` share priority `0`.
-
-### Method-Scoped Logging
-
-The `.for()` method creates a sub-scoped logger for specific methods, appending the method name to the scope with a `-` separator. The resulting logger is also cached.
+`.for()` appends a method name to the current scope so every line in that method self-identifies.
 
 ```typescript
 class UserService {
@@ -176,455 +72,85 @@ class UserService {
   async createUser(data: CreateUserDto) {
     this.logger.for('createUser').info('Creating user: %j', data);
     // Output: [UserService-createUser] Creating user: {...}
-
-    try {
-      const user = await this.userRepo.create({ data });
-      this.logger.for('createUser').info('User created: %s', user.id);
-      return user;
-    } catch (error) {
-      this.logger.for('createUser').error('Failed to create user: %s', error);
-      throw error;
-    }
   }
 }
 ```
 
-### Logging Errors: `%s`, Never `%j`
+### Log an Error with `%s`, never `%j`
 
-`message` and `stack` are non-enumerable properties on a native `Error`. `%j` formats via `JSON.stringify`, which only visits enumerable own properties, so `logger.error('Failed: %j', error)` silently drops both `message` and `stack` -- the two fields the log line exists to capture. Always pair an `Error` argument with `%s`; reserve `%j`/`%o` for plain data objects.
+`%s` routes the error through `ErrorPrettier`, which projects it down to identity, cause and frames. `%j` keeps every enumerable own property instead, so a driver error takes its whole query along and a `jose` error its whole payload. Always pair an `Error` argument with `%s`.
 
 ```typescript
-// ✅ Good - %s prints message + stack
-logger.error('Failed to create user: %s', error);
-
-// ❌ Bad - %j drops message and stack (non-enumerable on Error)
-logger.error('Failed to create user: %j', error);
+logger.error('Failed to create user: %s', error); // prints message + stack
 ```
 
-### Object Inspection Depth for `%s`
-
-Node hard-codes `depth: 0` for `%s` in `util.format` -- an object passed to `%s` collapses to `[Object]`, hiding the nested `extra` or `cause` a wrapped error carries. IGNIS's formatter (`formatLogMessage`/`deepSplat`) pre-inspects any object bound to a `%s` placeholder before handing the message to Winston, widening that depth so nested fields print instead of collapsing.
+A mistaken `%j` is no longer a silent loss: the formatter projects `message` and `stack` in before `JSON.stringify` runs, which on its own would drop both (they are non-enumerable). It is still the wrong placeholder for an error.
 
-```typescript
-logger.error('Failed: %s', error); // nested `error.cause` is now visible, not `[Object]`
-```
+### Keep a driver error readable with `ErrorPrettier`
 
-The inspection depth defaults to `5` and is configurable via `APP_ENV_LOGGER_INSPECT_DEPTH`:
-
-```bash
-APP_ENV_LOGGER_INSPECT_DEPTH=8
-```
-
-The value must be a non-negative integer. An absent, empty, negative, or unparseable value falls back to the default of `5` -- there is no "unlimited" setting.
-
-### Log Formats
-
-The logger supports two output formats, controlled by the `APP_ENV_LOGGER_FORMAT` environment variable (default: `text`).
-
-The `LoggerFormats` class provides constants and validation:
+`%s` prints the whole object. A `pg` or `drizzle` failure carries the statement in `message`, again in `stack`, and again in `query` - one failure floods the log with the same SQL several times. Wrap it:
 
 ```typescript
-import { LoggerFormats } from '@venizia/ignis-helpers';
-import type { TLoggerFormat } from '@venizia/ignis-helpers';
-
-LoggerFormats.JSON;              // 'json'
-LoggerFormats.TEXT;              // 'text'
-LoggerFormats.isValid('json');   // true
+import { ErrorPrettier } from '@venizia/ignis-helpers';
 
-const fmt: TLoggerFormat = 'text';
+logger.error('Failed to create user | %s', ErrorPrettier.format({ error }));
 ```
 
-#### JSON Format
+You get the identity, the root `cause` with its code, the driver's `hint`, the full message and the top stack frames - each on its own line, with the message's real newlines intact. The duplicated statement and the noisy driver internals are gone.
 
-```bash
-APP_ENV_LOGGER_FORMAT=json
-```
+Pass `includeStack: false` when the error is one you raised yourself and the frames add nothing. For a JSON sink, `ErrorPrettier.summarize({ error })` returns the same projection as a typed object instead of a string.
 
-Output:
+### Switch the output format
 
-```json
-{"level":"info","message":"[UserService] User created","timestamp":"2024-01-11T10:30:00.000Z","label":"APP"}
-```
-
-#### Pretty Text Format (Default)
+`APP_ENV_LOGGER_FORMAT` controls plain text (default) vs. JSON output.
 
 ```bash
-APP_ENV_LOGGER_FORMAT=text
-```
-
-Output:
-
-```
-2024-01-11T10:30:00.000Z [APP] info: [UserService] User created
-```
-
-> [!NOTE]
-> The label shown in log output (e.g. `APP`) comes from `APP_ENV_APPLICATION_NAME` (defaults to `'APP'`). Set this env var to customize the label for your application.
-
-#### Custom Formatters
-
-Build formatters directly using the exported helper functions:
-
-```typescript
-import {
-  defineLogFormatter,
-  defineJsonLoggerFormatter,
-  definePrettyLoggerFormatter,
-} from '@venizia/ignis-helpers';
-
-// Auto-detect from APP_ENV_LOGGER_FORMAT (or override with format option)
-const formatter = defineLogFormatter({ label: 'my-app' });
-const jsonFmt = defineLogFormatter({ label: 'my-app', format: 'json' });
-
-// Or use specific formatters directly
-const jsonFormatter = defineJsonLoggerFormatter({ label: 'my-app' });
-const prettyFormatter = definePrettyLoggerFormatter({ label: 'my-app' });
-```
-
-### Transports
-
-Every logger created by `defineCustomLogger` always includes a **Console** transport at the `debug` level. File and UDP transports are optional.
-
-#### File Rotation (DailyRotateFile)
-
-Configure file rotation through environment variables or programmatically via `IFileTransportOptions`.
-
-**Environment variables:**
-
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `APP_ENV_LOGGER_FOLDER_PATH` | `./` | Log files directory |
-| `APP_ENV_LOGGER_FILE_FREQUENCY` | `1h` | Rotation frequency |
-| `APP_ENV_LOGGER_FILE_MAX_SIZE` | `100m` | Max file size before rotation |
-| `APP_ENV_LOGGER_FILE_MAX_FILES` | `5d` | Retention period |
-| `APP_ENV_LOGGER_FILE_DATE_PATTERN` | `YYYYMMDD_HH` | Date pattern in filename |
-
-**Programmatic configuration:**
-
-```typescript
-import { defineCustomLogger, applicationLogFormatter } from '@venizia/ignis-helpers';
-
-const customLogger = defineCustomLogger({
-  loggerFormatter: applicationLogFormatter,
-  transports: {
-    info: {
-      file: {
-        prefix: 'my-app',
-        folder: './logs',
-        frequency: '24h',
-        maxSize: '500m',
-        maxFiles: '30d',
-        datePattern: 'YYYYMMDD',
-      },
-    },
-    error: {
-      file: {
-        prefix: 'my-app-error',
-        folder: './logs',
-        maxFiles: '90d',
-      },
-    },
-  },
-});
-```
-
-Generated filename pattern: `{folder}/{prefix}-info-{DATE}.log` or `{folder}/{prefix}-error-{DATE}.log`.
-
-#### IFileTransportOptions
-
-```typescript
-interface IFileTransportOptions {
-  prefix: string;       // Filename prefix (required)
-  folder: string;       // Output directory (required)
-  frequency?: string;   // Rotation frequency (default: '1h')
-  maxSize?: string;     // Max file size (default: '100m')
-  maxFiles?: string;    // Retention period (default: '5d')
-  datePattern?: string; // Date pattern in filename (default: 'YYYYMMDD_HH')
-}
-```
-
-#### UDP Transport (DgramTransport)
-
-The `DgramTransport` is a custom Winston transport that sends log entries over UDP. It supports level-based filtering -- only messages matching the configured `levels` set are forwarded.
-
-```typescript
-import { DgramTransport } from '@venizia/ignis-helpers';
-
-const transport = new DgramTransport({
-  label: 'my-app',
-  host: '127.0.0.1',
-  port: 5000,
-  levels: ['error', 'warn', 'info'],
-  socketOptions: { type: 'udp4' },
-});
-```
-
-**Static factory with validation** -- returns `null` if any required field is missing:
-
-```typescript
-const transport = DgramTransport.fromPartial({
-  label: 'my-app',
-  host: '127.0.0.1',
-  port: 5000,
-  levels: ['error', 'warn'],
-  socketOptions: { type: 'udp4' },
-});
-// Returns null if label, host, port, levels (non-empty), or socketOptions is missing
-```
-
-The transport automatically re-establishes the UDP socket if it encounters an error.
-
-**Environment variables for the default application logger:**
-
-| Variable | Description |
-|----------|-------------|
-| `APP_ENV_LOGGER_DGRAM_HOST` | UDP log aggregator host |
-| `APP_ENV_LOGGER_DGRAM_PORT` | UDP log aggregator port |
-| `APP_ENV_LOGGER_DGRAM_LABEL` | Label to identify log source |
-| `APP_ENV_LOGGER_DGRAM_LEVELS` | Comma-separated levels to send via UDP |
-
-#### IDgramTransportOptions
-
-```typescript
-interface IDgramTransportOptions extends Transport.TransportStreamOptions {
-  label: string;                      // Label to identify log source
-  host: string;                       // UDP host
-  port: number;                       // UDP port
-  levels: Array<string>;              // Levels to forward over UDP
-  socketOptions: dgram.SocketOptions; // Node.js dgram socket options
-}
-```
-
-#### ICustomLoggerOptions
-
-```typescript
-interface ICustomLoggerOptions {
-  logLevels?: { [name: string | symbol]: number };
-  logColors?: { [name: string | symbol]: string };
-  loggerFormatter?: ReturnType<typeof winston.format.combine>;
-  transports: {
-    info: {
-      file?: IFileTransportOptions;
-      dgram?: Partial<IDgramTransportOptions>;
-    };
-    error: {
-      file?: IFileTransportOptions;
-      dgram?: Partial<IDgramTransportOptions>;
-    };
-  };
-}
+APP_ENV_LOGGER_FORMAT=text   # 2024-01-11T10:30:00.000Z [APP] info: [UserService] User created
+APP_ENV_LOGGER_FORMAT=json   # {"level":"info","message":"[UserService] User created", ...}
 ```
 
-Both `info` and `error` transport groups support optional `file` (DailyRotateFile) and `dgram` (UDP) transports. A console transport is always included. Error file transports are also registered as exception handlers.
-
-### Debug Logging Behavior
+The `[APP]` label comes from `APP_ENV_APPLICATION_NAME` (defaults to `'APP'`).
 
-Debug logs require **both** conditions to be met:
+### Enable daily file rotation
 
-1. `DEBUG=true` environment variable is set (parsed via `toBoolean`)
-2. `NODE_ENV` is either unset **or** is present in the `Environment.COMMON_ENVS` set
-
-The `COMMON_ENVS` set includes: `local`, `debug`, `development`, `dev`, `sit`, `uat`, `alpha`, `beta`, `staging`, `production`. You can extend this set with `APP_ENV_EXTRA_LOG_ENVS`:
+Point `APP_ENV_LOGGER_FOLDER_PATH` at a directory. Rotation frequency, size cap, and retention are also env-driven. Without this variable, no log files are written - console (and UDP, if configured) remain the only outputs.
 
 ```bash
-DEBUG=true
-NODE_ENV=development
-APP_ENV_EXTRA_LOG_ENVS=qa,preview   # Comma-separated additional environments
-```
-
-> [!IMPORTANT]
-> The debug flag check is pre-computed at module load time. Changing `DEBUG` or `NODE_ENV` at runtime has no effect -- the values are captured once when the module is first imported.
-
-### High-Frequency Logger (HfLogger)
-
-For performance-critical applications (e.g., HFT systems, game servers), `HfLogger` provides zero-allocation logging via a lock-free ring buffer backed by `SharedArrayBuffer`.
-
-```typescript
-import { HfLogger, HfLogFlusher } from '@venizia/ignis-helpers';
-
-// At initialization time (once):
-const logger = HfLogger.get('OrderEngine');
-const MSG_ORDER_SENT = HfLogger.encodeMessage('Order sent');
-const MSG_ORDER_FILLED = HfLogger.encodeMessage('Order filled');
-
-// Start background flusher
-const flusher = new HfLogFlusher();
-flusher.start(100); // Flush every 100ms
-
-// In hot path (~100-300ns, zero allocation):
-logger.log('info', MSG_ORDER_SENT);
-logger.log('info', MSG_ORDER_FILLED);
+APP_ENV_LOGGER_FOLDER_PATH=./app_data/logs
+APP_ENV_LOGGER_FILE_MAX_FILES=30d
 ```
 
-#### HfLogger API
-
-| Method | Signature | Description |
-|--------|-----------|-------------|
-| `HfLogger.get` | `(scope: string) => HfLogger` | Get or create a cached logger instance |
-| `HfLogger.encodeMessage` | `(msg: string) => Uint8Array` | Pre-encode a message string to bytes (cached) |
-| `logger.log` | `(level: THfLogLevel, messageBytes: Uint8Array) => void` | Write entry to ring buffer |
-
-Supported levels: `debug` (0), `info` (1), `warn` (2), `error` (3), `emerg` (4).
+| Setting | Default |
+|---|---|
+| Rotation frequency | `1h` |
+| Max file size | `100m` |
+| Retention | `5d` |
 
-#### HfLogFlusher API
+Full programmatic configuration - custom prefixes, custom retention - is in the [Full reference](/extensions/helpers/logger/reference).
 
-| Method | Signature | Description |
-|--------|-----------|-------------|
-| `flusher.flush` | `() => Promise<void>` | Flush all buffered entries to output |
-| `flusher.start` | `(intervalMs?: number) => void` | Start background flush loop (default: `100`ms) |
+### Forward logs over UDP
 
-#### Ring Buffer Entry Format
-
-Each entry occupies exactly 256 bytes in a 64K-entry (16MB) `SharedArrayBuffer`:
-
-| Offset | Size | Field |
-|--------|------|-------|
-| 0-7 | 8 bytes | Timestamp (`BigInt64`, nanosecond precision) |
-| 8 | 1 byte | Level (`0`=debug, `1`=info, `2`=warn, `3`=error, `4`=emerg) |
-| 9-40 | 32 bytes | Scope (fixed-width, padded) |
-| 41-255 | 215 bytes | Message (fixed-width, truncated if longer) |
-
-The buffer wraps around at 65,536 entries using bitwise AND masking (`writeIndex & (BUFFER_SIZE - 1)`).
-
-> [!WARNING]
-> Pre-encode messages at initialization time using `HfLogger.encodeMessage()`. Calling it in the hot path defeats the zero-allocation purpose because it triggers string encoding on every log call.
-
-### Environment Variables
-
-#### Core Configuration
-
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `APP_ENV_APPLICATION_NAME` | `APP` | Label prefix shown in all log output |
-| `DEBUG` | `false` | Enable debug-level logging |
-| `NODE_ENV` | _(unset)_ | Must be in `COMMON_ENVS` or unset for debug to activate |
-| `APP_ENV_EXTRA_LOG_ENVS` | _(empty)_ | Comma-separated additional environments to allow debug |
-| `APP_ENV_LOGGER_FORMAT` | `text` | Output format (`json` or `text`) |
-| `APP_ENV_LOGGER_FOLDER_PATH` | `./` | Log files directory |
-| `APP_ENV_LOGGER_INSPECT_DEPTH` | `5` | Object inspection depth for `%s` placeholders. Non-negative integer only; invalid or absent falls back to `5` |
-
-#### File Rotation
-
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `APP_ENV_LOGGER_FILE_FREQUENCY` | `1h` | Rotation frequency |
-| `APP_ENV_LOGGER_FILE_MAX_SIZE` | `100m` | Max file size before rotation |
-| `APP_ENV_LOGGER_FILE_MAX_FILES` | `5d` | Retention period |
-| `APP_ENV_LOGGER_FILE_DATE_PATTERN` | `YYYYMMDD_HH` | Date pattern in filename |
-
-#### UDP Transport
-
-| Variable | Description |
-|----------|-------------|
-| `APP_ENV_LOGGER_DGRAM_HOST` | UDP log aggregator host |
-| `APP_ENV_LOGGER_DGRAM_PORT` | UDP log aggregator port |
-| `APP_ENV_LOGGER_DGRAM_LABEL` | Label to identify log source |
-| `APP_ENV_LOGGER_DGRAM_LEVELS` | Comma-separated levels to send via UDP |
-
-#### Example `.env`
+Set all four `APP_ENV_LOGGER_DGRAM_*` variables - the transport is silently skipped if any one is missing.
 
 ```bash
-# Application
-APP_ENV_APPLICATION_NAME=my-service
-
-# Core
-DEBUG=true
-APP_ENV_LOGGER_FORMAT=json
-APP_ENV_LOGGER_FOLDER_PATH=./app_data/logs
-APP_ENV_LOGGER_INSPECT_DEPTH=5
-
-# File rotation
-APP_ENV_LOGGER_FILE_FREQUENCY=24h
-APP_ENV_LOGGER_FILE_MAX_SIZE=500m
-APP_ENV_LOGGER_FILE_MAX_FILES=30d
-
-# UDP transport
 APP_ENV_LOGGER_DGRAM_HOST=127.0.0.1
 APP_ENV_LOGGER_DGRAM_PORT=5000
 APP_ENV_LOGGER_DGRAM_LABEL=my-app
 APP_ENV_LOGGER_DGRAM_LEVELS=error,warn,info
 ```
 
-## API Summary
-
-| Export | Kind | Description |
-|--------|------|-------------|
-| `Logger` | class | Scoped logger with caching, wraps a Winston logger instance |
-| `ApplicationLogger` | value + type alias | Backward-compatible alias for `Logger` |
-| `LoggerFactory` | class | Factory that creates `Logger` from scope arrays |
-| `HfLogger` | class | Zero-allocation ring-buffer logger |
-| `HfLogFlusher` | class | Background flusher for `HfLogger` |
-| `LogLevels` | class (constants) | Log level constants (`ERROR`, `ALERT`, `EMERG`, `WARN`, `INFO`, `HTTP`, `VERBOSE`, `DEBUG`, `SILLY`) with `isValid()` |
-| `LoggerFormats` | class (constants) | Format constants (`JSON`, `TEXT`) with `isValid()` |
-| `defineCustomLogger` | `(opts: ICustomLoggerOptions) => winston.Logger` | Create a fully configured Winston logger |
-| `defineLogFormatter` | `(opts: { label: string; format?: TLoggerFormat }) => winston.Logform.Format` | Create a formatter (auto-detects format from env) |
-| `defineJsonLoggerFormatter` | `(opts: { label: string }) => winston.Logform.Format` | Create a JSON formatter |
-| `definePrettyLoggerFormatter` | `(opts: { label: string }) => winston.Logform.Format` | Create a pretty text formatter |
-| `applicationLogFormatter` | `winston.Logform.Format` | Pre-built formatter using `APP_ENV_APPLICATION_NAME` label |
-| `applicationLogger` | `winston.Logger` | Pre-built default Winston logger instance |
-| `DgramTransport` | class | Custom Winston transport for UDP logging |
-| `TLogLevel` | type | Union of all log level string literals |
-| `TLoggerFormat` | type | Union of `'json' \| 'text'` |
-| `IFileTransportOptions` | interface | Options for daily-rotating file transport |
-| `ICustomLoggerOptions` | interface | Options for `defineCustomLogger` |
-| `IDgramTransportOptions` | interface | Options for `DgramTransport` |
-
-## Troubleshooting
-
-### Debug logs not appearing
-
-**Cause:** Debug logging requires both `DEBUG=true` AND a `NODE_ENV` that is either unset or present in the `COMMON_ENVS` set. These values are pre-computed at module load time.
-
-**Fix:**
-1. Verify `DEBUG=true` is set in your environment.
-2. Verify `NODE_ENV` is set to one of: `local`, `debug`, `development`, `dev`, `sit`, `uat`, `alpha`, `beta`, `staging`, `production` -- or is unset entirely.
-3. If you use a custom environment name (e.g. `qa`), add it to `APP_ENV_EXTRA_LOG_ENVS=qa`.
-
-```bash
-DEBUG=true NODE_ENV=development bun run server:dev
-```
-
-### "[defineLogger] Invalid logger format | format: {format} | valids: json,text"
-
-**Cause:** The `format` option passed to `defineLogFormatter` (or the `APP_ENV_LOGGER_FORMAT` environment variable) is not `json` or `text`.
-
-**Fix:** Set `APP_ENV_LOGGER_FORMAT` to either `json` or `text`:
-
-```bash
-APP_ENV_LOGGER_FORMAT=text
-```
-
-### UDP transport not sending logs
-
-**Cause:** `DgramTransport.fromPartial()` returns `null` if any required option is missing (`label`, `host`, `port`, `levels` with at least one entry, or `socketOptions`). The transport is silently not registered.
-
-**Fix:**
-1. Ensure **all four** dgram env vars are set: `APP_ENV_LOGGER_DGRAM_HOST`, `APP_ENV_LOGGER_DGRAM_PORT`, `APP_ENV_LOGGER_DGRAM_LABEL`, and `APP_ENV_LOGGER_DGRAM_LEVELS`.
-2. `APP_ENV_LOGGER_DGRAM_LEVELS` must contain at least one level (e.g. `error,warn,info`). An empty value results in no transport.
-3. Verify the UDP aggregator is reachable from your host (firewall, port binding).
-
-### Log label shows "APP" instead of application name
-
-**Cause:** The default label comes from `Defaults.APPLICATION_NAME`, which reads `APP_ENV_APPLICATION_NAME`. If the env var is not set, it falls back to `'APP'`.
-
-**Fix:** Set `APP_ENV_APPLICATION_NAME` in your environment:
-
-```bash
-APP_ENV_APPLICATION_NAME=my-service
-```
-
-## See Also
-
-- **Related Concepts:**
-  - [Services](/guides/core-concepts/services) -- Logging in services
-  - [Controllers](/guides/core-concepts/rest-controllers) -- Logging in controllers
+## See also
 
-- **Other Helpers:**
-  - [Helpers Index](../index) -- All available helpers
+- [Full reference](/extensions/helpers/logger/reference) - every export, transport option, log level, and edge case
+- [Services](/guides/core-concepts/services) - logging in services
+- [Controllers](/guides/core-concepts/rest-controllers) - logging in controllers
+- [Helpers Overview](/extensions/helpers/) - all available helpers
+- [Request Tracker Component](/extensions/components/request-tracker) - request logging
+- [Winston documentation](https://github.com/winstonjs/winston) - underlying logging library
 
-- **References:**
-  - [Request Tracker Component](/extensions/components/request-tracker) -- Request logging
+**Files:**
 
-- **External Resources:**
-  - [Winston Documentation](https://github.com/winstonjs/winston) -- Winston logging library
-  - [winston-daily-rotate-file](https://github.com/winstonjs/winston-daily-rotate-file) -- File rotation transport
+- [`packages/helpers/src/modules/logger/common/types.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/helpers/src/modules/logger/common/types.ts) - `ILogger`, the contract every consumer types against
+- [`packages/helpers/src/modules/logger/winston/logger.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/helpers/src/modules/logger/winston/logger.ts) - `WinstonLogger`, `Logger` alias
+- [`packages/helpers/src/modules/logger/factory.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/helpers/src/modules/logger/factory.ts) - `LoggerFactory`, `ApplicationLogger`
+- [`packages/helpers/src/modules/logger/winston/define.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/helpers/src/modules/logger/winston/define.ts) - Winston setup, transports, env configuration