logixia 1.12.5 → 1.13.0

package/README.md

@@ -520,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
@@ -531,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
@@ -540,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
@@ -644,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',
@@ -800,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',
@@ -811,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
@@ -823,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',
@@ -861,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',
@@ -1285,22 +1316,28 @@ logixia ships this as a dedicated `logixia/correlation` sub-package. It uses the
 ```typescript
 import { correlationMiddleware } from 'logixia/correlation';
 
-// Zero-config — reads X-Correlation-ID / X-Request-ID from the incoming request.
-// Generates a UUID v4 if no header is present.
+// Zero-config — reads X-Correlation-ID from the incoming request.
+// Generates a UUID v4 if the header is missing or invalid.
 // Sets X-Correlation-ID on the response.
 app.use(correlationMiddleware());
 
 // Custom config:
 app.use(
   correlationMiddleware({
-    header: 'X-Correlation-ID', // header to read / write. Default: 'X-Correlation-ID'
-    generateId: () => crypto.randomUUID(),
+    header: 'X-Correlation-ID', // header to read / write (matched case-insensitively). Default: 'x-correlation-id'
+    generate: () => crypto.randomUUID(), // used when no usable incoming ID. Default: crypto.randomUUID()
     trustIncoming: true, // honour the header from the client. Default: true
     setResponseHeader: true, // echo the ID back in the response. Default: true
   })
 );
 ```
 
+An incoming ID is only used if it is at most 128 characters long and contains only
+`A-Z`, `a-z`, `0-9`, `.`, `_`, `:` and `-`. Anything else (newlines, spaces, or base64-style
+`+`, `/`, `=`) is replaced with a freshly generated ID, so client-supplied text can't end up in
+every log line. Set `trustIncoming: false` to ignore the incoming header entirely and always
+generate a new ID. `correlationFastifyHook()` takes the same options.
+
 ### Correlation Fastify hook
 
 ```typescript
@@ -1502,6 +1539,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
@@ -1777,6 +1821,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
@@ -1821,11 +1867,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
@@ -2202,10 +2253,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';
@@ -2535,11 +2586,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;
         }