ntlogger 2.10.0 → 4.0.0

package/plugins/README.md

@@ -2,6 +2,36 @@
 
 NightTimeLogger is a powerful and flexible logging utility with various plugins to extend its functionality. This README provides an overview of the available plugins and instructions on how to set them up.
 
+## Required Plugin Entry Fields
+
+Every entry in the `plugins` array **must** supply all three of the following. The
+loader silently skips a plugin whose `enabled` is missing/falsy, and reports and skips
+a plugin whose `config` is missing or is not an object:
+
+| Field | Required | Notes |
+| --- | --- | --- |
+| `name` | yes | Must be one of `Sentry`, `MySQL`, `Postgres`, `Jest`, `Syslog`, `Discord`, `Teams`, `OpenObserve`, `OpenTelemetry`. Unknown names are reported and skipped. |
+| `enabled` | yes | Must be `true`. A plugin with `enabled: false` (or omitted) is skipped. |
+| `config` | yes | Must be an object, even if empty (`config: {}`). |
+
+## Optional Peer Dependencies
+
+The heavier plugin backends are **optional peer dependencies**: installing `ntlogger`
+does not pull them in, so projects that do not use those plugins stay lean. Install the
+peer for each plugin you actually enable:
+
+| Plugin | Install |
+| --- | --- |
+| Sentry | `npm install @sentry/node` |
+| MySQL | `npm install mysql2` |
+| Postgres | `npm install pg` |
+| OpenTelemetry | `npm install @opentelemetry/api @opentelemetry/api-logs @opentelemetry/sdk-logs @opentelemetry/exporter-logs-otlp-http @opentelemetry/resources @opentelemetry/semantic-conventions` |
+| Discord, Teams, OpenObserve, Syslog, Jest | none - no extra packages required |
+
+If the peer is missing, the plugin loader reports an actionable error naming the
+package and the install command, then skips that plugin. Every other plugin in the
+same configuration still loads and the logger keeps working.
+
 ## Available Plugins
 
 ### 1. Discord
