logixia 1.12.4 → 1.12.6

package/README.md

@@ -202,24 +202,26 @@ logixia takes a different approach: **everything ships built-in, and nothing blo
 
 ## Performance
 
-logixia is async-first and built for the hot path: a synchronous fast path for in-process transports (no Promise allocated when the write completes synchronously), a millisecond-cached timestamp, lazy formatting (each transport formats once — no wasted pre-format), and per-call work (level check, namespace resolution, redaction decision) served off pre-built caches. The result: logixia **beats pino on 5 of 6 real-world scenarios**, beats winston and bunyan across the board, and keeps **p99 latency at 1–3µs** with no tail spikes.
+logixia is async-first and built for the hot path: a synchronous fast path for in-process transports (no Promise allocated when the write completes synchronously), a millisecond-cached timestamp, lazy formatting (each transport formats once), and per-call work (level check, namespace resolution, redaction decision) served off pre-built caches.
 
-Benchmarked against **pino, winston, and bunyan** — all writing to `/dev/null` (pure serialization + framework overhead, no disk/terminal cost). Node 20, Apple M-series; numbers are ops/sec, higher is better. Reproduce with `npm run benchmark`.
+Every library below writes the **same JSON output** to a null sink, so this measures serialization and framework overhead, not disk or terminal speed. Node 22, Apple Silicon, ops/sec (higher is better). Reproduce with `npm run benchmark`.
 
-| Scenario                       |      pino |   **logixia** |   winston |  bunyan |
-| ------------------------------ | --------: | ------------: | --------: | ------: |
-| Simple string log              | 3,220,000 |     2,769,000 | 1,577,000 | 707,000 |
-| **Structured log (5 fields)**  | 1,319,000 | **1,536,000** |   699,000 | 536,000 |
-| **Error object logging**       |   907,000 | **1,940,000** | 1,062,000 | 573,000 |
-| **Child / per-request logger** | 1,093,000 | **1,436,000** |   321,000 | 380,000 |
-| **Deep nested object**         |   891,000 | **1,040,000** |   435,000 | 442,000 |
-| **High-cardinality (12 flds)** |   651,000 | **1,027,000** |   316,000 | 404,000 |
+| Scenario                     |      pino | logixia (json) |   winston |
+| ---------------------------- | --------: | -------------: | --------: |
+| Simple string log            | 3,396,000 |      1,804,000 | 1,533,000 |
+| Structured log (5 fields)    | 1,308,000 |        931,000 |   729,000 |
+| Error object logging         | 1,192,000 |      1,587,000 | 1,078,000 |
+| Child / per-request logger   | 1,134,000 |        892,000 |   494,000 |
+| Deep nested object           | 1,327,000 |      1,023,000 |   549,000 |
+| High-cardinality (12 fields) |   734,000 |        525,000 |   400,000 |
 
 **What this means:**
 
-- ✅ **logixia is faster than pino on 5 of 6 scenarios** — including **+114% on error logging**, **+58% on high-cardinality**, **+31% on child loggers**, and **+16% on structured logs** — the shapes that dominate real production traffic.
-- ✅ **logixia beats winston and bunyan in every scenario**, often by 2–3×, and avoids their tail-latency spikes (winston hit **3,038µs p99** on high-cardinality and **412µs** on deep objects; logixia stays **1–3µs p99** throughout).
-- ⚖️ **pino still wins the trivial simple-string case** (−14%) because it writes synchronously straight to `process.stdout` — fast in a microbenchmark, but it blocks the event loop under real I/O and is exactly the path behind pino's open [flush-on-exit log-loss bug](#graceful-shutdown). logixia stays non-blocking and guarantees delivery, and pulls ahead the moment you log anything structured.
+- **pino is the fastest raw JSON serializer here.** It leads in 5 of 6 scenarios, by 21–47%. If raw throughput is the only thing you need, pino is a great choice.
+- **logixia is 1.2–1.9× faster than winston in every scenario**, with p99 latency of 1–5µs, against winston's 2.5–7.5µs.
+- logixia is ahead on error logging, partly because pino also serializes the full stack through its error serializer.
+- logixia's default human-readable console format is faster than its JSON mode. `npm run benchmark` prints both.
+- The point of logixia is everything else in one package: non-blocking file and database transports, tracing, redaction, OpenTelemetry, NestJS and the CLI. It aims to be fast enough that you never notice it, without six extra installs.
 
 **Distinctive-feature throughput** (no cross-library equivalent — `npm run benchmark:features`):
 
