ntlogger 2.9.1 → 3.0.0

package/plugins/otel.js

@@ -0,0 +1,263 @@
+/**
+ * @file /plugins/otel.js
+ * @description Sends logs to an OpenTelemetry collector via the OTLP Logs SDK.
+ *
+ * OpenTelemetry packages are optional peer dependencies. Install them when using this plugin:
+ *   npm install @opentelemetry/api @opentelemetry/api-logs @opentelemetry/sdk-logs \
+ *               @opentelemetry/exporter-logs-otlp-http @opentelemetry/resources \
+ *               @opentelemetry/semantic-conventions
+ *
+ * For gRPC or protobuf transport, install the corresponding exporter package and
+ * pass it via the `exporter` option.
+ */
+
+const Transport = require('winston-transport');
+const levels = require('../lib/levels');
+
+const ANSI_REGEX = /\[[0-9;]*m/g;
+
+function stripAnsi(str) {
+    if (typeof str !== 'string') return str;
+    return str.replace(ANSI_REGEX, '');
+}
+
+/**
+ * Map ntlogger levels to OpenTelemetry SeverityNumber values.
+ * See: https://opentelemetry.io/docs/specs/otel/logs/data-model/#field-severitynumber
+ */
+const SEVERITY_NUMBER = {
+    internal: 1,  // TRACE
+    trace:    1,  // TRACE
+    debug:    5,  // DEBUG
+    info:     9,  // INFO
+    warn:     13, // WARN
+    error:    17, // ERROR
+    fatal:    21, // FATAL
+};
+
+const SEVERITY_TEXT = {
+    internal: 'TRACE',
+    trace:    'TRACE',
+    debug:    'DEBUG',
+    info:     'INFO',
+    warn:     'WARN',
+    error:    'ERROR',
+    fatal:    'FATAL',
+};
+
+/**
+ * Lazily require an OTel package, returning null if it's not installed.
+ * Lets the plugin loader skip OTel gracefully when deps are missing.
+ */
+function tryRequire(name) {
+    try {
+        return require(name);
+    } catch (err) {
+        if (err && err.code === 'MODULE_NOT_FOUND') return null;
+        throw err;
+    }
+}
+
+class OpenTelemetryTransport extends Transport {
+    constructor(opts = {}) {
+        super(opts);
+
+        this.name = 'OpenTelemetry Transport for NTLogger';
+
+        // Level threshold (default: log everything down to 'trace')
+        this.level = opts.level || 'trace';
+        if (!(this.level in levels)) {
+            throw new Error(`Invalid log level: ${this.level}`);
+        }
+        this.levelPriority = levels[this.level];
+
+        this.includeTraceContext = opts.includeTraceContext !== false;
+        this.stripAnsi = opts.stripAnsi !== false;
+
+        // Caller-supplied LoggerProvider takes precedence and lets the plugin
+        // run without the OTel SDK packages installed (useful for tests).
+        if (opts.loggerProvider) {
+            this.loggerProvider = opts.loggerProvider;
+            this._ownsProvider = false;
+        } else {
+            const sdkLogs = tryRequire('@opentelemetry/sdk-logs');
+            if (!sdkLogs) {
+                throw new Error(
+                    'OpenTelemetry plugin requires @opentelemetry/sdk-logs (and an exporter) ' +
+                    'when no `loggerProvider` is supplied. ' +
+                    'Install with: npm install @opentelemetry/sdk-logs @opentelemetry/api-logs @opentelemetry/exporter-logs-otlp-http'
+                );
+            }
+            this.loggerProvider = this._buildLoggerProvider(opts, sdkLogs);
+            this._ownsProvider = true;
+        }
+
+        const instrumentationName = opts.instrumentationName || 'ntlogger';
+        const instrumentationVersion = opts.instrumentationVersion || undefined;
+        this.otelLogger = this.loggerProvider.getLogger(instrumentationName, instrumentationVersion);
+
+        // Optional @opentelemetry/api for trace context correlation
+        if (this.includeTraceContext) {
+            const api = tryRequire('@opentelemetry/api');
+            this._traceApi = api && api.trace ? api.trace : null;
+        }
+    }
+
+    /**
+     * Build a LoggerProvider from configuration when one isn't supplied.
+     */
+    _buildLoggerProvider(opts, sdkLogs) {
+        const { LoggerProvider, BatchLogRecordProcessor, SimpleLogRecordProcessor } = sdkLogs;
+
+        let exporter = opts.exporter;
+        if (!exporter) {
+            const otlpHttp = tryRequire('@opentelemetry/exporter-logs-otlp-http');
+            if (!otlpHttp) {
+                throw new Error(
+                    'OpenTelemetry plugin requires either an `exporter` instance or ' +
+                    '@opentelemetry/exporter-logs-otlp-http installed. ' +
+                    'Install with: npm install @opentelemetry/exporter-logs-otlp-http'
+                );
+            }
+            exporter = new otlpHttp.OTLPLogExporter({
+                url: opts.url,
+                headers: opts.headers,
+                concurrencyLimit: opts.concurrencyLimit,
+                timeoutMillis: opts.timeoutMillis,
+            });
+        }
+
+        const Processor = opts.useSimpleProcessor ? SimpleLogRecordProcessor : BatchLogRecordProcessor;
+        const processor = new Processor({ ...(opts.processorOptions || {}), exporter });
+
+        let resource;
+        const resources = tryRequire('@opentelemetry/resources');
+        if (resources && (opts.resource || opts.resourceAttributes || opts.serviceName)) {
+            if (opts.resource) {
+                resource = opts.resource;
+            } else {
+                const attrs = { ...(opts.resourceAttributes || {}) };
+                if (opts.serviceName) {
+                    const semconv = tryRequire('@opentelemetry/semantic-conventions');
+                    const key = (semconv && semconv.ATTR_SERVICE_NAME) || 'service.name';
+                    attrs[key] = opts.serviceName;
+                    if (opts.serviceVersion) {
+                        const vkey = (semconv && semconv.ATTR_SERVICE_VERSION) || 'service.version';
+                        attrs[vkey] = opts.serviceVersion;
+                    }
+                }
+                resource = resources.resourceFromAttributes
+                    ? resources.resourceFromAttributes(attrs)
+                    : new resources.Resource(attrs);
+            }
+        }
+
+        return new LoggerProvider({
+            resource,
+            processors: [processor],
+        });
+    }
+
+    /**
+     * Flatten metadata into OTel-compatible primitive/array attributes.
+     * Objects are JSON-stringified since OTel attributes can't be nested.
+     */
+    _toAttributes(meta) {
+        const attrs = {};
+        for (const [key, value] of Object.entries(meta)) {
+            if (value === null || value === undefined) continue;
+            if (key === 'timestamp' || key === 'timeCreated') continue;
+
+            const t = typeof value;
+            if (t === 'string') {
+                attrs[key] = this.stripAnsi ? stripAnsi(value) : value;
+            } else if (t === 'number' || t === 'boolean') {
+                attrs[key] = value;
+            } else if (Array.isArray(value)) {
+                attrs[key] = value.map(v =>
+                    typeof v === 'object' && v !== null ? JSON.stringify(v) : v
+                );
+            } else if (t === 'object') {
+                try {
+                    attrs[key] = JSON.stringify(value);
+                } catch {
+                    attrs[key] = String(value);
+                }
+            } else {
+                attrs[key] = String(value);
+            }
+        }
+        return attrs;
+    }
+
+    log(info, callback) {
+        setImmediate(() => {
+            this.emit('logged', info);
+        });
+
+        const { level, message, ...meta } = info;
+
+        if (levels[level] === undefined || levels[level] > this.levelPriority) {
+            callback();
+            return;
+        }
+
+        const severityNumber = SEVERITY_NUMBER[level] ?? SEVERITY_NUMBER.info;
+        const severityText = SEVERITY_TEXT[level] || String(level).toUpperCase();
+        const body = this.stripAnsi && typeof message === 'string' ? stripAnsi(message) : message;
+
+        const record = {
+            severityNumber,
+            severityText,
+            body,
+            attributes: this._toAttributes(meta),
+            ...(meta.timestamp ? { timestamp: new Date(meta.timestamp) } : {}),
+        };
+
+        if (this._traceApi) {
+            const span = this._traceApi.getActiveSpan();
+            const ctx = span && span.spanContext && span.spanContext();
+            if (ctx && ctx.traceId && ctx.spanId) {
+                record.traceId = ctx.traceId;
+                record.spanId = ctx.spanId;
+                if (typeof ctx.traceFlags === 'number') {
+                    record.traceFlags = ctx.traceFlags;
+                }
+            }
+        }
+
+        try {
+            this.otelLogger.emit(record);
+        } catch (err) {
+            callback(err);
+            return;
+        }
+
+        callback();
+    }
+
+    /**
+     * Force-flush pending log records.
+     */
+    flush() {
+        if (this.loggerProvider && typeof this.loggerProvider.forceFlush === 'function') {
+            return this.loggerProvider.forceFlush();
+        }
+        return Promise.resolve();
+    }
+
+    /**
+     * Shut down the LoggerProvider (only if this transport created it).
+     */
+    async close() {
+        if (this._ownsProvider && this.loggerProvider && typeof this.loggerProvider.shutdown === 'function') {
+            await this.loggerProvider.shutdown();
+        }
+    }
+}
+
+module.exports = {
+    transport: OpenTelemetryTransport,
+    SEVERITY_NUMBER,
+    SEVERITY_TEXT,
+};

package/plugins/postgres.js

@@ -1,14 +1,36 @@
 /**
  * @file /plugins/postgres.js
  * @description Stores logs in PostgresSQL database.
+ *
+ * `pg` is an optional peer dependency. Install it when using this plugin:
+ *   npm install pg
  */
 
 const Transport = require('winston-transport');
-const { Pool } = require('pg');
 const levels = require('../lib/levels');
 
-let connectionPool = null;
-let tableInitialized = false;
+/**
+ * Requires an optional peer dependency, translating only that package's
+ * MODULE_NOT_FOUND into an actionable install message. Any other failure
+ * (including a missing module *inside* the package) propagates unchanged.
+ * @param {string} moduleId - The module specifier to require.
+ * @param {string} packageName - The npm package to install.
+ * @returns {*} The resolved module.
+ */
+function requirePeer(moduleId, packageName) {
+    try {
+        return require(moduleId);
+    } catch (err) {
+        if (err && err.code === 'MODULE_NOT_FOUND' && String(err.message).includes(`'${moduleId}'`)) {
+            throw new Error(`ntlogger Postgres plugin requires '${packageName}'. Install it with: npm install ${packageName}`);
+        }
+        throw err;
+    }
+}
+
+const { Pool } = requirePeer('pg', 'pg');
+
+
 
 class PostgreSQLTransport extends Transport {
     constructor(opts = {}) {
@@ -17,6 +39,11 @@ class PostgreSQLTransport extends Transport {
         this.name = 'PostgreSQL Transport for NTLogger';
         this.database = opts.database || 'test';
         this.table = opts.table || 'logs';
+        if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(this.table)) {
+            throw new Error('Log table must be a simple SQL identifier');
+        }
+        this.tableInitialized = false;
+        this.closed = false;
 
         this.logLevel = opts.level ? levels[opts.level] : levels.info;
 
@@ -26,58 +53,44 @@ class PostgreSQLTransport extends Transport {
             user: opts.user || 'postgres',
             password: opts.password || '',
             database: this.database,
+            ssl: opts.ssl,
             max: opts.connectionLimit || 10,
             idleTimeoutMillis: opts.idleTimeout || 60000,
             connectionTimeoutMillis: opts.connectionTimeout || 2000,
         };
 
-        this.init();
+        this.pool = new Pool(this.poolConfig);
+        this.pool.on('error', error => { this.lastError = error; });
+        this.ready = this.checkLogTable();
+        this.ready.catch(error => { this.lastError = error; });
     }
 
-    async init() {
-        try {
-            if (!connectionPool) {
-                connectionPool = new Pool(this.poolConfig);
-            }
-            this.pool = connectionPool;
-            await this.checkLogTable();
-        } catch (err) {
-            console.error(`Failed to initialize ${this.name}:`, err);
-        }
-    }
+    async init() { return this.ready; }
 
     async log(info, callback) {
-        setImmediate(() => {
-            this.emit('logged', info);
-        });
-
-        if (!tableInitialized) {
-            await this.checkLogTable();
-        }
-
-        const { level, message, ...meta } = info;
-
-        if (levels[level] > this.logLevel) {
-            callback();
-            return;
-        }
-
-        const metaString = JSON.stringify(meta);
-        const timestamp = this.formatTimestamp(meta.timeCreated);
-
+        if (levels[info.level] > this.logLevel) { callback(); return; }
         try {
+            if (this.closed) throw new Error('Database transport is closed');
+            await this.ready;
+            const { level, message, ...meta } = info;
+            const timestamp = this.formatTimestamp(meta.timestamp);
             await this.pool.query(
                 `INSERT INTO ${this.table} (level, message, meta, timestamp) VALUES ($1, $2, $3, $4)`,
-                [level, message, metaString, timestamp]
+                [level, message, JSON.stringify(meta), timestamp]
             );
-        } catch (err) {
-            console.error(`Failed to log message to ${this.name}:`, err);
+            this.emit('logged', info);
+            callback();
+        } catch (error) {
+            this.lastError = error;
+            callback(error);
         }
-
-        callback();
     }
 
     formatTimestamp(timeCreated) {
+        if (timeCreated && /^\d{4}-/.test(timeCreated)) {
+            const date = new Date(timeCreated);
+            return date.toISOString();
+        }
         if (!timeCreated) {
             return new Date().toISOString().slice(0, 19).replace('T', ' ');
         }
@@ -96,43 +109,32 @@ class PostgreSQLTransport extends Transport {
         return `${date.getFullYear()}-${(date.getMonth() + 1).toString().padStart(2, '0')}-${date.getDate().toString().padStart(2, '0')} ${hours}:${minutes}:${seconds}`;
     }
 
-    async checkLogTable() {
-        if (tableInitialized) return;
-
-        try {
-            const result = await this.pool.query(
-                `SELECT to_regclass('${this.table}') as tablename`
-            );
-
-            if (!result.rows[0].tablename) {
-                await this.pool.query(
-                    `CREATE TABLE IF NOT EXISTS ${this.table} (
-                        id SERIAL PRIMARY KEY,
-                        level VARCHAR(255) NOT NULL,
-                        message TEXT NOT NULL,
-                        meta JSONB,
-                        timestamp TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP
-                    )`
-                );
-            }
-
-            tableInitialized = true;
-        } catch (err) {
-            console.error(`Failed to check or create table ${this.table}:`, err);
+    checkLogTable() {
+        if (!this.tableReady) {
+            this.tableReady = this.pool.query(`CREATE TABLE IF NOT EXISTS ${this.table} (id SERIAL PRIMARY KEY, level VARCHAR(255) NOT NULL, message TEXT NOT NULL, meta JSONB, timestamp TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP)`)
+                .then(() => { this.tableInitialized = true; })
+                .catch(error => { this.tableReady = null; throw error; });
         }
+        return this.tableReady;
     }
 
     isActive() {
-        return this.pool && !this.pool.ended;
+        return this.pool && !this.closed;
+    }
+
+    async flush() {
+        await this.ready;
+        if (this.lastError) throw this.lastError;
     }
 
-    async close() {
-        if (connectionPool) {
-            await connectionPool.end();
-            connectionPool = null;
-            console.log('Closed PostgreSQL connection pool.');
+    close() {
+        if (!this.closePromise) {
+            this.closed = true;
+            this.closePromise = this.ready.catch(() => {}).then(() => this.pool.end());
         }
+        return this.closePromise;
     }
+
 }
 
 module.exports = {

package/plugins/sentry.js

@@ -1,10 +1,33 @@
 /**
  * @file /plugins/sentry.js
  * @description Initializes the Sentry SDK for error tracking and defines a custom Winston transport.
+ *
+ * `@sentry/node` is an optional peer dependency. Install it when using this plugin:
+ *   npm install @sentry/node
  */
 
 const Transport = require('winston-transport');
-const Sentry = require("@sentry/node");
+
+/**
+ * Requires an optional peer dependency, translating only that package's
+ * MODULE_NOT_FOUND into an actionable install message. Any other failure
+ * (including a missing module *inside* the package) propagates unchanged.
+ * @param {string} moduleId - The module specifier to require.
+ * @param {string} packageName - The npm package to install.
+ * @returns {*} The resolved module.
+ */
+function requirePeer(moduleId, packageName) {
+    try {
+        return require(moduleId);
+    } catch (err) {
+        if (err && err.code === 'MODULE_NOT_FOUND' && String(err.message).includes(`'${moduleId}'`)) {
+            throw new Error(`ntlogger Sentry plugin requires '${packageName}'. Install it with: npm install ${packageName}`);
+        }
+        throw err;
+    }
+}
+
+const Sentry = requirePeer('@sentry/node', '@sentry/node');
 
 /**
  * Custom Winston transport for sending logs to Sentry.
@@ -14,6 +37,7 @@ class SentryTransport extends Transport {
         super(opts);
 
         this.name = 'Sentry Transport for NTLogger';
+        this.flushTimeout = opts.flushTimeout ?? 5000;
         this.init(opts);
     }
 
@@ -37,13 +61,22 @@ class SentryTransport extends Transport {
         const { level, message, ...meta } = info;
 
         if (level === 'error') {
-            Sentry.captureException(new Error(message), { extra: meta });
+            const error = new Error(message);
+            if (meta.stack) error.stack = meta.stack;
+            Sentry.captureException(error, { extra: meta });
         } else {
-            Sentry.captureMessage(message, { level, extra: meta });
+            Sentry.captureMessage(message, { level: ({ warn: 'warning', trace: 'debug', internal: 'debug' })[level] || level, extra: meta });
         }
 
         callback();
     }
+    async flush() {
+        if (!await Sentry.flush(this.flushTimeout)) throw new Error('Sentry flush timed out');
+    }
+
+    // Flush without disabling the SDK shared with the host application.
+    close() { return this.flush(); }
+
 }
 
 module.exports = {

package/plugins/syslog.js

@@ -16,12 +16,12 @@ class SyslogTransport extends Transport {
             port: opts.port || 514,
             protocol: opts.protocol || 'UDP', // Options: 'UDP', 'TCP', 'TLS'
             rfc: opts.rfc || 'RFC-5424', // Options: 'RFC-3164', 'RFC-5424'
-            facility: opts.facility || 1,
+            facility: opts.facility ?? 1,
             appName: opts.appName || 'NTLogger',
             hostname: opts.hostname || require('os').hostname(),
         });
 
-        this.levels = {
+        this.severities = {
             internal: 7, // Debug level for internal logs
             trace: 7,    // Debug
             debug: 7,    // Debug
@@ -30,7 +30,7 @@ class SyslogTransport extends Transport {
             error: 3,    // Error
             fatal: 2,    // Critical
         };
-        this.logLevel = opts.level ? this.levels[opts.level] : this.levels.info;
+        this.logLevel = opts.level ? this.severities[opts.level] : this.severities.info;
 
         if (this.client.protocol === 'TCP' || this.client.protocol === 'TLS') {
             this.client.connect().catch(err => {
@@ -51,14 +51,12 @@ class SyslogTransport extends Transport {
 
         const { level, message, ...meta } = info;
 
-        if (this.levels[level] > this.logLevel) {
+        if (this.severities[level] > this.logLevel) {
             callback();
             return;
         }
 
-        this.client.send(this.levels[level], message, meta);
-
-        callback();
+        this.client.send(this.severities[level], message, meta, callback);
     }
 
     /**
@@ -74,8 +72,7 @@ class SyslogTransport extends Transport {
      * @returns {Promise<void>}
      */
     async close() {
-        this.client.close();
-        console.log('Closed Syslog client connection.');
+        await this.client.close();
     }
 }