adonisjs-server-stats 1.5.4 → 1.6.2

package/dist/src/provider/server_stats_provider.js

@@ -1,12 +1,11 @@
 import { readFileSync } from 'node:fs';
-import { registerDashboardRoutes } from '../dashboard/dashboard_routes.js';
-import { DashboardStore } from '../dashboard/dashboard_store.js';
+import { getLogStreamService } from '../collectors/log_collector.js';
 import { DebugStore } from '../debug/debug_store.js';
 import { StatsEngine } from '../engine/stats_engine.js';
 import { LogStreamService } from '../log_stream/log_stream_service.js';
 import { setShouldShow, setTraceCollector, setDashboardPath, setExcludedPrefixes, setOnRequestComplete, } from '../middleware/request_tracking_middleware.js';
-import { registerDebugRoutes } from '../routes/debug_routes.js';
-import { registerStatsRoutes } from '../routes/stats_routes.js';
+import { registerAllRoutes } from '../routes/register_routes.js';
+import { log, dim, bold } from '../utils/logger.js';
 export default class ServerStatsProvider {
     app;
     intervalId = null;
@@ -21,13 +20,39 @@ export default class ServerStatsProvider {
     flushTimer = null;
     statsController = null;
     debugController = null;
+    apiController = null;
+    // Dashboard dependency check (set in boot, read in ready)
+    dashboardDepsAvailable = true;
+    // Diagnostics tracking
+    pinoHookActive = false;
+    edgePluginActive = false;
+    prometheusActive = false;
+    transmitAvailable = false;
+    transmitChannels = [];
+    resolvedConfig = null;
+    resolvedCollectors = [];
     constructor(app) {
         this.app = app;
     }
     async boot() {
+        try {
+            await this.initializeBoot();
+        }
+        catch (err) {
+            log.warn(`boot failed: ${err?.message ?? err}\n` +
+                `  ${dim('The server will continue without server-stats.')}`);
+            if (err?.stack) {
+                console.error(err.stack);
+            }
+        }
+    }
+    async initializeBoot() {
         const config = this.app.config.get('server_stats');
-        if (!config)
+        if (!config) {
+            log.warn('no config found — is config/server_stats.ts set up?');
             return;
+        }
+        log.info('booting...');
         // Wire up the per-request shouldShow callback
         if (config.shouldShow) {
             setShouldShow(config.shouldShow);
@@ -41,55 +66,95 @@ export default class ServerStatsProvider {
         }
         if (router && !this.app.inProduction) {
             const registeredPaths = [];
-            // ── Auto-register stats bar endpoint ───────────────────────
-            if (typeof config.endpoint === 'string') {
-                registerStatsRoutes(router, config.endpoint, () => this.statsController, config.shouldShow);
-                registeredPaths.push(config.endpoint);
-            }
-            // ── Auto-register debug toolbar routes ─────────────────────
+            const r = router;
             const toolbarConfig = config.devToolbar;
-            if (toolbarConfig?.enabled) {
-                const debugEndpoint = toolbarConfig.debugEndpoint ?? '/admin/api/debug';
-                registerDebugRoutes(router, debugEndpoint, () => this.debugController, config.shouldShow);
-                registeredPaths.push(debugEndpoint + '/*');
-                // ── Auto-register dashboard routes ─────────────────────────
-                if (toolbarConfig.dashboard) {
-                    const dashPath = toolbarConfig.dashboardPath ?? '/__stats';
-                    registerDashboardRoutes(router, dashPath, () => this.dashboardController, config.shouldShow);
-                    registeredPaths.push(dashPath + '/*');
+            // Derive endpoint paths for route registration
+            const statsEndpoint = typeof config.endpoint === 'string' ? config.endpoint : false;
+            const debugEndpoint = toolbarConfig?.enabled
+                ? (toolbarConfig.debugEndpoint ?? '/admin/api/debug')
+                : undefined;
+            // Check dashboard dependencies before registering dashboard routes.
+            // Must use appImport — bare import() resolves to this package's
+            // devDeps when symlinked, not the app's actual dependencies.
+            if (toolbarConfig?.enabled && toolbarConfig.dashboard) {
+                const { appImport } = await import('../utils/app_import.js');
+                const missing = [];
+                try {
+                    await appImport('knex');
                 }
+                catch {
+                    missing.push('knex');
+                }
+                try {
+                    await appImport('better-sqlite3');
+                }
+                catch {
+                    missing.push('better-sqlite3');
+                }
+                if (missing.length > 0) {
+                    this.dashboardDepsAvailable = false;
+                    log.block(`Dashboard requires ${missing.join(' and ')}. Install with:`, [
+                        '',
+                        bold(`npm install ${missing.join(' ')}`),
+                        '',
+                        dim('Dashboard routes have been skipped for now.'),
+                        dim('Everything else (stats bar, debug panel) works without it.'),
+                    ]);
+                }
+            }
+            const dashboardPath = toolbarConfig?.enabled && toolbarConfig.dashboard && this.dashboardDepsAvailable
+                ? (toolbarConfig.dashboardPath ?? '/__stats')
+                : undefined;
+            // ── Register all routes via the unified registrar ──────────
+            registerAllRoutes({
+                router: r,
+                getApiController: () => this.apiController,
+                getStatsController: () => this.statsController,
+                getDebugController: () => this.debugController,
+                getDashboardController: () => this.dashboardController,
+                statsEndpoint,
+                debugEndpoint,
+                dashboardPath,
+                shouldShow: config.shouldShow,
+            });
+            // Track which paths were registered for logging
+            if (typeof statsEndpoint === 'string') {
+                registeredPaths.push(statsEndpoint);
+            }
+            if (debugEndpoint) {
+                registeredPaths.push(debugEndpoint + '/*');
+            }
+            if (dashboardPath) {
+                registeredPaths.push(dashboardPath + '/*');
             }
             // Log registered routes
             if (registeredPaths.length > 0) {
-                const tag = '\x1b[36m[ \x1b[1m🔍 server-stats\x1b[0m\x1b[36m ]\x1b[0m';
-                const dim = (s) => `\x1b[2m${s}\x1b[0m`;
-                const bold = (s) => `\x1b[1m${s}\x1b[0m`;
-                console.log(`\n${tag} routes registered:\n` +
-                    registeredPaths.map((p) => `  ${dim('→')} ${bold(p)}`).join('\n'));
+                log.list('routes auto-registered (no manual setup needed):', registeredPaths);
                 // Only warn about global auth middleware if:
                 // 1. shouldShow is NOT configured (user hasn't set up access control)
                 // 2. There IS auth middleware in server.use() or router.use()
                 if (!config.shouldShow) {
                     const authMiddleware = this.detectGlobalAuthMiddleware();
                     if (authMiddleware.length > 0) {
-                        console.log(`\n${tag} ${bold('found global auth middleware that will run on every poll:')}\n` +
-                            authMiddleware.map((m) => `  ${dim('→')} ${m}`).join('\n') +
-                            '\n\n' +
-                            `  ${dim('these routes get polled every ~3s, so auth middleware will')}\n` +
-                            `  ${dim('trigger a DB query on each poll. here are two ways to fix it:')}\n` +
-                            '\n' +
-                            `  ${bold('option 1:')} add a shouldShow callback to your config:\n` +
-                            '\n' +
-                            `  ${dim('// config/server_stats.ts')}\n` +
-                            `  ${dim("shouldShow: (ctx) => ctx.auth?.user?.role === 'admin'")}\n` +
-                            '\n' +
-                            `  ${bold('option 2:')} move auth middleware from router.use() to a route group:\n` +
-                            '\n' +
-                            `  ${dim('// start/kernel.ts — remove from router.use()')}\n` +
-                            `  ${dim("// () => import('#middleware/silent_auth_middleware')")}\n` +
-                            '\n' +
-                            `  ${dim('// start/routes.ts — add to your route groups instead')}\n` +
-                            `  ${dim("router.group(() => { ... }).use(middleware.silentAuth())")}\n`);
+                        log.block(bold('found global auth middleware that will run on every poll:'), [
+                            ...authMiddleware.map((m) => `${dim('→')} ${m}`),
+                            '',
+                            dim('these routes get polled every ~3s, so auth middleware will'),
+                            dim('trigger a DB query on each poll. here are two ways to fix it:'),
+                            '',
+                            `${bold('option 1:')} add a shouldShow callback to your config:`,
+                            '',
+                            dim('// config/server_stats.ts'),
+                            dim("shouldShow: (ctx) => ctx.auth?.user?.role === 'admin'"),
+                            '',
+                            `${bold('option 2:')} move auth middleware from router.use() to a route group:`,
+                            '',
+                            dim('// start/kernel.ts — remove from router.use()'),
+                            dim("// () => import('#middleware/silent_auth_middleware')"),
+                            '',
+                            dim('// start/routes.ts — add to your route groups instead'),
+                            dim('router.group(() => { ... }).use(middleware.silentAuth())'),
+                        ]);
                     }
                 }
             }
@@ -97,12 +162,18 @@ export default class ServerStatsProvider {
         if (!this.app.usingEdgeJS)
             return;
         try {
-            const edge = await import('edge.js');
+            // Must use appImport for edge.js — when this package is symlinked,
+            // bare import('edge.js') resolves to the package's devDep copy,
+            // which is a different singleton than the app's Edge instance.
+            const { appImport } = await import('../utils/app_import.js');
+            const edge = await appImport('edge.js');
             const { edgePluginServerStats } = await import('../edge/plugin.js');
             edge.default.use(edgePluginServerStats(config));
+            this.edgePluginActive = true;
         }
-        catch {
-            // Edge not available — skip tag registration
+        catch (err) {
+            log.warn('could not register Edge plugin — @serverStats() tag will not work: ' +
+                err?.message);
         }
     }
     /**
@@ -155,36 +226,115 @@ export default class ServerStatsProvider {
         }
         return found;
     }
+    /**
+     * Hook into the AdonisJS logger's Pino stream to feed log entries
+     * directly into the LogStreamService — no file path needed.
+     *
+     * Uses `Symbol.for('pino.stream')` (documented Pino API) to access
+     * the underlying destination stream, then wraps its `write` method
+     * to tee entries into the log collector.
+     */
+    async hookPinoLogger() {
+        const logStream = getLogStreamService();
+        if (!logStream)
+            return; // logCollector() not in the config
+        let logger;
+        try {
+            logger = await this.app.container.make('logger');
+        }
+        catch {
+            // Logger not available
+        }
+        const pino = logger?.pino;
+        if (!pino)
+            return;
+        const streamSym = Symbol.for('pino.stream');
+        const rawStream = pino[streamSym];
+        if (!rawStream || typeof rawStream.write !== 'function')
+            return;
+        const stream = rawStream;
+        const originalWrite = stream.write.bind(stream);
+        stream.write = function (chunk, ...args) {
+            try {
+                const str = typeof chunk === 'string' ? chunk : chunk.toString();
+                const entry = JSON.parse(str);
+                if (entry && typeof entry.level === 'number') {
+                    logStream.ingest(entry);
+                }
+            }
+            catch {
+                // Not valid JSON — ignore (e.g. pino-pretty output)
+            }
+            return originalWrite(chunk, ...args);
+        };
+        this.pinoHookActive = true;
+        log.info('log collector hooked into AdonisJS logger (zero-config)');
+    }
     async ready() {
         const config = this.app.config.get('server_stats');
         if (!config)
             return;
         if (this.app.inTest && config.skipInTest !== false)
             return;
-        this.engine = new StatsEngine(config.collectors);
+        // Defer the entire initialization to setImmediate so ready() returns
+        // immediately. AdonisJS waits for all provider ready() hooks before
+        // processing HTTP requests — blocking here would hang the server.
+        // Routes use lazy controller getters that return 503 until init completes.
+        setImmediate(() => {
+            this.initializeServerStats(config).catch((err) => {
+                log.warn(`failed to initialize: ${err?.message ?? err}\n` +
+                    `  ${dim('The server will continue without server-stats.')}`);
+                if (err?.stack) {
+                    console.error(err.stack);
+                }
+            });
+        });
+    }
+    async initializeServerStats(config) {
+        this.resolvedConfig = config;
+        let collectors;
+        if (!config.collectors || config.collectors === 'auto') {
+            const { autoDetectCollectors } = await import('../collectors/auto_detect.js');
+            const result = await autoDetectCollectors();
+            collectors = result.collectors;
+            log.info(`${bold(String(result.active))} of ${bold(String(result.total))} collectors active`);
+        }
+        else {
+            collectors = config.collectors;
+        }
+        this.resolvedCollectors = collectors;
+        this.engine = new StatsEngine(collectors);
         this.app.container.singleton('server_stats.engine', () => this.engine);
         await this.engine.start();
+        // Auto-hook log collector into the AdonisJS Pino logger (zero-config)
+        await this.hookPinoLogger();
         // Create the stats controller (makes the stats route functional)
         const StatsControllerClass = (await import('../controller/server_stats_controller.js')).default;
         this.statsController = new StatsControllerClass(this.engine);
         // Dev toolbar setup
         const toolbarConfig = config.devToolbar;
         if (toolbarConfig?.enabled && !this.app.inProduction) {
-            await this.setupDevToolbar({
-                enabled: true,
-                maxQueries: toolbarConfig.maxQueries ?? 500,
-                maxEvents: toolbarConfig.maxEvents ?? 200,
-                maxEmails: toolbarConfig.maxEmails ?? 100,
-                slowQueryThresholdMs: toolbarConfig.slowQueryThresholdMs ?? 100,
-                persistDebugData: toolbarConfig.persistDebugData ?? false,
-                tracing: toolbarConfig.tracing ?? false,
-                maxTraces: toolbarConfig.maxTraces ?? 200,
-                dashboard: toolbarConfig.dashboard ?? false,
-                dashboardPath: toolbarConfig.dashboardPath ?? '/__stats',
-                retentionDays: toolbarConfig.retentionDays ?? 7,
-                dbPath: toolbarConfig.dbPath ?? '.adonisjs/server-stats/dashboard.sqlite3',
-                debugEndpoint: toolbarConfig.debugEndpoint ?? '/admin/api/debug',
-            });
+            try {
+                await this.setupDevToolbar({
+                    enabled: true,
+                    maxQueries: toolbarConfig.maxQueries ?? 500,
+                    maxEvents: toolbarConfig.maxEvents ?? 200,
+                    maxEmails: toolbarConfig.maxEmails ?? 100,
+                    slowQueryThresholdMs: toolbarConfig.slowQueryThresholdMs ?? 100,
+                    persistDebugData: toolbarConfig.persistDebugData ?? false,
+                    tracing: toolbarConfig.tracing ?? false,
+                    maxTraces: toolbarConfig.maxTraces ?? 200,
+                    dashboard: toolbarConfig.dashboard ?? false,
+                    dashboardPath: toolbarConfig.dashboardPath ?? '/__stats',
+                    retentionDays: toolbarConfig.retentionDays ?? 7,
+                    dbPath: toolbarConfig.dbPath ?? '.adonisjs/server-stats/dashboard.sqlite3',
+                    debugEndpoint: toolbarConfig.debugEndpoint ?? '/admin/api/debug',
+                });
+            }
+            catch (err) {
+                log.warn(`dev toolbar setup failed: ${err?.message ?? err}\n` +
+                    `  ${dim('Stats bar will still work, but debug panel may be unavailable.')}`);
+            }
             // Exclude the stats endpoint and user-specified prefixes from tracing
             // so the debug panel's own polling doesn't flood the timeline
             const debugEndpoint = toolbarConfig.debugEndpoint ?? '/admin/api/debug';
@@ -196,31 +346,67 @@ export default class ServerStatsProvider {
             if (prefixes.length > 0) {
                 setExcludedPrefixes(prefixes);
             }
+            // Create the unified ApiController now that debug store is available.
+            // Dashboard store is passed as a getter so it picks up the reference
+            // once setupDashboard() completes asynchronously.
+            if (this.debugStore) {
+                const logPath = this.app.makePath('logs', 'adonisjs.log');
+                const { DataAccess: DataAccessClass } = await import('../data/data_access.js');
+                const dataAccess = new DataAccessClass(this.debugStore, () => this.dashboardStore, logPath);
+                const { ApiController: ApiControllerClass } = await import('../controller/api_controller.js');
+                this.apiController = new ApiControllerClass(dataAccess);
+            }
         }
+        // ── Stats collection interval + transmit (lightweight, set up inline) ──
+        this.setupStatsInterval(config);
+        log.info('ready');
+    }
+    /**
+     * Set up the stats collection interval, transmit broadcasting,
+     * and Prometheus integration. Extracted from initializeServerStats
+     * so the ready log fires promptly.
+     */
+    setupStatsInterval(config) {
         let transmit = null;
-        if (config.transport === 'transmit') {
+        let prometheusCollector = null;
+        // Resolve transmit + prometheus asynchronously but don't block ready()
+        const resolveIntegrations = async () => {
+            if (config.transport === 'transmit') {
+                try {
+                    transmit = await this.app.container.make('transmit');
+                    if (transmit) {
+                        this.transmitAvailable = true;
+                        if (config.channelName) {
+                            this.transmitChannels.push(config.channelName);
+                        }
+                    }
+                }
+                catch {
+                    log.info('transport is "transmit" but @adonisjs/transmit is not installed — falling back to polling');
+                }
+            }
             try {
-                transmit = await this.app.container.make('transmit');
+                const mod = await import('../prometheus/prometheus_collector.js');
+                prometheusCollector = mod.ServerStatsCollector.instance;
             }
             catch {
-                // Transmit not installed — skip broadcasting
+                // Prometheus not installed — skip (optional dependency)
             }
-        }
-        let prometheusCollector = null;
-        try {
-            const mod = await import('../prometheus/prometheus_collector.js');
-            prometheusCollector = mod.ServerStatsCollector.instance;
-        }
-        catch {
-            // Prometheus not installed — skip
-        }
+            if (prometheusCollector) {
+                this.prometheusActive = true;
+                log.info('Prometheus integration active');
+            }
+        };
+        resolveIntegrations().catch(() => { });
         this.intervalId = setInterval(async () => {
             try {
                 const stats = await this.engine.collect();
                 if (transmit && config.channelName) {
+                    ;
                     transmit.broadcast(config.channelName, JSON.parse(JSON.stringify(stats)));
                 }
                 if (prometheusCollector) {
+                    ;
                     prometheusCollector.update(stats);
                 }
                 config.onStats?.(stats);
@@ -247,7 +433,7 @@ export default class ServerStatsProvider {
             emitter = await this.app.container.make('emitter');
         }
         catch {
-            // Emitter not available
+            log.warn('AdonisJS emitter not available — query and event collection will be disabled');
         }
         // Get the router
         let router = null;
@@ -259,9 +445,14 @@ export default class ServerStatsProvider {
         }
         await this.debugStore.start(emitter, router);
         // Create the debug controller (makes the debug routes functional)
-        const logPath = this.app.makePath('logs', 'adonisjs.log');
+        const serverConfig = this.app.config.get('server_stats');
         const DebugControllerClass = (await import('../controller/debug_controller.js')).default;
-        this.debugController = new DebugControllerClass(this.debugStore, logPath);
+        this.debugController = new DebugControllerClass(this.debugStore, serverConfig, {
+            getEngine: () => this.engine,
+            getDashboardStore: () => this.dashboardStore,
+            getProviderDiagnostics: () => this.getDiagnostics(),
+            getApp: () => this.app,
+        });
         // Wire trace collector into the request tracking middleware
         if (this.debugStore.traces) {
             setTraceCollector(this.debugStore.traces);
@@ -286,7 +477,11 @@ export default class ServerStatsProvider {
             // Transmit not installed — debug panel will use polling
         }
         if (debugTransmit) {
+            this.transmitAvailable = true;
             const debugChannel = 'server-stats/debug';
+            if (!this.transmitChannels.includes(debugChannel)) {
+                this.transmitChannels.push(debugChannel);
+            }
             const pendingTypes = new Set();
             this.debugStore.onNewItem((type) => {
                 // Debounce: coalesce rapid events into a single broadcast
@@ -298,6 +493,7 @@ export default class ServerStatsProvider {
                     const types = Array.from(pendingTypes);
                     pendingTypes.clear();
                     try {
+                        ;
                         debugTransmit.broadcast(debugChannel, { types });
                     }
                     catch {
@@ -306,9 +502,17 @@ export default class ServerStatsProvider {
                 }, 200);
             });
         }
-        // Full-page dashboard setup (routes already registered in boot)
-        if (toolbarConfig.dashboard) {
-            await this.setupDashboard(toolbarConfig, emitter);
+        // Full-page dashboard setup — deferred with setImmediate so it runs
+        // AFTER the current event-loop cycle completes. This guarantees
+        // ready() returns and AdonisJS can process HTTP requests while the
+        // SQLite store initializes in the background.
+        if (toolbarConfig.dashboard && this.dashboardDepsAvailable) {
+            setImmediate(() => {
+                this.setupDashboard(toolbarConfig, emitter).catch((err) => {
+                    log.warn(`dashboard setup failed: ${err?.message ?? err}\n` +
+                        `  ${dim('Everything else continues to work.')}`);
+                });
+            });
         }
     }
     /**
@@ -319,42 +523,99 @@ export default class ServerStatsProvider {
      * This method creates the controller so those routes become functional.
      */
     async setupDashboard(toolbarConfig, emitter) {
-        // Create and start the DashboardStore
-        this.dashboardStore = new DashboardStore(toolbarConfig);
+        log.info('dashboard: initializing SQLite store...');
+        // Dynamically import DashboardStore so knex/better-sqlite3 are truly optional
+        const { DashboardStore: DashboardStoreClass } = await import('../dashboard/dashboard_store.js');
+        this.dashboardStore = new DashboardStoreClass(toolbarConfig);
         const appRoot = this.app.makePath('');
         try {
-            await this.dashboardStore.start(null, emitter, appRoot);
+            // Timeout safety net: if SQLite init hangs (e.g. wrong native binary
+            // loaded via symlink), abort after 15s instead of freezing forever.
+            const TIMEOUT_MS = 15_000;
+            const startPromise = this.dashboardStore.start(null, emitter, appRoot);
+            const timeoutPromise = new Promise((_, reject) => {
+                setTimeout(() => reject(new Error(`Dashboard SQLite initialization timed out after ${TIMEOUT_MS / 1000}s`)), TIMEOUT_MS);
+            });
+            await Promise.race([startPromise, timeoutPromise]);
+            log.info('dashboard: SQLite store ready');
         }
         catch (err) {
             const msg = err?.message || '';
-            if (msg.includes('better-sqlite3') || msg.includes('Cannot find module')) {
-                console.warn('[server-stats] Dashboard requires better-sqlite3. Install it with:\n' +
-                    '  npm install better-sqlite3\n' +
-                    'Dashboard has been disabled for this session.');
-                this.dashboardStore = null;
-                return;
+            const code = err?.code || '';
+            const isMissingDep = msg.includes('better-sqlite3') ||
+                msg.includes('knex') ||
+                msg.includes('Cannot find module') ||
+                msg.includes('Cannot find package') ||
+                code === 'ERR_MODULE_NOT_FOUND' ||
+                code === 'MODULE_NOT_FOUND';
+            const isTimeout = msg.includes('timed out');
+            if (isMissingDep) {
+                log.block('Dashboard could not start — missing dependencies. Install with:', [
+                    '',
+                    bold('npm install knex better-sqlite3'),
+                    '',
+                    dim('Dashboard has been disabled for this session.'),
+                    dim('Everything else (stats bar, debug panel) works without it.'),
+                ]);
+            }
+            else if (isTimeout) {
+                log.block('Dashboard initialization timed out', [
+                    dim('SQLite setup took too long — this usually means a wrong native'),
+                    dim('binary was loaded (common with symlinked/file: dependencies).'),
+                    '',
+                    dim('Try running:'),
+                    `  ${bold('npm install knex better-sqlite3')}`,
+                    dim('in your app directory to ensure the correct copies are used.'),
+                    '',
+                    dim('Dashboard has been disabled for this session.'),
+                    dim('Everything else (stats bar, debug panel) works without it.'),
+                ]);
+            }
+            else {
+                log.warn(`Dashboard could not start: ${msg}\n` +
+                    `  ${dim('Dashboard has been disabled for this session.')}`);
+                if (err?.stack) {
+                    console.error(err.stack);
+                }
             }
-            throw err;
+            this.dashboardStore = null;
+            return;
         }
-        // Bind to container
-        ;
+        log.info('dashboard: binding to container...');
         this.app.container.singleton('dashboard.store', () => this.dashboardStore);
         // Set dashboard path in middleware for self-exclusion
         setDashboardPath(toolbarConfig.dashboardPath);
         // Create the controller — this makes the routes registered in boot() functional
+        log.info('dashboard: creating controller...');
         const DashboardControllerClass = (await import('../dashboard/dashboard_controller.js')).default;
-        this.dashboardController = new DashboardControllerClass(this.dashboardStore, this.debugStore, this.app);
+        this.dashboardController = new DashboardControllerClass(this.dashboardStore, this.app);
         // ── Log piping ────────────────────────────────────────────────
-        const logPath = this.app.makePath('logs', 'adonisjs.log');
-        this.dashboardLogStream = new LogStreamService(logPath, (entry) => {
-            this.dashboardStore?.recordLog(entry);
-        });
-        await this.dashboardLogStream.start();
+        // If the log collector is already hooked into Pino (zero-config mode),
+        // piggyback on it instead of creating a separate file poller.
+        log.info('dashboard: setting up log piping...');
+        const existingLogStream = getLogStreamService();
+        if (existingLogStream && !existingLogStream['logPath']) {
+            // Stream mode — add a listener for dashboard persistence
+            const origOnEntry = existingLogStream['onEntry'];
+            existingLogStream['onEntry'] = (entry) => {
+                origOnEntry?.(entry);
+                this.dashboardStore?.recordLog(entry);
+            };
+        }
+        else {
+            // File-based fallback
+            const logPath = this.app.makePath('logs', 'adonisjs.log');
+            this.dashboardLogStream = new LogStreamService(logPath, (entry) => {
+                this.dashboardStore?.recordLog(entry);
+            });
+            await this.dashboardLogStream.start();
+        }
         // ── Per-request data piping ────────────────────────────────────
         const debugStore = this.debugStore;
         const dashStore = this.dashboardStore;
         let lastQueryId = 0;
         let lastEventId = 0;
+        let warnedPersistOnce = false;
         setOnRequestComplete(({ method, url, statusCode, duration, trace }) => {
             if (!dashStore.isReady())
                 return;
@@ -372,14 +633,24 @@ export default class ServerStatsProvider {
             }
             // Persist asynchronously (fire-and-forget)
             dashStore
-                .persistRequest(method, url, statusCode, duration, newQueries, trace ?? null)
+                .persistRequest({
+                method,
+                url,
+                statusCode,
+                duration,
+                queries: newQueries,
+                trace: trace ?? null,
+            })
                 .then((requestId) => {
                 if (requestId !== null && newEvents.length > 0) {
                     return dashStore.recordEvents(requestId, newEvents);
                 }
             })
-                .catch(() => {
-                // Silently ignore persistence errors
+                .catch((err) => {
+                if (!warnedPersistOnce) {
+                    warnedPersistOnce = true;
+                    log.warn('failed to persist request data — ' + (err?.message || 'unknown error'));
+                }
             });
         });
         // ── Transmit streaming for real-time dashboard updates ────────
@@ -391,13 +662,24 @@ export default class ServerStatsProvider {
             // Transmit not installed — skip real-time updates
         }
         if (transmit) {
+            this.transmitAvailable = true;
             const dashChannel = 'server-stats/dashboard';
+            if (!this.transmitChannels.includes(dashChannel)) {
+                this.transmitChannels.push(dashChannel);
+            }
             this.dashboardBroadcastTimer = setInterval(async () => {
                 try {
                     if (!dashStore.isReady())
                         return;
                     const overview = await dashStore.getOverviewMetrics('1h');
-                    transmit.broadcast(dashChannel, overview);
+                    const diagnostics = {
+                        collectors: this.engine.getCollectorHealth(),
+                        buffers: this.debugStore.getBufferStats(),
+                    };
+                    transmit.broadcast(dashChannel, {
+                        ...overview,
+                        diagnostics,
+                    });
                 }
                 catch {
                     // Silently ignore
@@ -405,6 +687,80 @@ export default class ServerStatsProvider {
             }, 5_000);
         }
     }
+    /** Return diagnostics state for the Internals endpoint. */
+    getDiagnostics() {
+        const config = this.resolvedConfig;
+        const toolbarConfig = config?.devToolbar;
+        return {
+            timers: {
+                collectionInterval: {
+                    active: this.intervalId !== null,
+                    intervalMs: config?.intervalMs ?? 0,
+                },
+                dashboardBroadcast: {
+                    active: this.dashboardBroadcastTimer !== null,
+                    intervalMs: 5000,
+                },
+                debugBroadcast: {
+                    active: this.debugBroadcastTimer !== null,
+                    debounceMs: 200,
+                },
+                persistFlush: {
+                    active: this.flushTimer !== null,
+                    intervalMs: 30_000,
+                },
+                retentionCleanup: {
+                    active: this.dashboardStore?.isReady() ?? false,
+                    intervalMs: 60 * 60 * 1000,
+                },
+            },
+            transmit: {
+                available: this.transmitAvailable,
+                channels: this.transmitChannels,
+            },
+            integrations: {
+                prometheus: { active: this.prometheusActive },
+                pinoHook: {
+                    active: this.pinoHookActive,
+                    mode: this.pinoHookActive ? 'stream' : toolbarConfig?.enabled ? 'none' : 'none',
+                },
+                edgePlugin: { active: this.edgePluginActive },
+                cacheInspector: {
+                    available: this.resolvedCollectors.some((c) => c.name === 'redis'),
+                },
+                queueInspector: {
+                    available: this.resolvedCollectors.some((c) => c.name === 'queue'),
+                },
+            },
+            config: {
+                intervalMs: config?.intervalMs ?? 0,
+                transport: config?.transport ?? 'none',
+                channelName: config?.channelName ?? '',
+                endpoint: config?.endpoint ?? false,
+                skipInTest: config?.skipInTest !== false,
+                hasOnStatsCallback: typeof config?.onStats === 'function',
+                hasShouldShowCallback: typeof config?.shouldShow === 'function',
+            },
+            devToolbar: {
+                enabled: !!toolbarConfig?.enabled,
+                maxQueries: toolbarConfig?.maxQueries ?? 500,
+                maxEvents: toolbarConfig?.maxEvents ?? 200,
+                maxEmails: toolbarConfig?.maxEmails ?? 100,
+                maxTraces: toolbarConfig?.maxTraces ?? 200,
+                slowQueryThresholdMs: toolbarConfig?.slowQueryThresholdMs ?? 100,
+                tracing: toolbarConfig?.tracing ?? false,
+                dashboard: toolbarConfig?.dashboard ?? false,
+                dashboardPath: toolbarConfig?.dashboardPath ?? '/__stats',
+                debugEndpoint: toolbarConfig?.debugEndpoint ?? '/admin/api/debug',
+                retentionDays: toolbarConfig?.retentionDays ?? 7,
+                dbPath: toolbarConfig?.dbPath ?? '.adonisjs/server-stats/dashboard.sqlite3',
+                persistDebugData: toolbarConfig?.persistDebugData ?? false,
+                renderer: toolbarConfig?.renderer ?? 'preact',
+                excludeFromTracing: toolbarConfig?.excludeFromTracing ?? [],
+                customPaneCount: toolbarConfig?.panes?.length ?? 0,
+            },
+        };
+    }
     async shutdown() {
         if (this.intervalId) {
             clearInterval(this.intervalId);
@@ -427,8 +783,8 @@ export default class ServerStatsProvider {
             try {
                 await this.debugStore.saveToDisk(this.persistPath);
             }
-            catch {
-                // Silently ignore save errors during shutdown
+            catch (err) {
+                log.warn('could not save debug data on shutdown — ' + err?.message);
             }
         }
         // Clean up dashboard resources