@@ -518,9 +520,10 @@ const logger = createLogger({
     file: {
       filename: 'app.log',
       dirname: './logs',
-      maxSize: '50MB', // rotate when file reaches this size
-      maxFiles: 14, // keep 14 rotated files
+      maxSize: '50MB', // rotate before the file passes this size ('500KB', '1GB' or bytes)
+      maxFiles: 14, // keep the 14 newest rotated files, delete older ones
       zippedArchive: true, // compress old files with gzip
+      datePattern: 'YYYY-MM-DD', // optional: also rotate when the day changes
       format: 'json', // 'json' | 'text' | 'csv'
       batchSize: 100, // buffer up to 100 entries before writing
       flushInterval: 2000, // flush buffer every 2 seconds
@@ -529,6 +532,20 @@ const logger = createLogger({
 });
 ```
 
+The live file keeps its name, so `tail -f logs/app.log` keeps working. Rotated files are renamed beside it: `app-2026-10-22T09-30-00-000.log.gz`, or `app-2026-10-22.log.gz` when `datePattern` is set. Files are split on line boundaries, so no line is cut in half. On restart the transport carries on from the size of the existing `app.log`.
+
+**Bounding memory under load.** Entries wait in memory until the disk accepts them, and by default there is no limit. Set `maxQueue` to cap how many unwritten entries (the batch being written included) the transport holds, and `queuePolicy` to choose what happens at the cap:
+
+```typescript
+file: {
+  filename: 'app.log',
+  maxQueue: 10000,
+  queuePolicy: 'drop-oldest', // 'drop-oldest' (default) | 'drop-newest' | 'block'
+}
+```
+
+`drop-oldest` discards the oldest waiting entry, `drop-newest` discards the incoming one, and `block` makes `write()` wait until there is room. Dropped lines are counted and reported on stderr at most once every 5 seconds, and once more on `close()`.
+
 You can also use **time-based rotation** via the `rotation` sub-key:
 
 ```typescript
@@ -538,13 +555,18 @@ transports: {
     dirname: './logs',
     rotation: {
       interval: '1d',      // rotate daily: '1h' | '6h' | '12h' | '1d' | '1w'
+      maxSize: '100MB',    // and on size
       maxFiles: 30,
       compress: true,
+      // or decide yourself, checked before each write:
+      // shouldRotate: (file, { size, created }) => size > 100 * 1024 * 1024,
     },
   },
 },
 ```
 
+With a `rotation` block every file is timestamped, including the one being written.
+
 Multiple file transports are supported — pass an array:
 
 ```typescript
@@ -642,7 +664,7 @@ logixia includes built-in support for Datadog, Mixpanel, Segment, and Google Ana
 **Datadog** — sends logs, metrics, and traces to your Datadog account:
 
 ```typescript
-import { DataDogTransport } from 'logixia';
+import { DataDogTransport } from 'logixia/transports';
 
 const logger = createLogger({
   appName: 'api',
@@ -798,7 +820,7 @@ logixia ships three production-ready cloud transports. All are batched, non-bloc
 Batches log events and sends them to a CloudWatch Logs stream using `PutLogEvents`. Supports **EMF** (Embedded Metric Format) so numeric fields in your log entries are automatically promoted to CloudWatch Metrics — no separate SDK needed.
 
 ```typescript
-import { CloudWatchTransport } from 'logixia';
+import { CloudWatchTransport } from 'logixia/cloudwatch';
 
 const logger = createLogger({
   appName: 'api',
@@ -809,8 +831,7 @@ const logger = createLogger({
         region: 'us-east-1', // or set AWS_REGION env var
         logGroupName: '/app/api',
         logStreamName: 'api-server-1', // defaults to hostname + PID
-        // Credentials fall back to AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY env vars,
-        // or the EC2/ECS/Lambda metadata service — no hard-coding needed.
+        // Credentials: see "Credential sources" below — no hard-coding needed.
         batchSize: 100, // default: 100
         flushIntervalMs: 5000, // default: 5000
         emf: true, // emit numeric fields as CloudWatch Metrics
@@ -821,19 +842,31 @@ const logger = createLogger({
 });
 ```
 
-With `emf: true`, any numeric field in your log data is published as a CloudWatch Metric under the `Logixia` namespace:
+With `emf: true`, any numeric field in your log data is published as a CloudWatch Metric in the `Logixia` namespace (override with `emfNamespace`), with a `level` dimension:
 
 ```typescript
 await logger.info('Request completed', { duration: 142, statusCode: 200 });
-// → CloudWatch Metric: Logixia/duration, Logixia/statusCode
+// → CloudWatch Metrics in namespace "Logixia": duration, statusCode
 ```
 
+**Credential sources**, tried in this order (no SDK needed):
+
+1. `accessKeyId` / `secretAccessKey` / `sessionToken` in the transport config
+2. `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` / `AWS_SESSION_TOKEN`
+3. The shared credentials file: `~/.aws/credentials`, or `AWS_SHARED_CREDENTIALS_FILE`, using the `AWS_PROFILE` profile (default `default`)
+4. ECS container credentials: `AWS_CONTAINER_CREDENTIALS_RELATIVE_URI` or `AWS_CONTAINER_CREDENTIALS_FULL_URI` (with `AWS_CONTAINER_AUTHORIZATION_TOKEN` or `_FILE`)
+5. EC2 instance role through IMDSv2 (set `AWS_EC2_METADATA_DISABLED=true` to skip)
+
+Not supported: SSO, assume-role profiles, `credential_process`, web identity (EKS IRSA). If no source yields credentials, events stay buffered (and the buffer cap applies) rather than being dropped, and a warning is logged.
+
+The log group and stream are created on first use; an already-existing one is fine. The IAM role needs `logs:CreateLogGroup`, `logs:CreateLogStream` and `logs:PutLogEvents` (if the group and stream already exist, only `PutLogEvents` is required, and a failed `CreateLogGroup` is tolerated). Use `endpoint` to point at LocalStack or a VPC endpoint.
+
 ### Google Cloud Logging
 
 Maps logixia levels to GCP `severity` values (`DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`), auto-injects `logging.googleapis.com/trace` for Cloud Trace correlation, and supports Application Default Credentials (ADC) — no service account JSON required when running on GKE / Cloud Run / App Engine.
 
 ```typescript
-import { GCPTransport } from 'logixia';
+import { GCPTransport } from 'logixia/gcp';
 
 const logger = createLogger({
   appName: 'api',
@@ -859,7 +892,7 @@ const logger = createLogger({
 Sends logs to Azure Monitor via the **Logs Ingestion API** (Data Collection Rule). Uses OAuth2 client-credentials to obtain a bearer token automatically.
 
 ```typescript
-import { AzureMonitorTransport } from 'logixia';
+import { AzureMonitorTransport } from 'logixia/azure';
 
 const logger = createLogger({
   appName: 'api',
@@ -1500,6 +1533,13 @@ const logger = createLogger({
 
 Both `paths` and `patterns` can be combined in the same config.
 
+Path rules follow these conventions:
+
+- Matching is case-insensitive, so `req.headers.authorization` also redacts `Authorization`.
+- Array elements are addressed by index: `users.*.password` and `users.0.password` both match, and the older index-free form `users.password` still works. Nested arrays are walked the same way.
+- Circular references are printed as `[Circular]` instead of throwing.
+- Plain objects, class instances (ORM entities, documents) and arrays are walked. Built-ins such as `URL`, `Date`, `Buffer`, `Map`, `Set` and `Error` pass through unchanged unless a rule targets them directly.
+
 ---
 
 ## Timer API
@@ -1775,6 +1815,8 @@ const logger = createLogger({
 });
 ```
 
+`maxLogsPerSecond` is always enforced after the rate decision, including with `traceConsistent: true` (a kept trace can still lose entries once the cap is hit). With `traceConsistent`, a trace's keep/drop decision is remembered in a bounded LRU (100k traces, dropped after 5 minutes idle) and survives stats resets; logs written outside any trace are sampled one by one.
+
 ---
 
 ## Robust serialization
@@ -1819,11 +1861,16 @@ const logger = createLogger({
     enabled: true,
     timeout: 10_000, // wait up to 10 s; force-exits after
     signals: ['SIGTERM', 'SIGINT', 'SIGHUP'],
+    exit: 'auto', // 'auto' | 'always' | 'never'
   },
   transports: {/* ... */},
 });
 ```
 
+**Who ends the process.** By default (`exit: 'auto'`) logixia flushes and then exits only if its handler is the only listener for that signal. If your app registers its own `SIGTERM` handler (`server.close()`, NestJS shutdown hooks, ...), logixia just flushes and leaves the exit to you, so your cleanup is never cut off. When logixia does exit it uses `128 + signal number` (143 for SIGTERM, 130 for SIGINT), so supervisors see a signal exit. Set `exit: 'always'` or `exit: 'never'` to override. Registered loggers are also flushed (not closed) on `beforeExit`, so an app that keeps logging after the event loop first drains still writes.
+
+`flushOnExit` is configured by its first call; later calls with different `timeout`, `signals`, `exit` or hooks print a warning and are ignored.
+
 You can also call `flushOnExit` directly with lifecycle hooks:
 
 ```typescript
@@ -2200,10 +2247,10 @@ import {
   LogixiaExceptionFilter, // global exception filter
 } from 'logixia';
 
-// Cloud transports (import directly):
-import { CloudWatchTransport } from 'logixia';
-import { GCPTransport } from 'logixia';
-import { AzureMonitorTransport } from 'logixia';
+// Cloud transports (subpath imports):
+import { CloudWatchTransport } from 'logixia/cloudwatch';
+import { GCPTransport } from 'logixia/gcp';
+import { AzureMonitorTransport } from 'logixia/azure';
 
 // Plugin API:
 import type { LogixiaPlugin } from 'logixia';
@@ -2533,11 +2580,17 @@ interface LoggerConfig {
           level?: string;
           batchSize?: number;
           flushInterval?: number; // ms
+          maxQueue?: number; // cap on unwritten entries held in memory. Default: no cap
+          queuePolicy?: 'drop-oldest' | 'drop-newest' | 'block'; // Default: 'drop-oldest'
           rotation?: {
             interval?: '1h' | '6h' | '12h' | '1d' | '1w' | '1m' | '1y';
             maxSize?: string | number;
             maxFiles?: number;
             compress?: boolean;
+            shouldRotate?: (
+              currentFile: string,
+              stats: { size: number; created: Date; modified: Date }
+            ) => boolean;
           };
           filter?: (entry: TransportLogEntry) => boolean;
         }