adonisjs-server-stats 1.5.3 → 1.6.1

package/dist/src/collectors/auto_detect.js

@@ -0,0 +1,116 @@
+import { log, dim, green, bold } from '../utils/logger.js';
+/**
+ * Probe whether a package is importable at runtime.
+ *
+ * Uses dynamic `import()` wrapped in try/catch so a missing
+ * optional dependency simply returns `false` instead of crashing.
+ */
+async function isInstalled(pkg) {
+    try {
+        await import(pkg);
+        return true;
+    }
+    catch {
+        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) ──────────────────────
+    const { processCollector } = await import('./process_collector.js');
+    const { systemCollector } = await import('./system_collector.js');
+    const { httpCollector } = await import('./http_collector.js');
+    const { logCollector } = await import('./log_collector.js');
+    collectors.push(processCollector());
+    entries.push({ name: 'process', description: 'CPU, memory, event loop', enabled: true });
+    collectors.push(systemCollector());
+    entries.push({ name: 'system', description: 'OS load, memory, uptime', enabled: true });
+    collectors.push(httpCollector());
+    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 ─────────────────────────────────
+    const hasLucid = await isInstalled('@adonisjs/lucid');
+    if (hasLucid) {
+        const { dbPoolCollector } = await import('./db_pool_collector.js');
+        const { appCollector } = await import('./app_collector.js');
+        collectors.push(dbPoolCollector());
+        collectors.push(appCollector());
+    }
+    entries.push({
+        name: 'db-pool',
+        description: 'connection pool stats',
+        enabled: hasLucid,
+        reason: hasLucid ? 'found @adonisjs/lucid' : 'install @adonisjs/lucid to enable',
+    });
+    entries.push({
+        name: 'app',
+        description: 'app-level DB metrics',
+        enabled: hasLucid,
+        reason: hasLucid ? 'found @adonisjs/lucid' : 'install @adonisjs/lucid to enable',
+    });
+    // ── Conditional: @adonisjs/redis ─────────────────────────────────
+    const hasRedis = await isInstalled('@adonisjs/redis');
+    if (hasRedis) {
+        const { redisCollector } = await import('./redis_collector.js');
+        collectors.push(redisCollector());
+    }
+    entries.push({
+        name: 'redis',
+        description: 'connections, commands, memory',
+        enabled: hasRedis,
+        reason: hasRedis ? 'found @adonisjs/redis' : 'install @adonisjs/redis to enable',
+    });
+    // ── 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 },
+        }));
+    }
+    entries.push({
+        name: 'queue',
+        description: 'jobs, wait time, throughput',
+        enabled: hasBullMQ,
+        reason: hasBullMQ ? 'found bullmq' : 'install bullmq to enable',
+    });
+    // ── Rich boot log ────────────────────────────────────────────────
+    const total = entries.length;
+    const active = entries.filter((e) => e.enabled).length;
+    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}`;
+        }
+        const mark = dim('✗');
+        const detail = dim('— ' + (entry.reason ?? entry.description));
+        return `  ${mark} ${dim(paddedName)}  ${detail}`;
+    });
+    log.block('collectors (auto-detected):', lines);
+    return { collectors, total, active };
+}

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

@@ -35,6 +35,15 @@ export interface MetricCollector {
      * like `'process'`, `'http'`, `'redis'`, etc.
      */
     name: string;
+    /**
+     * Short description shown in the startup log.
+     *
+     * Include key options so the developer can verify the collector
+     * is configured correctly at a glance.
+     *
+     * @example `'http — buffer: 10k, window: 60s'`
+     */
+    label?: string;
     /**
      * Called once when the {@link StatsEngine} starts.
      *
@@ -48,6 +57,14 @@ export interface MetricCollector {
      * Use this to clean up resources (e.g. close connections, clear timers).
      */
     stop?(): void | Promise<void>;
+    /**
+     * Return collector-specific configuration for diagnostics.
+     *
+     * Used by the Internals diagnostics endpoint to show resolved
+     * configuration for each collector. Sensitive values (e.g. passwords)
+     * should be redacted.
+     */
+    getConfig?(): Record<string, unknown>;
     /**
      * Collect metrics and return them as a flat key-value record.
      *

package/dist/src/collectors/collector.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"collector.d.ts","sourceRoot":"","sources":["../../../src/collectors/collector.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAE9C;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;;OAKG;IACH,IAAI,EAAE,MAAM,CAAA;IAEZ;;;;;OAKG;IACH,KAAK,CAAC,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAE9B;;;;OAIG;IACH,IAAI,CAAC,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAE7B;;;;;;;;;;;;;OAaG;IACH,OAAO,IAAI,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC,CAAA;CAC9E"}
+{"version":3,"file":"collector.d.ts","sourceRoot":"","sources":["../../../src/collectors/collector.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAE9C;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;;OAKG;IACH,IAAI,EAAE,MAAM,CAAA;IAEZ;;;;;;;OAOG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IAEd;;;;;OAKG;IACH,KAAK,CAAC,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAE9B;;;;OAIG;IACH,IAAI,CAAC,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAE7B;;;;;;OAMG;IACH,SAAS,CAAC,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAErC;;;;;;;;;;;;;OAaG;IACH,OAAO,IAAI,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC,CAAA;CAC9E"}

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

@@ -1 +1 @@
-{"version":3,"file":"db_pool_collector.d.ts","sourceRoot":"","sources":["../../../src/collectors/db_pool_collector.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAA;AAErD;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,MAAM,CAAA;CACxB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,eAAe,CAAC,IAAI,CAAC,EAAE,sBAAsB,GAAG,eAAe,CA4B9E"}
+{"version":3,"file":"db_pool_collector.d.ts","sourceRoot":"","sources":["../../../src/collectors/db_pool_collector.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAA;AAUrD;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,MAAM,CAAA;CACxB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,eAAe,CAAC,IAAI,CAAC,EAAE,sBAAsB,GAAG,eAAe,CA8D9E"}

package/dist/src/collectors/db_pool_collector.js

@@ -1,3 +1,4 @@
+import { log, dim, bold } from '../utils/logger.js';
 /**
  * Monitors the Knex connection pool for a Lucid database connection.
  *
@@ -21,17 +22,41 @@
  */
 export function dbPoolCollector(opts) {
     const connectionName = opts?.connectionName ?? 'postgres';
+    let warnedLucidMissing = false;
+    let warnedConnectionNotFound = false;
+    let warnedPoolUnavailable = false;
     return {
         name: 'db_pool',
+        label: `db_pool — connection: ${connectionName}`,
+        getConfig() {
+            return { connectionName };
+        },
         async collect() {
             try {
                 const { default: db } = await import('@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 {
@@ -42,6 +67,14 @@ export function dbPoolCollector(opts) {
                 };
             }
             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 };
             }
         },

package/dist/src/collectors/http_collector.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"http_collector.d.ts","sourceRoot":"","sources":["../../../src/collectors/http_collector.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAA;AAE7D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAA;AAErD;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IAEnB;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAID;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,IAAI,cAAc,CAOlD;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,aAAa,CAAC,IAAI,CAAC,EAAE,oBAAoB,GAAG,eAAe,CAiB1E"}
+{"version":3,"file":"http_collector.d.ts","sourceRoot":"","sources":["../../../src/collectors/http_collector.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAA;AAG7D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAA;AAErD;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IAEnB;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAID;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,IAAI,cAAc,CAOlD;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,aAAa,CAAC,IAAI,CAAC,EAAE,oBAAoB,GAAG,eAAe,CAmC1E"}

package/dist/src/collectors/http_collector.js

@@ -1,4 +1,5 @@
 import { RequestMetrics } from '../engine/request_metrics.js';
+import { log } from '../utils/logger.js';
 let sharedInstance = null;
 /**
  * Returns the shared {@link RequestMetrics} instance created by
@@ -43,14 +44,32 @@ export function httpCollector(opts) {
     sharedInstance = metrics;
     return {
         name: 'http',
-        collect() {
-            const m = metrics.getMetrics();
+        label: `http — buffer: ${(opts?.maxRecords ?? 10_000).toLocaleString()}, window: ${(opts?.windowMs ?? 60_000) / 1000}s`,
+        getConfig() {
             return {
-                requestsPerSecond: m.requestsPerSecond,
-                avgResponseTimeMs: m.averageResponseTimeMs,
-                errorRate: m.errorRate,
-                activeHttpConnections: m.activeConnections,
+                maxRecords: opts?.maxRecords ?? 10_000,
+                windowMs: opts?.windowMs ?? 60_000,
             };
         },
+        collect() {
+            try {
+                const m = metrics.getMetrics();
+                return {
+                    requestsPerSecond: m.requestsPerSecond,
+                    avgResponseTimeMs: m.averageResponseTimeMs,
+                    errorRate: m.errorRate,
+                    activeHttpConnections: m.activeConnections,
+                };
+            }
+            catch (error) {
+                log.warn(`http collector failed: ${error.message}`);
+                return {
+                    requestsPerSecond: 0,
+                    avgResponseTimeMs: 0,
+                    errorRate: 0,
+                    activeHttpConnections: 0,
+                };
+            }
+        },
     };
 }

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

@@ -11,4 +11,6 @@ export type { QueueCollectorOptions, QueueRedisConnection } from './queue_collec
 export { logCollector, getLogStreamService } from './log_collector.js';
 export type { LogCollectorOptions } from './log_collector.js';
 export { appCollector } from './app_collector.js';
+export { autoDetectCollectors } from './auto_detect.js';
+export type { AutoDetectResult } from './auto_detect.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/src/collectors/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/collectors/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAA;AACrD,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAA;AACzD,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AACvD,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA;AACtE,YAAY,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAA;AAC/D,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAA;AACxD,YAAY,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAA;AACpE,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AACrD,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AACrD,YAAY,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAA;AACvF,OAAO,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAA;AACtE,YAAY,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAA;AAC7D,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/collectors/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAA;AACrD,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAA;AACzD,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AACvD,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA;AACtE,YAAY,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAA;AAC/D,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAA;AACxD,YAAY,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAA;AACpE,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AACrD,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AACrD,YAAY,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAA;AACvF,OAAO,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAA;AACtE,YAAY,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAA;AAC7D,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AACjD,OAAO,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAA;AACvD,YAAY,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAA"}

package/dist/src/collectors/index.js

@@ -6,3 +6,4 @@ export { redisCollector } from './redis_collector.js';
 export { queueCollector } from './queue_collector.js';
 export { logCollector, getLogStreamService } from './log_collector.js';
 export { appCollector } from './app_collector.js';
+export { autoDetectCollectors } from './auto_detect.js';

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

@@ -24,10 +24,13 @@ export interface LogCollectorOptions {
  */
 export declare function getLogStreamService(): LogStreamService | null;
 /**
- * Monitors a JSON log file and reports rolling error/warning counts.
+ * Monitors log entries and reports rolling error/warning counts.
  *
- * Uses {@link LogStreamService} internally to poll the log file every
- * 2 seconds and maintain a 5-minute sliding window of entries.
+ * **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
@@ -41,8 +44,12 @@ export declare function getLogStreamService(): LogStreamService | null;
  * ```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;