@@ -9,10 +39,13 @@ NightTimeLogger is a powerful and flexible logging utility with various plugins
 
 ![Discord Plugin Output](https://github.com/NightSquawk/NightTimeLogger/blob/main/images/plugins/discord/pluginDiscordOutput.png)
 
+**Peer dependency:** none.
+
 **Setup:**
 ```javascript
 {
     name: 'Discord',
+    enabled: true,
     config: {
         webhookUrl: process.env.DISCORD_WEBHOOK_URL
         avatarUrl: process.env.DISCORD_AVATAR_URL || 'https://pbs.twimg.com/profile_images/997535493624508416/V7Ed1k2o_400x400.jpg',
@@ -26,11 +59,15 @@ NightTimeLogger is a powerful and flexible logging utility with various plugins
 ### 2. Sentry
 Description: Initializes the Sentry SDK for error tracking and defines a custom Winston transport for capturing and sending error logs to Sentry.
 
+**Peer dependency:** `npm install @sentry/node` (plus `@sentry/profiling-node` if you use
+`nodeProfilingIntegration()`).
+
 Setup:
 
 ``` javascript
 {
     name: 'Sentry',
+    enabled: true,
     config: {
         dsn: process.env.SENTRY_DSN || null,
         release: process.env.SENTRY_RELEASE || null,
@@ -54,11 +91,14 @@ Setup:
 ### 3. MySQL
 Description: Stores logs in a MySQL database, allowing you to persist log messages and analyze them using SQL queries.
 
+**Peer dependency:** `npm install mysql2`.
+
 Setup:
 
 ``` javascript
 {
     name: 'MySQL',
+    enabled: true,
     config: {
         host: process.env.MYSQL_DB_HOST || 'localhost',
         port: process.env.MYSQL_DB_PORT || 3306,
@@ -73,11 +113,16 @@ Setup:
 ### 4. Jest
 Description: Stores log messages in memory for testing purposes, particularly useful when running tests with Jest.
 
-Setup:
+**Peer dependency:** none.
+
+Setup (`enabled` and an object `config` are both required, even though the Jest
+transport takes no options):
 
 ``` javascript
 {
     name: 'Jest',
+    enabled: true,
+    config: {},
 }
 ```
 
@@ -87,11 +132,14 @@ Description: Sends logs to a Syslog server using a custom Syslog client. This al
 ![Syslog Plugin Output](https://github.com/NightSquawk/NightTimeLogger/blob/main/images/plugins/syslog/pluginSyslogOutput.png)
 
 
+**Peer dependency:** none.
+
 Setup:
 
 ``` javascript
 {
     name: 'Syslog',
+    enabled: true,
     config: {
         host: process.env.SYSLOG_HOST || 'localhost',
         port: process.env.SYSLOG_PORT || 514,
@@ -111,11 +159,14 @@ Setup:
 ![Teams Mixed Object Plugin Output](https://github.com/NightSquawk/NightTimeLogger/blob/main/images/plugins/teams/pluginTeamsMixedOutput.png)
 
 
+**Peer dependency:** none.
+
 **Setup:**
 
 ``` javascript
 {
     name: 'Teams',
+    enabled: true,
         config: {
         webhookUrl: process.env.TEAMS_WEBHOOK_URL || "im not leaking my webhook url again",
             level: process.env.LOG_LEVEL || "info",
@@ -236,11 +287,14 @@ log.error('Error message',[
 ### 7. OpenObserve
 **Description:** Sends logs to OpenObserve, an open-source observability platform. This plugin automatically strips ANSI escape codes, removes timestamps, and sends clean structured JSON logs to OpenObserve's HTTP API with batching support for improved performance.
 
+**Peer dependency:** none.
+
 **Setup:**
 
 ```javascript
 {
     name: 'OpenObserve',
+    enabled: true,
     config: {
         host: process.env.OPENOBSERVE_HOST || 'http://localhost:5080',
         organization: process.env.OPENOBSERVE_ORGANIZATION || 'default',
@@ -261,6 +315,60 @@ log.error('Error message',[
 - Clean structured JSON output suitable for OpenObserve ingestion
 - Support for all log levels with configurable filtering
 
+### 8. OpenTelemetry
+**Description:** Sends logs to an OpenTelemetry collector as OTLP log records. Maps ntlogger levels to OTel `SeverityNumber`/`SeverityText`, strips ANSI colour codes, flattens metadata into OTel attributes (nested objects are JSON-stringified), and automatically attaches `trace_id`/`span_id` from the active span when `@opentelemetry/api` is installed.
+
+**Peer dependency:** the OpenTelemetry packages are optional peers:
+
+```bash
+npm install @opentelemetry/api @opentelemetry/api-logs @opentelemetry/sdk-logs \
+            @opentelemetry/exporter-logs-otlp-http @opentelemetry/resources \
+            @opentelemetry/semantic-conventions
+```
+
+If your application already builds its own OTel pipeline, pass an existing
+`loggerProvider` and none of the SDK packages are required by this plugin.
+
+**Setup:**
+
+```javascript
+{
+    name: 'OpenTelemetry',
+    enabled: true,
+    config: {
+        // --- Collector endpoint (used when no `exporter`/`loggerProvider` is given) ---
+        url: process.env.OTEL_EXPORTER_OTLP_LOGS_ENDPOINT || 'http://localhost:4318/v1/logs',
+        headers: { 'x-api-key': process.env.OTEL_API_KEY },
+        concurrencyLimit: 10,        // Optional: max in-flight export requests
+        timeoutMillis: 10000,        // Optional: export request timeout
+
+        // --- Resource attributes ---
+        serviceName: 'my-service',   // Optional: sets service.name
+        serviceVersion: '1.2.3',     // Optional: sets service.version
+        resourceAttributes: { 'deployment.environment': process.env.NODE_ENV },
+        // resource: myResource,     // Optional: a pre-built OTel Resource (wins over the above)
+
+        // --- Pipeline ---
+        // exporter: myExporter,         // Optional: bring your own exporter (gRPC/protobuf/etc.)
+        // loggerProvider: myProvider,   // Optional: reuse an existing LoggerProvider
+        useSimpleProcessor: false,       // Optional: SimpleLogRecordProcessor instead of Batch
+        processorOptions: {},            // Optional: passed to the processor constructor
+
+        // --- Behaviour ---
+        level: 'trace',              // Optional: minimum level to export (default: 'trace')
+        includeTraceContext: true,   // Optional: attach trace_id/span_id (default: true)
+        stripAnsi: true,             // Optional: strip ANSI codes (default: true)
+        instrumentationName: 'ntlogger',  // Optional: OTel instrumentation scope name
+        instrumentationVersion: '3.0.0', // Optional: OTel instrumentation scope version
+    },
+}
+```
+
+**Notes:**
+- `level` uses ntlogger priorities (`fatal` 0 -> `internal` 6). The default `'trace'` exports everything except `internal`; use `'internal'` to export absolutely everything.
+- If neither `loggerProvider` nor `exporter` is supplied and the SDK/exporter packages are not installed, the transport constructor throws a message naming the packages to install - the loader reports it and skips only this plugin.
+- The plugin shuts the provider down on `close()` only when it created the provider itself; a caller-supplied `loggerProvider` is left alone.
+
 ### Example Logger Configuration
 Here is an example configuration for NightTimeLogger using multiple plugins:
 
@@ -272,6 +380,7 @@ let config = {
     plugins: [
         {
             name: 'Discord',
+            enabled: true,
             config: {
                 webhookUrl: process.env.DISCORD_WEBHOOK_URL,
                 avatarUrl: process.env.DISCORD_AVATAR_URL,
@@ -282,6 +391,7 @@ let config = {
         },
         {
             name: 'Sentry',
+            enabled: true,
             config: {
                 dsn: process.env.SENTRY_DSN,
                 release: process.env.SENTRY_RELEASE,
@@ -291,6 +401,7 @@ let config = {
         },
         {
             name: 'MySQL',
+            enabled: true,
             config: {
                 host: process.env.MYSQL_DB_HOST,
                 port: process.env.MYSQL_DB_PORT || 3306,
@@ -302,9 +413,12 @@ let config = {
         },
         {
             name: 'Jest',
+            enabled: true,
+            config: {},
         },
         {
             name: 'Syslog',
+            enabled: true,
             config: {
                 host: process.env.SYSLOG_HOST || 'localhost',
                 port: process.env.SYSLOG_PORT || 514,
@@ -315,6 +429,7 @@ let config = {
         },
         {
             name: 'OpenObserve',
+            enabled: true,
             config: {
                 host: process.env.OPENOBSERVE_HOST || 'http://localhost:5080',
                 organization: process.env.OPENOBSERVE_ORGANIZATION || 'default',
@@ -326,10 +441,23 @@ let config = {
                 level: 'info',
             },
         },
+        {
+            name: 'OpenTelemetry',
+            enabled: true,
+            config: {
+                url: process.env.OTEL_EXPORTER_OTLP_LOGS_ENDPOINT || 'http://localhost:4318/v1/logs',
+                serviceName: 'MyAppLogger',
+                level: 'info',
+            },
+        },
     ],
 };
 ```
 
+Every entry above sets `enabled: true` and an object `config` - both are mandatory.
+Plugins whose peer dependency is not installed (`Sentry`, `MySQL`, `Postgres`,
+`OpenTelemetry`) are reported and skipped without affecting the rest of the list.
+
 ### Conclusion
 The NightTimeLogger is highly customizable and supports various plugins for different logging requirements. By leveraging these plugins, you can easily integrate logging into your existing infrastructure, whether it be storing logs in databases, sending them to monitoring tools like Sentry, or receiving alerts directly in Discord.
 

package/plugins/discord.js

@@ -4,8 +4,7 @@
  */
 
 const Transport = require('winston-transport');
-const https = require('https');
-const { URL } = require('url');
+const { HttpDelivery } = require('./lib/httpDelivery');
 
 const colors = require('../lib/colors');
 const levels = require('../lib/levels');
@@ -17,6 +16,7 @@ class DiscordTransport extends Transport {
         this.name = 'Discord Webhook Transport for NTLogger';
 
         this.webhookUrl = opts.webhookUrl;
+        this.delivery = new HttpDelivery(opts.webhookUrl, opts);
         this.username = opts.username || 'NTLogger';
         this.avatarUrl = opts.avatarUrl || null;
         this.strict = opts.strict || false;
@@ -38,10 +38,6 @@ class DiscordTransport extends Transport {
     }
 
     async log(info, callback) {
-        setImmediate(() => {
-            this.emit('logged', info);
-        });
-
         const { level, message, ...meta } = info;
 
         // Check if the log level matches the configured level (strict mode) or is at or below the configured level
@@ -57,52 +53,38 @@ class DiscordTransport extends Transport {
             }
         }
 
-        const payload = JSON.stringify({
-            username: this.username,
-            avatar_url: this.avatarUrl,
-            embeds: [
-                {
-                    title: `Log Level: ${level.toUpperCase()}`,
-                    description: message,
-                    color: this.levelColors[level] || 0x000000, // Default to black if the level is unknown
-                    fields: Object.keys(meta).map(key => ({
-                        name: key,
-                        value: typeof meta[key] === 'string' ? meta[key] : JSON.stringify(meta[key], null, 2),
-                        inline: false,
-                    })),
-                    timestamp: new Date().toISOString(),
-                }
-            ]
-        });
-
-        const webhookUrl = new URL(this.webhookUrl);
-
-        const options = {
-            hostname: webhookUrl.hostname,
-            path: webhookUrl.pathname + webhookUrl.search,
-            method: 'POST',
-            headers: {
-                'Content-Type': 'application/json',
-                'Content-Length': Buffer.byteLength(payload),
-            },
-        };
-
-        const req = https.request(options, (res) => {
-            res.on('data', (chunk) => {
-                console.log(`Response from Discord: ${chunk}`);
-            });
-            res.on('end', () => {
-                callback();
+        try {
+            const payload = JSON.stringify({
+                username: this.username,
+                avatar_url: this.avatarUrl,
+                embeds: [
+                    {
+                        title: `Log Level: ${level.toUpperCase()}`,
+                        description: message,
+                        color: this.levelColors[level] || 0x000000, // Default to black if the level is unknown
+                        fields: Object.keys(meta).map(key => ({
+                            name: key,
+                            value: typeof meta[key] === 'string' ? meta[key] : JSON.stringify(meta[key], null, 2),
+                            inline: false,
+                        })),
+                        timestamp: new Date().toISOString(),
+                    }
+                ]
             });
-        });
 
-        req.on('error', (e) => {
-            console.error(`Failed to send log to Discord: ${e.message}`);
-        });
+            if (this.closed) throw new Error('HTTP transport is closed');
+            await this.delivery.send(payload);
+            this.emit('logged', info);
+            callback();
+        } catch (error) { callback(error); }
 
-        req.write(payload);
-        req.end();
     }
+    flush() { return this.delivery.flush(); }
+    close() {
+        this.closed = true;
+        return this.delivery.flush();
+    }
+
 }
 
 module.exports = {

package/plugins/index.js

@@ -3,19 +3,28 @@
  * @description Initializes any plugins required by the application.
  */
 
-// Available plugins
+// Available plugins.
+//
+// Each entry is a *thunk*, not a module: the `require()` only runs when the
+// plugin is actually requested by a config entry. Several plugins depend on
+// optional peer dependencies (`@sentry/node`, `mysql2`, `pg`, the
+// OpenTelemetry packages) that consumers are not required to install, so
+// resolving every module at load time would break `require('ntlogger')` for
+// everyone who does not use those backends. Resolution happens inside the
+// per-plugin try/catch in initPlugins(), which means a missing optional
+// dependency disables only that one plugin.
 const plugins = {
-    Sentry      : require('./sentry'),
-    MySQL       : require('./mysql'),
-    Postgres    : require('./postgres'),
-    Jest        : require('./jest'),
-    Syslog      : require('./syslog'),
-    Discord     : require('./discord'),
-    Teams       : require('./teams'),
-    OpenObserve : require('./openobserve'),
-    OpenTelemetry : require('./otel'),
+    Sentry      : () => require('./sentry'),
+    MySQL       : () => require('./mysql'),
+    Postgres    : () => require('./postgres'),
+    Jest        : () => require('./jest'),
+    Syslog      : () => require('./syslog'),
+    Discord     : () => require('./discord'),
+    Teams       : () => require('./teams'),
+    OpenObserve : () => require('./openobserve'),
+    OpenTelemetry : () => require('./otel'),
 
-    // WIP SMSMail : require('./smsMail'),
+    // WIP SMSMail : () => require('./smsMail'),
 };
 
 // ------------------------------ DO NOT MODIFY BELOW THIS LINE ------------------------------ //
@@ -26,9 +35,15 @@ function checkPluginAvailability(pluginName) {
     }
 }
 
+/**
+ * Lazily resolves a plugin module and returns its transport class.
+ * Any error thrown here (including a missing optional peer dependency)
+ * is reported and skipped by the caller rather than crashing the logger.
+ */
 function getPluginTransport(pluginName) {
     checkPluginAvailability(pluginName);
-    return plugins[pluginName].transport;
+    const pluginModule = plugins[pluginName]();
+    return pluginModule && pluginModule.transport;
 }
 
 /**

package/plugins/lib/httpDelivery.js

@@ -0,0 +1,98 @@
+'use strict';
+
+const http = require('http');
+const https = require('https');
+
+class HttpDelivery {
+    constructor(url, opts = {}) {
+        this.url = new URL(url);
+        if (!['http:', 'https:'].includes(this.url.protocol)) throw new Error('Expected an HTTP(S) URL');
+        this.timeout = opts.timeout ?? 5000;
+        this.maxRetries = opts.maxRetries ?? 3;
+        this.retryDelay = opts.retryDelay ?? 1000;
+        this.maxPending = opts.maxPending ?? 100;
+        for (const [name, value] of Object.entries({ timeout: this.timeout, maxPending: this.maxPending })) {
+            if (!Number.isFinite(value) || value <= 0) throw new Error(`Invalid ${name}`);
+        }
+        if (!Number.isInteger(this.maxRetries) || this.maxRetries < 0 || !Number.isFinite(this.retryDelay) || this.retryDelay < 0) {
+            throw new Error('Invalid retry configuration');
+        }
+        this.pending = new Set();
+        this.failure = null;
+    }
+
+    send(payload, headers = {}) {
+        if (this.pending.size >= this.maxPending) {
+            const error = new Error('HTTP delivery queue is full');
+            this.failure = error;
+            return Promise.reject(error);
+        }
+        const operation = this.deliver(payload, headers);
+        this.pending.add(operation);
+        operation.then(() => this.pending.delete(operation), error => {
+            this.failure = error;
+            this.pending.delete(operation);
+        });
+        return operation;
+    }
+
+    async deliver(payload, headers) {
+        for (let attempt = 0; ; attempt++) {
+            try { return await this.request(payload, headers); }
+            catch (error) {
+                if (error.retryable === false || attempt >= this.maxRetries) throw error;
+                const wait = Math.min(error.retryAfter ?? this.retryDelay * 2 ** attempt, this.timeout);
+                await new Promise(resolve => setTimeout(resolve, wait));
+            }
+        }
+    }
+
+    request(payload, headers) {
+        return new Promise((resolve, reject) => {
+            const protocol = this.url.protocol === 'https:' ? https : http;
+            let timer;
+            const req = protocol.request(this.url, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(payload), ...headers },
+            }, res => {
+                let body = '';
+                res.setEncoding('utf8');
+                res.on('data', chunk => {
+                    body += chunk;
+                    if (body.length > 1048576) req.destroy(new Error('HTTP response exceeds 1 MB'));
+                });
+                res.on('aborted', () => req.destroy(new Error('HTTP response aborted')));
+                res.on('error', error => req.destroy(error));
+                res.on('end', () => {
+                    clearTimeout(timer);
+                    if (res.statusCode >= 200 && res.statusCode < 300 && !body.includes('Microsoft Teams endpoint returned HTTP error 429')) {
+                        resolve();
+                    } else {
+                        const error = new Error(`HTTP log delivery failed (${res.statusCode})`);
+                        error.retryable = res.statusCode === 429 || res.statusCode >= 500 || body.includes('HTTP error 429');
+                        const retryAfter = res.headers['retry-after'];
+                        if (retryAfter) {
+                            const ms = Number.isFinite(Number(retryAfter)) ? Number(retryAfter) * 1000 : Date.parse(retryAfter) - Date.now();
+                            if (Number.isFinite(ms)) error.retryAfter = Math.max(0, ms);
+                        }
+                        reject(error);
+                    }
+                });
+            });
+            timer = setTimeout(() => req.destroy(new Error('HTTP log delivery timed out')), this.timeout);
+            req.on('error', error => { clearTimeout(timer); reject(error); });
+            req.end(payload);
+        });
+    }
+
+    async flush() {
+        await Promise.allSettled([...this.pending]);
+        if (this.failure) {
+            const error = this.failure;
+            this.failure = null;
+            throw error;
+        }
+    }
+}
+
+module.exports = { HttpDelivery };

package/plugins/lib/syslogClient.js

@@ -13,7 +13,7 @@ class SyslogClient {
         this.port = opts.port || 514;
         this.protocol = opts.protocol || 'UDP'; // 'UDP', 'TCP', 'TLS'
         this.rfc = opts.rfc || 'RFC-5424'; // 'RFC-3164', 'RFC-5424'
-        this.facility = opts.facility || 1; // Default to user-level messages
+        this.facility = opts.facility ?? 1; // Default to user-level messages
         this.appName = opts.appName || 'NTLogger';
         this.hostname = opts.hostname || require('os').hostname();
         this.transport = null;
@@ -52,12 +52,13 @@ class SyslogClient {
      * @param {string} message - The log message.
      * @param {object} [meta] - Additional metadata for RFC-5424 structured data.
      */
-    send(severity, message, meta = {}) {
+    send(severity, message, meta = {}, callback = () => {}) {
         const formattedMessage = this.formatMessage(severity, message, meta);
         if (this.protocol === 'UDP') {
-            this.transport.send(Buffer.from(formattedMessage), 0, formattedMessage.length, this.port, this.host);
+            const buffer = Buffer.from(formattedMessage);
+            this.transport.send(buffer, 0, buffer.length, this.port, this.host, callback);
         } else {
-            this.transport.write(formattedMessage + '\n');
+            this.transport.write(formattedMessage + '\n', callback);
         }
     }
 
@@ -101,12 +102,21 @@ class SyslogClient {
      * Closes the transport connection.
      */
     close() {
-        if (this.transport && (this.protocol === 'TCP' || this.protocol === 'TLS')) {
-            this.transport.end();
-        } else if (this.protocol === 'UDP') {
-            this.transport.close();
+        if (!this.closePromise) {
+            this.closePromise = new Promise((resolve, reject) => {
+                try {
+                    if (this.protocol === 'UDP') this.transport.close(resolve);
+                    else if (this.transport.destroyed) resolve();
+                    else this.transport.end(resolve);
+                } catch (error) {
+                    if (error.code === 'ERR_SOCKET_DGRAM_NOT_RUNNING') resolve();
+                    else reject(error);
+                }
+            });
         }
+        return this.closePromise;
     }
+
 }
 
 module.exports = SyslogClient;