ntlogger 3.0.0 → 4.0.0

package/index.d.ts

@@ -53,6 +53,11 @@ declare namespace logger {
      * Logger configuration options
      */
     export interface LoggerConfig {
+        /** Maximum in-flight callback promises; overflow drops newest callback, not the primary log. */
+        onLogMaxPending?: number;
+        onLog?: (record: Record<string, any>) => void | Promise<void>;
+        otel?: boolean | { loggerProvider?: { getLogger(name: string): { emit(record: any): void }; forceFlush?(): Promise<void> }; name?: string };
+        redact?: false | { extraKeys?: string[]; patterns?: boolean; replacement?: string; maxDepth?: number; maxStringLength?: number };
         /** Minimum log level to be logged */
         level?: LogLevel;
         /** Enable console logging (default: true) */
@@ -95,6 +100,9 @@ declare namespace logger {
      * Statistics object returned by getStats()
      */
     export interface LoggerStats {
+        levels: Record<string, number>;
+        hookErrors: number;
+        onLog: { pending: number; dropped: number; limit: number };
         sampling: {
             total: Record<string, number>;
             sampled: Record<string, number>;
@@ -199,6 +207,7 @@ declare namespace logger {
          * @returns Statistics object
          */
         getStats(): LoggerStats;
+        resetStats(): void;
 
         /**
          * Flush all pending logs (returns Promise)
@@ -227,6 +236,7 @@ declare function logger(location?: string, config?: logger.LoggerConfig): logger
 
 declare namespace logger {
     /** Opt in to process-wide signal handlers; returns an unregister function. */
+    function withSecretValues<T>(values: string[], callback: () => T): T;
     function setupSignalHandlers(options?: { timeout?: number }): () => void;
 }
 

package/index.js

@@ -114,4 +114,21 @@
  * Initial release
  */
 
-module.exports = require('./lib/logger');
+// Only the Winston entry point resolves these peers. Pino consumers never load it.
+for (const peer of ['winston', 'winston-transport']) {
+    try {
+        require.resolve(peer);
+    } catch (cause) {
+        if (cause.code !== 'MODULE_NOT_FOUND') throw cause;
+        const error = new Error(
+            `ntlogger's Winston backend requires ${peer}. Run: npm install winston winston-transport. ` +
+            `For Pino, import 'ntlogger/pino' instead.`,
+            { cause },
+        );
+        error.code = 'MODULE_NOT_FOUND';
+        throw error;
+    }
+}
+
+module.exports = require('./lib/logger');
+module.exports.withSecretValues = require('./lib/secretScope').withSecretValues;

package/lib/logObserver.js

@@ -0,0 +1,55 @@
+'use strict';
+const { AsyncLocalStorage } = require('node:async_hooks');
+const { withTimeout } = require('./lifecycle');
+
+// Counts represent serialized records, not confirmed delivery to any destination.
+function createLogObserver({ onLog, otel, onLogMaxPending = 100 } = {}) {
+    if (onLog !== undefined && typeof onLog !== 'function') throw new TypeError('onLog must be a function');
+    if (!Number.isSafeInteger(onLogMaxPending) || onLogMaxPending < 0) throw new TypeError('onLogMaxPending must be a nonnegative safe integer');
+    const scope = new AsyncLocalStorage();
+    const pending = new Set();
+    const counts = Object.fromEntries(['trace', 'debug', 'info', 'warn', 'error', 'fatal', 'internal'].map(k => [k, 0]));
+    let hookErrors = 0;
+    let dropped = 0;
+    const bridge = otel ? require('./pinoOtel').createOtelBridge(otel) : null;
+    const levelNames = { 10: 'trace', 20: 'debug', 30: 'info', 40: 'warn', 50: 'error', 60: 'fatal' };
+    function failure() { hookErrors++; }
+    function observe(record) {
+        const level = typeof record.level === 'number' ? levelNames[record.level] : record.level;
+        if (Object.hasOwn(counts, level)) counts[level]++;
+        // Suppress observers for logs made by an observer, including async descendants.
+        if (scope.getStore()) return;
+        scope.run(true, () => {
+            if (bridge) {
+                try { bridge.emit(record); } catch (_) { failure(); }
+            }
+            if (onLog) {
+                // In-flight promises cannot be cancelled: drop the newest callback only.
+                if (pending.size >= onLogMaxPending) { dropped++; return; }
+                try {
+                    // Mutation of the callback record cannot change output or OTel data.
+                    const result = onLog(JSON.parse(JSON.stringify(record)));
+                    if (result && typeof result.then === 'function') {
+                        const task = Promise.resolve(result).catch(failure);
+                        pending.add(task);
+                        task.finally(() => pending.delete(task));
+                    }
+                } catch (_) { failure(); }
+            }
+        });
+    }
+    return {
+        context: () => bridge ? bridge.context() : {},
+        observe,
+        streamWrite(line) { observe(JSON.parse(line)); return line; },
+        stats: () => ({ levels: { ...counts }, hookErrors, onLog: { pending: pending.size, dropped, limit: onLogMaxPending } }),
+        reset() { for (const key of Object.keys(counts)) counts[key] = 0; hookErrors = 0; dropped = 0; },
+        async flush(timeout = 5000) {
+            await withTimeout((async () => {
+                while (pending.size) await Promise.all([...pending]);
+                if (bridge) await bridge.flush();
+            })(), timeout, 'Log observers flush');
+        },
+    };
+}
+module.exports = { createLogObserver };

package/lib/logger.js

@@ -344,6 +344,8 @@ const createLoggerInstance = (location = "Unknown", config = {}, transports, par
         statsInterval = 0,
     } = config;
 
+    const observer = require('./logObserver').createLogObserver(config);
+    const redactor = config.redact === false ? null : require('./secretRedaction').createRedactor(config.redact);
     let logTransport = [].filter(Boolean);
 
     if (console) {
@@ -376,6 +378,13 @@ const createLoggerInstance = (location = "Unknown", config = {}, transports, par
     const logger = winston.createLogger({
         level: level,
         levels: customSettings.levels,
+        format: winston.format(info => {
+            const safe = redactor ? redactor.redactObject(info) : { ...info };
+            Object.assign(safe, observer.context());
+            Object.assign(info, safe);
+            observer.observe(safe);
+            return info;
+        })(),
         transports: logTransport,
         defaultMeta: {
             location,
@@ -469,10 +478,17 @@ const createLoggerInstance = (location = "Unknown", config = {}, transports, par
             sampling: sampler ? sampler.getStats() : null,
             deduplication: deduplicator ? deduplicator.getStats() : null,
             performance: perfTracker ? perfTracker.getStats() : null,
+            ...observer.stats(),
         };
         return stats;
     };
 
+    logger.resetStats = () => {
+        sampler?.resetStats();
+        deduplicator?.resetStats();
+        observer.reset();
+    };
+
     const timeout = config.shutdownTimeout ?? 30000;
     if (!Number.isFinite(timeout) || timeout <= 0) throw new Error('Invalid shutdownTimeout');
     let closePromise;
@@ -480,6 +496,7 @@ const createLoggerInstance = (location = "Unknown", config = {}, transports, par
     logger.flush = () => withTimeout((async () => {
         await drain(logger, state, timeout);
         await Promise.all(logger.transports.map(t => t.flush?.()));
+        await observer.flush(timeout);
         await drain(logger, state, timeout);
     })(), timeout, 'Logger flush');
 

package/lib/pinoOtel.js

@@ -0,0 +1,43 @@
+'use strict';
+
+// No SDK/provider is created or registered here. Export through the application's
+// existing logs provider in the calling thread, where active context is available.
+function createOtelBridge(options) {
+    const opts = options === true ? {} : options;
+    const api = require('@opentelemetry/api');
+    const provider = opts.loggerProvider || require('@opentelemetry/api-logs').logs.getLoggerProvider();
+    const logger = provider.getLogger(opts.name || 'ntlogger');
+    const severity = { 10: 1, 20: 5, 30: 9, 40: 13, 50: 17, 60: 21,
+        trace: 1, debug: 5, info: 9, warn: 13, error: 17, fatal: 21, internal: 1 };
+    const names = { 1: 'TRACE', 5: 'DEBUG', 9: 'INFO', 13: 'WARN', 17: 'ERROR', 21: 'FATAL' };
+    return {
+        context() {
+            const span = api.trace.getActiveSpan();
+            const ctx = span && span.spanContext();
+            return ctx && api.isSpanContextValid(ctx)
+                ? { traceId: ctx.traceId, spanId: ctx.spanId, traceFlags: ctx.traceFlags }
+                : {};
+        },
+        emit(record) {
+            const attributes = {};
+            for (const [key, value] of Object.entries(record)) {
+                if (['level', 'msg', 'message', 'time', 'timestamp'].includes(key) || value == null) continue;
+                attributes[key] = typeof value === 'object' ? JSON.stringify(value) : value;
+            }
+            if (record.err) {
+                if (record.err.type) attributes['exception.type'] = record.err.type;
+                if (record.err.message) attributes['exception.message'] = record.err.message;
+                if (record.err.stack) attributes['exception.stacktrace'] = record.err.stack;
+            }
+            const severityNumber = severity[record.level] || 9;
+            logger.emit({
+                context: api.context.active(),
+                timestamp: new Date(record.time ?? record.timestamp ?? Date.now()),
+                severityNumber, severityText: names[severityNumber],
+                body: record.msg ?? record.message ?? '', attributes,
+            });
+        },
+        flush: () => typeof provider.forceFlush === 'function' ? provider.forceFlush() : Promise.resolve(),
+    };
+}
+module.exports = { createOtelBridge };

package/lib/secretRedaction.js

@@ -87,6 +87,10 @@ const DEFAULT_KEYS = Object.freeze([
     'webhookurl',
     'snmpcommunity',
     'community_string',
+    'community',
+    'authPassword',
+    'privPassword',
+    'passphrase',
 ]);
 
 /*
@@ -145,6 +149,9 @@ const KV_SECRET = /(?<pre>\b(?:api[_-]?key|apikey|access[_-]?key|access[_-]?toke
  */
 const GENERIC_KV = /(?<pre>\b(?:password|passwd|secret|token|api[_-]?key)\s*[=:]\s*)(?!["'[])\S+/gi;
 
+/** Scanner credentials in free text, including short and quoted values. */
+const SCANNER_SECRET = /(?<pre>["']?\b(?:snmp[_-]?community|community(?:[_-]?string)?|auth[_-]?password|priv[_-]?password|passphrase)["']?\s*[:=]\s*)(?:"(?:\\.|[^"\\])*(?:"|$)|'(?:\\.|[^'\\])*(?:'|$)|[^\s,;}]+)/gi;
+
 /** Default pattern set, in application order. */
 const DEFAULT_PATTERNS = Object.freeze([
     PEM_PRIVATE_KEY,
@@ -156,6 +163,7 @@ const DEFAULT_PATTERNS = Object.freeze([
     BEARER_TOKEN,
     BASIC_AUTH,
     DISCORD_WEBHOOK,
+    SCANNER_SECRET,
     KV_SECRET,
     GENERIC_KV,
     URL_CREDENTIALS,
@@ -177,6 +185,7 @@ const PATTERN_HINTS = new Map([
     [BEARER_TOKEN, 'bearer'],
     [BASIC_AUTH, 'basic'],
     [DISCORD_WEBHOOK, 'discord'],
+    [SCANNER_SECRET, 'community|auth[_-]?password|priv[_-]?password|passphrase'],
     [KV_SECRET, 'key|secret|passw|pwd|token'],
     [GENERIC_KV, 'key|secret|passw|token'],
     [URL_CREDENTIALS, '://'],
@@ -384,7 +393,7 @@ function createRedactor(options) {
             return value;
         }
         try {
-            let text = value;
+            let text = require('./secretScope').redactSecretValues(value, replacement);
             let truncated = false;
             if (text.length > maxStringLength) {
                 text = text.slice(0, maxStringLength);

package/lib/secretScope.js

@@ -0,0 +1,24 @@
+'use strict';
+const { AsyncLocalStorage } = require('node:async_hooks');
+const scope = new AsyncLocalStorage();
+
+function withSecretValues(values, callback) {
+    if (!Array.isArray(values) || values.some(v => typeof v !== 'string' || !v)) {
+        throw new TypeError('Secret values must be nonempty strings');
+    }
+    const secrets = [...new Set([...(scope.getStore() || []), ...values])];
+    if (secrets.length > 128 || secrets.some(v => v.length > 65536)) {
+        throw new RangeError('Secret scope exceeds 128 values or 65536 characters per value');
+    }
+    return scope.run(secrets, callback);
+}
+function redactSecretValues(text, replacement) {
+    const secrets = scope.getStore();
+    if (!secrets?.length) return text;
+    const variants = [...new Set(secrets.flatMap(value => [value, JSON.stringify(value).slice(1, -1)]))]
+        .sort((a, b) => b.length - a.length);
+    // A single pass avoids redacting the replacement itself or missing overlaps.
+    const pattern = new RegExp([replacement, ...variants].map(value => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('|'), 'g');
+    return text.replace(pattern, () => replacement);
+}
+module.exports = { withSecretValues, redactSecretValues, hasSecretValues: () => Boolean(scope.getStore()?.length) };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ntlogger",
-  "version": "3.0.0",
-  "description": "A Custom Ready-To-Go Logging Wrapper Built on Winston",
+  "version": "4.0.0",
+  "description": "Structured logging with Winston and Pino backends",
   "keywords": [
     "custom logger",
     "discord compatible",
@@ -38,7 +38,13 @@
       "types": "./pino.d.ts",
       "default": "./pino.js"
     },
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./eslint": {
+      "types": "./eslint.d.ts",
+      "default": "./eslint.js"
+    },
+    "./contract/redaction.json": "./contract/redaction.json",
+    "./contract/conformance.json": "./contract/conformance.json"
   },
   "types": "./index.d.ts",
   "files": [
@@ -48,31 +54,37 @@
     "pino.d.ts",
     "lib/*.js",
     "plugins/**/*",
-    "transports/"
+    "transports/",
+    "eslint.js",
+    "eslint.d.ts",
+    "eslint-rules/",
+    "contract/"
   ],
   "scripts": {
     "test": "jest",
     "test:coverage": "jest --runInBand --coverage",
-    "test:unit": "jest --runInBand --testPathIgnorePatterns=tests/plugins/mysql.test.js tests/plugins/postgres.test.js"
-  },
-  "dependencies": {
-    "winston": "^3.19.0",
-    "winston-transport": "^4.9.0"
+    "test:unit": "jest --runInBand --testPathIgnorePatterns=tests/plugins/mysql.test.js tests/plugins/postgres.test.js",
+    "test:package": "node scripts/test-package.cjs",
+    "test:python": "python3 -W error -m unittest discover -s python/tests",
+    "test:contract": "node scripts/sync-python-contract.cjs --check"
   },
   "optionalDependencies": {
     "split2": "^4.2.0"
   },
   "peerDependencies": {
-    "pino": ">=8.0.0",
-    "@sentry/node": "^10.74.0",
-    "mysql2": "^3.24.4",
-    "pg": "^8.23.0",
     "@opentelemetry/api": ">=1.9.0",
     "@opentelemetry/api-logs": "^0.222.0",
-    "@opentelemetry/sdk-logs": "^0.222.0",
     "@opentelemetry/exporter-logs-otlp-http": "^0.222.0",
     "@opentelemetry/resources": "^2.11.0",
-    "@opentelemetry/semantic-conventions": ">=1.20.0"
+    "@opentelemetry/sdk-logs": "^0.222.0",
+    "@opentelemetry/semantic-conventions": ">=1.20.0",
+    "@sentry/node": "^10.74.0",
+    "mysql2": "^3.24.4",
+    "pg": "^8.23.0",
+    "pino": ">=9.14.0",
+    "winston": "^3.19.0",
+    "winston-transport": "^4.9.0",
+    "eslint": ">=9.0.0"
   },
   "peerDependenciesMeta": {
     "pino": {
@@ -104,21 +116,36 @@
     },
     "@opentelemetry/semantic-conventions": {
       "optional": true
+    },
+    "winston": {
+      "optional": true
+    },
+    "winston-transport": {
+      "optional": true
+    },
+    "eslint": {
+      "optional": true
     }
   },
   "devDependencies": {
+    "@opentelemetry/context-async-hooks": "^2.11.0",
+    "@opentelemetry/exporter-logs-otlp-http": "^0.222.0",
+    "@opentelemetry/sdk-logs": "^0.222.0",
     "@sentry/node": "^10.74.0",
     "@sentry/profiling-node": "^10.74.0",
-    "mysql2": "^3.24.4",
-    "pg": "^8.23.0",
     "@testcontainers/mysql": "^12.1.0",
     "@testcontainers/postgresql": "^12.1.0",
     "dotenv": "^17.4.2",
+    "eslint": "^10.10.0",
+    "fastify": "^5.12.4",
     "jest": "^30.5.1",
-    "testcontainers": "^12.1.0",
+    "mysql2": "^3.24.4",
+    "pg": "^8.23.0",
     "pino": "^10.3.1",
-    "@opentelemetry/sdk-logs": "^0.222.0",
-    "@opentelemetry/exporter-logs-otlp-http": "^0.222.0"
+    "testcontainers": "^12.1.0",
+    "typescript": "^5.9.3",
+    "winston": "^3.19.0",
+    "winston-transport": "^4.9.0"
   },
   "engines": {
     "node": ">=22.22.2"

package/pino.d.ts

@@ -17,6 +17,7 @@ import type {
     ChildLoggerOptions,
     DestinationStream,
     Logger as PinoLogger,
+    LoggerOptions,
 } from 'pino';
 
 /**
@@ -126,6 +127,9 @@ declare namespace ntlPinoTransport {
 
     /** Snapshot returned by `logger.getStats()`. Members are `null` when unconfigured. */
     export interface NtlPinoStats {
+        levels: Record<NtlLevel, number>;
+        hookErrors: number;
+        onLog: { pending: number; dropped: number; limit: number };
         sampling: SamplingStats | null;
         deduplication: DeduplicationStats | null;
     }
@@ -175,6 +179,12 @@ declare namespace ntlPinoTransport {
 
     /** Options for `createLogger()`. */
     export interface CreateLoggerOptions {
+        /** Receives a detached redacted record; async work is drained by close(). */
+        /** Maximum in-flight callback promises; overflow drops newest callback, not the primary log. */
+        onLogMaxPending?: number;
+        onLog?: (record: Record<string, any>) => void | Promise<void>;
+        /** Use the application's OTel provider; never registers or shuts down a provider. */
+        otel?: boolean | { loggerProvider?: { getLogger(name: string): { emit(record: any): void }; forceFlush?(): Promise<void> }; name?: string };
         /** Pino level. Defaults to `LOG_LEVEL`, else `debug` in dev / `info` in production. */
         level?: string;
         /** Module label added to every line and used as the transport's default label. */
@@ -214,13 +224,13 @@ declare namespace ntlPinoTransport {
      * properties, so children inherit them through the prototype chain.
      */
     export interface NtlPinoExtras {
-        /** Sampling and deduplication counters. */
+        /** Emitted level counts, callback/export hook errors, sampling and deduplication. */
         getStats(): NtlPinoStats;
-        /** Zero the sampling and deduplication counters. */
+        /** Zero all counters shared by the root and its children. */
         resetStats(): void;
         /**
          * Release sampler/deduplicator timers, then drain the destination.
-         * Calling this on a child tears down state shared with its parent.
+         * Closing a child leaves its parent open. Calls after close throw, even at disabled levels.
          */
         close(timeout?: number): Promise<DrainResult>;
         /** Present only when `processHandlers` was enabled. */
@@ -237,10 +247,24 @@ declare namespace ntlPinoTransport {
     export type NtlPinoLogger = NtlPinoExtras & PinoLogger;
 
     /** Create a pre-configured Pino logger that follows NightTimeLogger conventions. */
+    export function withSecretValues<T>(values: string[], callback: () => T): T;
+
     export function createLogger(opts?: CreateLoggerOptions): NtlPinoLogger;
 
+    /** Framework-owned JSON logger options; no ntlogger lifecycle or timers. */
+    export type CreatePinoOptions = Pick<CreateLoggerOptions,
+        'level' | 'module' | 'service' | 'context' | 'contextProvider' | 'contextKeys' | 'redact' | 'silent' | 'onLog' | 'onLogMaxPending' | 'otel'
+    > & { serializers?: LoggerOptions['serializers'] };
+    export function createPinoOptions(opts?: CreatePinoOptions): LoggerOptions;
+
+    /** Synchronous capture of serialized, redacted records; explicitly silent loggers capture nothing. */
+    export function createTestLogger(opts?: Omit<CreateLoggerOptions, 'destination' | 'processHandlers'>): {
+        logger: NtlPinoLogger;
+        records: Array<Record<string, any>>;
+    };
+
     /**
-     * Resolve silent mode: `opts.silent` -> `NTLOGGER_SILENT` -> `NODE_ENV === 'test'`.
+     * Resolve silent mode: `opts.silent` -> `NTLOGGER_SILENT` -> `NODE_ENV === 'test'` or nonempty `NODE_TEST_CONTEXT`.
      */
     export function isSilent(opts?: { silent?: boolean }): boolean;