+export declare function logCollector(opts?: LogCollectorOptions): MetricCollector;
 //# sourceMappingURL=log_collector.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"log_collector.d.ts","sourceRoot":"","sources":["../../../src/collectors/log_collector.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,qCAAqC,CAAA;AAEtE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAA;AAErD;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;;;;;OAQG;IACH,OAAO,EAAE,MAAM,CAAA;CAChB;AAID;;;;;;GAMG;AACH,wBAAgB,mBAAmB,IAAI,gBAAgB,GAAG,IAAI,CAE7D;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,mBAAmB,GAAG,eAAe,CAyBvE"}
+{"version":3,"file":"log_collector.d.ts","sourceRoot":"","sources":["../../../src/collectors/log_collector.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,gBAAgB,EAAE,MAAM,qCAAqC,CAAA;AAGtE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAA;AAErD;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;;;;;OAQG;IACH,OAAO,EAAE,MAAM,CAAA;CAChB;AAID;;;;;;GAMG;AACH,wBAAgB,mBAAmB,IAAI,gBAAgB,GAAG,IAAI,CAE7D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,YAAY,CAAC,IAAI,CAAC,EAAE,mBAAmB,GAAG,eAAe,CAmExE"}

package/dist/src/collectors/log_collector.js

@@ -1,4 +1,6 @@
+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
@@ -11,10 +13,13 @@ export function getLogStreamService() {
     return sharedLogStream;
 }
 /**
- * Monitors a JSON log file and reports rolling error/warning counts.
+ * Monitors log entries and reports rolling error/warning counts.
  *
- * Uses {@link LogStreamService} internally to poll the log file every
- * 2 seconds and maintain a 5-minute sliding window of entries.
+ * **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
@@ -28,16 +33,57 @@ export function getLogStreamService() {
  * ```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 function logCollector(opts) {
-    const service = new LogStreamService(opts.logPath);
+    const service = new LogStreamService(opts?.logPath);
     sharedLogStream = service;
+    let warnedMissingFile = false;
+    let warnedStartFailure = false;
     return {
         name: 'log',
+        label: opts?.logPath ? `log — file: ${opts.logPath}` : 'log — pino stream (zero-config)',
+        getConfig() {
+            return {
+                logPath: opts?.logPath ?? null,
+                mode: opts?.logPath ? 'file' : 'stream',
+            };
+        },
         async start() {
-            await service.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.'),
+                        ]);
+                    }
+                }
+            }
+            // Stream mode: no startup needed — entries arrive via ingest()
         },
         stop() {
             service.stop();

package/dist/src/collectors/process_collector.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"process_collector.d.ts","sourceRoot":"","sources":["../../../src/collectors/process_collector.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAA;AAErD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,IAAI,eAAe,CA8ClD"}
+{"version":3,"file":"process_collector.d.ts","sourceRoot":"","sources":["../../../src/collectors/process_collector.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAA;AAErD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,IAAI,eAAe,CAmDlD"}

package/dist/src/collectors/process_collector.js

@@ -33,6 +33,10 @@ export function processCollector() {
     }
     return {
         name: 'process',
+        label: 'process — cpu, memory, event loop, uptime',
+        getConfig() {
+            return {};
+        },
         start() {
             if (!started) {
                 histogram.enable();

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

@@ -1 +1 @@
-{"version":3,"file":"queue_collector.d.ts","sourceRoot":"","sources":["../../../src/collectors/queue_collector.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAA;AAErD;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,kBAAkB;IAClB,IAAI,EAAE,MAAM,CAAA;IAEZ,kBAAkB;IAClB,IAAI,EAAE,MAAM,CAAA;IAEZ,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAElB;;;;;;;;;;;;;;OAcG;IACH,UAAU,EAAE,oBAAoB,CAAA;CACjC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,qBAAqB,GAAG,eAAe,CA8B3E"}
+{"version":3,"file":"queue_collector.d.ts","sourceRoot":"","sources":["../../../src/collectors/queue_collector.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAA;AAErD;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,kBAAkB;IAClB,IAAI,EAAE,MAAM,CAAA;IAEZ,kBAAkB;IAClB,IAAI,EAAE,MAAM,CAAA;IAEZ,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAElB;;;;;;;;;;;;;;OAcG;IACH,UAAU,EAAE,oBAAoB,CAAA;CACjC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,qBAAqB,GAAG,eAAe,CA0F3E"}

package/dist/src/collectors/queue_collector.js

@@ -1,3 +1,4 @@
+import { log, dim, bold } from '../utils/logger.js';
 /**
  * Monitors a BullMQ job queue for active, waiting, delayed, and failed jobs.
  *
@@ -27,9 +28,36 @@
  */
 export function queueCollector(opts) {
     const queueName = opts.queueName ?? 'default';
+    let warnedMissingBullmq = false;
+    let warnedConnectionError = false;
+    let warnedMissingConnection = false;
     return {
         name: 'queue',
+        label: `queue — ${queueName} @ ${opts.connection?.host ?? '?'}:${opts.connection?.port ?? '?'}`,
+        getConfig() {
+            return {
+                queueName,
+                connectionHost: opts.connection?.host ?? '?',
+                connectionPort: opts.connection?.port ?? '?',
+            };
+        },
         async collect() {
+            if (!opts.connection) {
+                if (!warnedMissingConnection) {
+                    warnedMissingConnection = true;
+                    log.warn(`Queue collector ${bold(queueName)}: missing ${bold('connection')} option`);
+                    log.block('Provide a Redis connection when creating the collector:', [
+                        `${dim('queueCollector({ connection: { host: "localhost", port: 6379 } })')}`,
+                    ]);
+                }
+                return {
+                    queueActive: 0,
+                    queueWaiting: 0,
+                    queueDelayed: 0,
+                    queueFailed: 0,
+                    queueWorkerCount: 0,
+                };
+            }
             try {
                 const { Queue } = await import('bullmq');
                 const queue = new Queue(queueName, { connection: opts.connection });
@@ -43,7 +71,33 @@ export function queueCollector(opts) {
                     queueWorkerCount: workers.length,
                 };
             }
-            catch {
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                const isImportError = message.includes('Cannot find package') ||
+                    message.includes('MODULE_NOT_FOUND') ||
+                    message.includes('ERR_MODULE_NOT_FOUND');
+                if (isImportError) {
+                    if (!warnedMissingBullmq) {
+                        warnedMissingBullmq = true;
+                        log.warn(`Queue collector ${bold(queueName)}: ${bold('bullmq')} is not installed`);
+                        log.block('Install the peer dependency to enable queue metrics:', [
+                            `${bold('npm install bullmq')}`,
+                            dim('Queue metrics will return zeros until bullmq is available.'),
+                        ]);
+                    }
+                }
+                else {
+                    if (!warnedConnectionError) {
+                        warnedConnectionError = true;
+                        const { host, port } = opts.connection;
+                        log.warn(`Queue collector ${bold(queueName)}: cannot connect to Redis at ${bold(`${host}:${port}`)}`);
+                        log.block('Connection failed:', [
+                            `${dim('Error:')} ${message}`,
+                            dim('Is Redis running? Check with: redis-cli ping'),
+                            dim('Queue metrics will return zeros until the connection succeeds.'),
+                        ]);
+                    }
+                }
                 return {
                     queueActive: 0,
                     queueWaiting: 0,

package/dist/src/collectors/redis_collector.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"redis_collector.d.ts","sourceRoot":"","sources":["../../../src/collectors/redis_collector.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAA;AAErD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,IAAI,eAAe,CA4DhD"}
+{"version":3,"file":"redis_collector.d.ts","sourceRoot":"","sources":["../../../src/collectors/redis_collector.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAA;AAMrD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,IAAI,eAAe,CAoGhD"}

package/dist/src/collectors/redis_collector.js

@@ -1,3 +1,7 @@
+import { log, dim, bold } from '../utils/logger.js';
+let warnedNotInstalled = false;
+let warnedPingFailed = false;
+let warnedConnectionError = false;
 /**
  * Monitors Redis health, memory, connections, keys, and cache hit rate.
  *
@@ -16,6 +20,10 @@
 export function redisCollector() {
     return {
         name: 'redis',
+        label: 'redis — memory, clients, keys, hit rate',
+        getConfig() {
+            return {};
+        },
         async collect() {
             const defaults = {
                 redisOk: false,
@@ -24,11 +32,33 @@ export function redisCollector() {
                 redisKeysCount: 0,
                 redisHitRate: 0,
             };
+            let redis;
+            try {
+                const mod = await import('@adonisjs/redis/services/main');
+                redis = mod.default;
+            }
+            catch {
+                if (!warnedNotInstalled) {
+                    warnedNotInstalled = true;
+                    log.block(`Redis collector ${bold('skipped')} — @adonisjs/redis is not installed`, [
+                        dim('Redis metrics will return defaults until the package is added.'),
+                        `Run ${bold('node ace add @adonisjs/redis')} to install it.`,
+                    ]);
+                }
+                return defaults;
+            }
             try {
-                const { default: redis } = await import('@adonisjs/redis/services/main');
                 const pong = await redis.ping();
-                if (pong !== 'PONG')
+                if (pong !== 'PONG') {
+                    if (!warnedPingFailed) {
+                        warnedPingFailed = true;
+                        log.block(`Redis collector ${bold('unhealthy')} — PING returned ${bold(String(pong))} instead of PONG`, [
+                            dim('Redis may be down or misconfigured.'),
+                            `Check your connection settings in ${bold('config/redis.ts')}.`,
+                        ]);
+                    }
                     return defaults;
+                }
                 const [memoryInfo, statsInfo, dbSize] = await Promise.all([
                     redis.info('memory'),
                     redis.info('stats'),
@@ -60,7 +90,15 @@ export function redisCollector() {
                     redisHitRate: hitRate,
                 };
             }
-            catch {
+            catch (error) {
+                if (!warnedConnectionError) {
+                    warnedConnectionError = true;
+                    const message = error instanceof Error ? error.message : String(error);
+                    log.block(`Redis collector ${bold('error')} — failed to communicate with Redis`, [
+                        dim(message),
+                        `Make sure Redis is running and accessible. Check ${bold('config/redis.ts')} for connection details.`,
+                    ]);
+                }
                 return defaults;
             }
         },

package/dist/src/collectors/system_collector.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"system_collector.d.ts","sourceRoot":"","sources":["../../../src/collectors/system_collector.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAA;AAErD;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,IAAI,eAAe,CAgBjD"}
+{"version":3,"file":"system_collector.d.ts","sourceRoot":"","sources":["../../../src/collectors/system_collector.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAA;AAErD;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,IAAI,eAAe,CAqBjD"}

package/dist/src/collectors/system_collector.js

@@ -13,6 +13,10 @@ import os from 'node:os';
 export function systemCollector() {
     return {
         name: 'system',
+        label: 'system — load avg, memory, uptime',
+        getConfig() {
+            return {};
+        },
         collect() {
             const loadAvg = os.loadavg();
             return {