adonisjs-server-stats 1.10.0 → 1.10.3

package/dist/src/collectors/auto_detect.js

@@ -1,14 +1,5 @@
 import { appImport } from '../utils/app_import.js';
 import { log, dim, green, bold } from '../utils/logger.js';
-/**
- * Probe whether a package is importable at runtime.
- *
- * Uses {@link appImport} which resolves from `process.cwd()` first,
- * handling the common case where adonisjs-server-stats is symlinked
- * (e.g. `file:../../adonisjs-server-stats` in package.json). Without
- * this, `import(pkg)` resolves from the symlink *target* directory,
- * which may have devDependency stubs instead of the real packages.
- */
 async function isInstalled(pkg) {
     try {
         await appImport(pkg);
@@ -18,29 +9,16 @@ async function isInstalled(pkg) {
         return false;
     }
 }
-/**
- * Auto-detect which metric collectors to enable based on installed packages.
- *
- * Always enables collectors with no external dependencies:
- * - `processCollector` -- Node.js process metrics
- * - `systemCollector` -- OS-level system metrics
- * - `httpCollector` -- HTTP request metrics
- * - `logCollector` -- log stream metrics
- *
- * Conditionally enables collectors when their peer dependency is importable:
- * - `dbPoolCollector` + `appCollector` -- when `@adonisjs/lucid` is installed
- * - `redisCollector` -- when `@adonisjs/redis` is installed
- * - `queueCollector` -- when `bullmq` is installed
- *
- * This function is meant to run at startup, so the async overhead of
- * probing packages is acceptable.
- *
- * @returns Resolved collectors and detection metadata for the boot summary.
- */
-export async function autoDetectCollectors() {
-    const collectors = [];
-    const entries = [];
-    // ── Always-on collectors (no external deps) ──────────────────────
+/** Push an optional collector entry with auto-generated reason. */
+function pushOptionalEntry(entries, opts) {
+    entries.push({
+        name: opts.name,
+        description: opts.description,
+        enabled: opts.enabled,
+        reason: opts.enabled ? `found ${opts.pkg}` : `install ${opts.pkg} to enable`,
+    });
+}
+async function registerCoreCollectors(collectors, entries) {
     const { processCollector } = await import('./process_collector.js');
     const { systemCollector } = await import('./system_collector.js');
     const { httpCollector } = await import('./http_collector.js');
@@ -53,7 +31,8 @@ export async function autoDetectCollectors() {
     entries.push({ name: 'http', description: 'req/s, latency, errors', enabled: true });
     collectors.push(logCollector());
     entries.push({ name: 'log', description: 'error & warning counts', enabled: true });
-    // ── Conditional: @adonisjs/lucid ─────────────────────────────────
+}
+async function registerOptionalCollectors(collectors, entries) {
     const hasLucid = await isInstalled('@adonisjs/lucid');
     if (hasLucid) {
         const { dbPoolCollector } = await import('./db_pool_collector.js');
@@ -61,60 +40,59 @@ export async function autoDetectCollectors() {
         collectors.push(dbPoolCollector());
         collectors.push(appCollector());
     }
-    entries.push({
+    pushOptionalEntry(entries, {
         name: 'db-pool',
         description: 'connection pool stats',
         enabled: hasLucid,
-        reason: hasLucid ? 'found @adonisjs/lucid' : 'install @adonisjs/lucid to enable',
+        pkg: '@adonisjs/lucid',
     });
-    entries.push({
+    pushOptionalEntry(entries, {
         name: 'app',
         description: 'app-level DB metrics',
         enabled: hasLucid,
-        reason: hasLucid ? 'found @adonisjs/lucid' : 'install @adonisjs/lucid to enable',
+        pkg: '@adonisjs/lucid',
     });
-    // ── Conditional: @adonisjs/redis ─────────────────────────────────
     const hasRedis = await isInstalled('@adonisjs/redis');
     if (hasRedis) {
         const { redisCollector } = await import('./redis_collector.js');
         collectors.push(redisCollector());
     }
-    entries.push({
+    pushOptionalEntry(entries, {
         name: 'redis',
         description: 'connections, commands, memory',
         enabled: hasRedis,
-        reason: hasRedis ? 'found @adonisjs/redis' : 'install @adonisjs/redis to enable',
+        pkg: '@adonisjs/redis',
     });
-    // ── Conditional: bullmq ──────────────────────────────────────────
     const hasBullMQ = await isInstalled('bullmq');
     if (hasBullMQ) {
         const { queueCollector } = await import('./queue_collector.js');
-        collectors.push(queueCollector({
-            queueName: 'default',
-            connection: { host: '127.0.0.1', port: 6379 },
-        }));
+        collectors.push(queueCollector({ queueName: 'default', connection: { host: '127.0.0.1', port: 6379 } }));
     }
-    entries.push({
+    pushOptionalEntry(entries, {
         name: 'queue',
         description: 'jobs, wait time, throughput',
         enabled: hasBullMQ,
-        reason: hasBullMQ ? 'found bullmq' : 'install bullmq to enable',
+        pkg: 'bullmq',
     });
-    // ── Rich boot log ────────────────────────────────────────────────
-    const total = entries.length;
-    const active = entries.filter((e) => e.enabled).length;
+}
+function printBootLog(entries) {
     const maxNameLen = Math.max(...entries.map((e) => e.name.length));
     const lines = entries.map((entry) => {
         const paddedName = entry.name.padEnd(maxNameLen);
         if (entry.enabled) {
-            const mark = green('✔');
             const detail = entry.reason ? dim('— ' + entry.reason) : dim('— ' + entry.description);
-            return `  ${mark} ${bold(paddedName)}  ${detail}`;
+            return `  ${green('✔')} ${bold(paddedName)}  ${detail}`;
         }
-        const mark = dim('✗');
         const detail = dim('— ' + (entry.reason ?? entry.description));
-        return `  ${mark} ${dim(paddedName)}  ${detail}`;
+        return `  ${dim('✗')} ${dim(paddedName)}  ${detail}`;
     });
     log.block('collectors (auto-detected):', lines);
-    return { collectors, total, active };
+}
+export async function autoDetectCollectors() {
+    const collectors = [];
+    const entries = [];
+    await registerCoreCollectors(collectors, entries);
+    await registerOptionalCollectors(collectors, entries);
+    printBootLog(entries);
+    return { collectors, total: entries.length, active: entries.filter((e) => e.enabled).length };
 }

package/dist/src/collectors/db_pool_collector.d.ts

@@ -1,4 +1,18 @@
 import type { MetricCollector } from './collector.js';
+/** Minimal interface for a Knex connection pool. */
+export interface KnexPool {
+    numUsed?(): number;
+    numFree?(): number;
+    numPendingAcquires?(): number;
+    max?: number;
+}
+/** Extract pool stats from a Knex pool object, defaulting to 0. */
+export declare function extractPoolMetrics(pool: Partial<KnexPool>): {
+    dbPoolUsed: number;
+    dbPoolFree: number;
+    dbPoolPending: number;
+    dbPoolMax: number;
+};
 /**
  * Options for {@link dbPoolCollector}.
  */
@@ -15,22 +29,6 @@ export interface DbPoolCollectorOptions {
 /**
  * Monitors the Knex connection pool for a Lucid database connection.
  *
- * **Metrics produced:**
- * - `dbPoolUsed` -- connections currently checked out
- * - `dbPoolFree` -- idle connections available
- * - `dbPoolPending` -- queries waiting for a connection
- * - `dbPoolMax` -- maximum pool size
- *
- * Returns zeros if the connection or pool is unavailable.
- *
  * **Peer dependencies:** `@adonisjs/lucid`
- *
- * @example
- * ```ts
- * import { dbPoolCollector } from 'adonisjs-server-stats/collectors'
- *
- * dbPoolCollector()                                // monitor 'postgres'
- * dbPoolCollector({ connectionName: 'mysql' })     // monitor 'mysql'
- * ```
  */
 export declare function dbPoolCollector(opts?: DbPoolCollectorOptions): MetricCollector;

package/dist/src/collectors/db_pool_collector.js

@@ -1,25 +1,20 @@
 import { appImport } from '../utils/app_import.js';
 import { log, dim, bold } from '../utils/logger.js';
+/** Default pool metrics returned when the pool is unavailable. */
+const POOL_DEFAULTS = { dbPoolUsed: 0, dbPoolFree: 0, dbPoolPending: 0, dbPoolMax: 0 };
+/** Extract pool stats from a Knex pool object, defaulting to 0. */
+export function extractPoolMetrics(pool) {
+    return {
+        dbPoolUsed: pool.numUsed?.() ?? 0,
+        dbPoolFree: pool.numFree?.() ?? 0,
+        dbPoolPending: pool.numPendingAcquires?.() ?? 0,
+        dbPoolMax: pool.max ?? 0,
+    };
+}
 /**
  * Monitors the Knex connection pool for a Lucid database connection.
  *
- * **Metrics produced:**
- * - `dbPoolUsed` -- connections currently checked out
- * - `dbPoolFree` -- idle connections available
- * - `dbPoolPending` -- queries waiting for a connection
- * - `dbPoolMax` -- maximum pool size
- *
- * Returns zeros if the connection or pool is unavailable.
- *
  * **Peer dependencies:** `@adonisjs/lucid`
- *
- * @example
- * ```ts
- * import { dbPoolCollector } from 'adonisjs-server-stats/collectors'
- *
- * dbPoolCollector()                                // monitor 'postgres'
- * dbPoolCollector({ connectionName: 'mysql' })     // monitor 'mysql'
- * ```
  */
 export function dbPoolCollector(opts) {
     const connectionName = opts?.connectionName ?? 'postgres';
@@ -34,50 +29,70 @@ export function dbPoolCollector(opts) {
         },
         async collect() {
             try {
-                const { default: db } = await appImport('@adonisjs/lucid/services/db');
-                const connection = db.manager.get(connectionName);
-                if (!connection) {
-                    if (!warnedConnectionNotFound) {
-                        warnedConnectionNotFound = true;
-                        log.block(`db_pool: connection ${bold(connectionName)} not found in db.manager`, [
-                            dim('The name must match a key in your') +
-                                ` ${bold('config/database.ts')} ` +
-                                dim('connections object.'),
-                            dim('Available connections are registered at app boot — double-check spelling.'),
-                        ]);
-                    }
-                    return { dbPoolUsed: 0, dbPoolFree: 0, dbPoolPending: 0, dbPoolMax: 0 };
-                }
-                const pool = connection.connection?.pool;
-                if (!pool) {
-                    if (!warnedPoolUnavailable) {
-                        warnedPoolUnavailable = true;
-                        log.block(`db_pool: pool not available on connection ${bold(connectionName)}`, [
-                            dim('This usually means the connection has not been established yet,'),
-                            dim('or the database driver does not expose a Knex-style pool.'),
-                            dim('Pool metrics will report zeros until the pool is available.'),
-                        ]);
-                    }
-                    return { dbPoolUsed: 0, dbPoolFree: 0, dbPoolPending: 0, dbPoolMax: 0 };
-                }
-                return {
-                    dbPoolUsed: pool.numUsed?.() ?? 0,
-                    dbPoolFree: pool.numFree?.() ?? 0,
-                    dbPoolPending: pool.numPendingAcquires?.() ?? 0,
-                    dbPoolMax: pool.max ?? 0,
-                };
+                return await collectPoolMetrics(connectionName, {
+                    warnConnectionNotFound(alreadyWarned) {
+                        if (!alreadyWarned)
+                            warnedConnectionNotFound = true;
+                        return warnedConnectionNotFound;
+                    },
+                    warnPoolUnavailable(alreadyWarned) {
+                        if (!alreadyWarned)
+                            warnedPoolUnavailable = true;
+                        return warnedPoolUnavailable;
+                    },
+                    isConnectionNotFoundWarned: () => warnedConnectionNotFound,
+                    isPoolUnavailableWarned: () => warnedPoolUnavailable,
+                });
             }
             catch {
-                if (!warnedLucidMissing) {
-                    warnedLucidMissing = true;
-                    log.block(`db_pool: ${bold('@adonisjs/lucid')} is not installed or failed to import`, [
-                        dim('Install it with:'),
-                        `  ${bold('node ace add @adonisjs/lucid')}`,
-                        dim('Pool metrics will report zeros until the package is available.'),
-                    ]);
-                }
-                return { dbPoolUsed: 0, dbPoolFree: 0, dbPoolPending: 0, dbPoolMax: 0 };
+                warnLucidMissing(warnedLucidMissing);
+                warnedLucidMissing = true;
+                return POOL_DEFAULTS;
             }
         },
     };
 }
+async function collectPoolMetrics(connectionName, warns) {
+    const { default: db } = await appImport('@adonisjs/lucid/services/db');
+    const connection = db.manager.get(connectionName);
+    if (!connection) {
+        warnConnectionNotFound(connectionName, warns.isConnectionNotFoundWarned());
+        warns.warnConnectionNotFound(true);
+        return POOL_DEFAULTS;
+    }
+    const pool = connection.connection?.pool;
+    if (!pool) {
+        warnPoolUnavailable(connectionName, warns.isPoolUnavailableWarned());
+        warns.warnPoolUnavailable(true);
+        return POOL_DEFAULTS;
+    }
+    return extractPoolMetrics(pool);
+}
+function warnConnectionNotFound(name, alreadyWarned) {
+    if (alreadyWarned)
+        return;
+    log.block(`db_pool: connection ${bold(name)} not found in db.manager`, [
+        dim('The name must match a key in your') +
+            ` ${bold('config/database.ts')} ` +
+            dim('connections object.'),
+        dim('Available connections are registered at app boot — double-check spelling.'),
+    ]);
+}
+function warnPoolUnavailable(name, alreadyWarned) {
+    if (alreadyWarned)
+        return;
+    log.block(`db_pool: pool not available on connection ${bold(name)}`, [
+        dim('This usually means the connection has not been established yet,'),
+        dim('or the database driver does not expose a Knex-style pool.'),
+        dim('Pool metrics will report zeros until the pool is available.'),
+    ]);
+}
+function warnLucidMissing(alreadyWarned) {
+    if (alreadyWarned)
+        return;
+    log.block(`db_pool: ${bold('@adonisjs/lucid')} is not installed or failed to import`, [
+        dim('Install it with:'),
+        `  ${bold('node ace add @adonisjs/lucid')}`,
+        dim('Pool metrics will report zeros until the package is available.'),
+    ]);
+}

package/dist/src/collectors/log_collector.d.ts

@@ -1,54 +1,7 @@
 import { LogStreamService } from '../log_stream/log_stream_service.js';
 import type { MetricCollector } from './collector.js';
-/**
- * Options for {@link logCollector}.
- */
 export interface LogCollectorOptions {
-    /**
-     * Path to the JSON log file to monitor.
-     *
-     * Relative to the application root. The file must contain
-     * newline-delimited JSON entries (one per line) with `level`
-     * and `time` fields (Pino format).
-     *
-     * @example `'logs/adonisjs.log'`
-     */
     logPath: string;
 }
-/**
- * Returns the shared {@link LogStreamService} instance created by
- * `logCollector()`, or `null` if the log collector is not configured.
- *
- * Useful for accessing the log stream outside of the collector
- * (e.g. in the LogStreamProvider for live broadcasting).
- */
 export declare function getLogStreamService(): LogStreamService | null;
-/**
- * Monitors log entries and reports rolling error/warning counts.
- *
- * **Two modes:**
- * - **Zero-config (no args):** the provider auto-hooks into the AdonisJS
- *   Pino logger at boot. Entries arrive in real-time, no file path needed.
- * - **File-based (with `logPath`):** polls a JSON log file every 2 seconds.
- *   Use this as a fallback if the auto-hook doesn't work for your setup.
- *
- * **Metrics produced:**
- * - `logErrorsLast5m` -- error + fatal entries in the last 5 minutes
- * - `logWarningsLast5m` -- warning entries in the last 5 minutes
- * - `logEntriesLast5m` -- total entries in the last 5 minutes
- * - `logEntriesPerMinute` -- entries per minute (averaged over 5 min)
- *
- * **Peer dependencies:** none
- *
- * @example
- * ```ts
- * import { logCollector } from 'adonisjs-server-stats/collectors'
- *
- * // Zero-config — auto-hooks into AdonisJS logger (recommended)
- * logCollector()
- *
- * // File-based fallback
- * logCollector({ logPath: 'logs/adonisjs.log' })
- * ```
- */
 export declare function logCollector(opts?: LogCollectorOptions): MetricCollector;

package/dist/src/collectors/log_collector.js

@@ -2,44 +2,33 @@ import { existsSync } from 'node:fs';
 import { LogStreamService } from '../log_stream/log_stream_service.js';
 import { log, dim, bold } from '../utils/logger.js';
 let sharedLogStream = null;
-/**
- * Returns the shared {@link LogStreamService} instance created by
- * `logCollector()`, or `null` if the log collector is not configured.
- *
- * Useful for accessing the log stream outside of the collector
- * (e.g. in the LogStreamProvider for live broadcasting).
- */
 export function getLogStreamService() {
     return sharedLogStream;
 }
-/**
- * Monitors log entries and reports rolling error/warning counts.
- *
- * **Two modes:**
- * - **Zero-config (no args):** the provider auto-hooks into the AdonisJS
- *   Pino logger at boot. Entries arrive in real-time, no file path needed.
- * - **File-based (with `logPath`):** polls a JSON log file every 2 seconds.
- *   Use this as a fallback if the auto-hook doesn't work for your setup.
- *
- * **Metrics produced:**
- * - `logErrorsLast5m` -- error + fatal entries in the last 5 minutes
- * - `logWarningsLast5m` -- warning entries in the last 5 minutes
- * - `logEntriesLast5m` -- total entries in the last 5 minutes
- * - `logEntriesPerMinute` -- entries per minute (averaged over 5 min)
- *
- * **Peer dependencies:** none
- *
- * @example
- * ```ts
- * import { logCollector } from 'adonisjs-server-stats/collectors'
- *
- * // Zero-config — auto-hooks into AdonisJS logger (recommended)
- * logCollector()
- *
- * // File-based fallback
- * logCollector({ logPath: 'logs/adonisjs.log' })
- * ```
- */
+function warnMissingFile(logPath, alreadyWarned) {
+    if (alreadyWarned)
+        return true;
+    log.warn(`Log file not found: ${bold(logPath)}`);
+    log.block('The log collector will keep retrying, but no metrics will appear until the file exists.', [
+        dim('Make sure the path is correct and your app is writing logs there.'),
+        dim('The file must contain newline-delimited JSON with') +
+            ` ${bold('level')} ` +
+            dim('and') +
+            ` ${bold('time')} ` +
+            dim('fields (Pino format).'),
+    ]);
+    return true;
+}
+function warnStartFailure(error, logPath, alreadyWarned) {
+    if (alreadyWarned)
+        return true;
+    log.warn(`Log collector failed to start: ${bold(String(error))}`);
+    log.block('The log collector will not produce metrics until this is resolved.', [
+        dim('Configured log path:') + ` ${bold(logPath)}`,
+        dim('Check file permissions and ensure the directory exists.'),
+    ]);
+    return true;
+}
 export function logCollector(opts) {
     if (sharedLogStream) {
         console.warn('[server-stats] logCollector() called again — stopping previous LogStreamService instance');
@@ -47,8 +36,8 @@ export function logCollector(opts) {
     }
     const service = new LogStreamService(opts?.logPath);
     sharedLogStream = service;
-    let warnedMissingFile = false;
-    let warnedStartFailure = false;
+    let warnedMissing = false;
+    let warnedStart = false;
     return {
         name: 'log',
         label: opts?.logPath ? `log — file: ${opts.logPath}` : 'log — pino stream (zero-config)',
@@ -59,35 +48,17 @@ export function logCollector(opts) {
             };
         },
         async start() {
-            if (opts?.logPath) {
-                // File-based mode
-                if (!existsSync(opts.logPath) && !warnedMissingFile) {
-                    warnedMissingFile = true;
-                    log.warn(`Log file not found: ${bold(opts.logPath)}`);
-                    log.block('The log collector will keep retrying, but no metrics will appear until the file exists.', [
-                        dim('Make sure the path is correct and your app is writing logs there.'),
-                        dim('The file must contain newline-delimited JSON with') +
-                            ` ${bold('level')} ` +
-                            dim('and') +
-                            ` ${bold('time')} ` +
-                            dim('fields (Pino format).'),
-                    ]);
-                }
-                try {
-                    await service.start();
-                }
-                catch (error) {
-                    if (!warnedStartFailure) {
-                        warnedStartFailure = true;
-                        log.warn(`Log collector failed to start: ${bold(String(error))}`);
-                        log.block('The log collector will not produce metrics until this is resolved.', [
-                            dim('Configured log path:') + ` ${bold(opts.logPath)}`,
-                            dim('Check file permissions and ensure the directory exists.'),
-                        ]);
-                    }
-                }
+            if (!opts?.logPath)
+                return;
+            if (!existsSync(opts.logPath)) {
+                warnedMissing = warnMissingFile(opts.logPath, warnedMissing);
+            }
+            try {
+                await service.start();
+            }
+            catch (error) {
+                warnedStart = warnStartFailure(error, opts.logPath, warnedStart);
             }
-            // Stream mode: no startup needed — entries arrive via ingest()
         },
         stop() {
             service.stop();

package/dist/src/collectors/queue_collector.d.ts

@@ -39,28 +39,8 @@ export interface QueueCollectorOptions {
 /**
  * Monitors a BullMQ job queue for active, waiting, delayed, and failed jobs.
  *
- * Creates a temporary BullMQ `Queue` instance each tick to fetch counts,
- * then immediately closes it.
- *
- * **Metrics produced:**
- * - `queueActive` -- jobs being processed
- * - `queueWaiting` -- jobs waiting for a worker
- * - `queueDelayed` -- jobs scheduled for the future
- * - `queueFailed` -- permanently failed jobs
- * - `queueWorkerCount` -- connected worker processes
- *
  * Returns zeros if BullMQ is unavailable or the queue cannot be reached.
  *
  * **Peer dependencies:** `bullmq`
- *
- * @example
- * ```ts
- * import { queueCollector } from 'adonisjs-server-stats/collectors'
- *
- * queueCollector({
- *   queueName: 'default',
- *   connection: { host: 'localhost', port: 6379, password: 'secret' },
- * })
- * ```
  */
 export declare function queueCollector(opts: QueueCollectorOptions): MetricCollector;