adonisjs-server-stats 1.15.0 → 1.16.1

package/dist/src/provider/dashboard_init.js

@@ -42,7 +42,11 @@ export async function initDashboardStore(opts) {
     setDashboardPath(tc.dashboardPath);
     const DCC = (await import('../dashboard/dashboard_controller.js')).default;
     const dashboardController = new DCC(dashboardStore, app);
-    const dashboardLogStream = pipeDashLogs(pinoHookActive, dashboardStore, app.makePath.bind(app));
+    // Log capture is a separate opt-in: it is high-volume and log lines routinely
+    // carry request payloads. With it off the dashboard's other panes still work.
+    const dashboardLogStream = tc.capture?.logs !== false
+        ? pipeDashLogs(pinoHookActive, dashboardStore, app.makePath.bind(app))
+        : null;
     pipeDashRequests(debugStore, dashboardStore);
     const dashboardBroadcastTimer = await setupDashBroadcast({
         container,
@@ -114,18 +118,27 @@ function pipeDashRequests(debugStore, dashboardStore) {
     }
     dashRequestPipeInstalled = true;
     let lastQueryId = 0;
+    let lastEventId = 0;
     setOnRequestComplete(({ method, url, statusCode, duration, trace, httpRequestId }) => {
         if (!dashboardStore.isReady())
             return;
         const q = debugStore.queries.getQueriesSince(lastQueryId);
         if (q.length > 0)
             lastQueryId = q[q.length - 1].id;
+        // Events are collected globally rather than per-request, so — exactly like
+        // queries above — anything emitted outside a request is attributed to
+        // whichever request finishes next. Imprecise, but it keeps events linked to
+        // a request row, which is what retention prunes on.
+        const events = debugStore.capture.events ? debugStore.events.getEventsSince(lastEventId) : [];
+        if (events.length > 0)
+            lastEventId = events[events.length - 1].id;
         dashboardStore.persistRequest({
             method,
             url,
             statusCode,
             duration,
             queries: q,
+            events,
             trace: trace ?? null,
             httpRequestId: httpRequestId ?? null,
         });

package/dist/src/provider/dashboard_setup.d.ts

@@ -2,6 +2,7 @@
  * Pure helper functions for dashboard setup and configuration.
  */
 import type { DevToolbarConfig } from '../debug/types.js';
+import type { ProductionConfig } from '../types.js';
 /**
  * Classify a dashboard start() error into a category.
  */
@@ -17,9 +18,17 @@ export declare function buildExcludedPrefixes(toolbarConfig: {
     debugEndpoint?: string;
     excludeFromTracing?: string[];
 }, statsEndpoint: string | false): string[];
+/** Environment context needed to resolve production-sensitive defaults. */
+export interface ProductionContext {
+    inProduction: boolean;
+    production?: ProductionConfig;
+}
 /**
  * Resolve a partial DevToolbarConfig by filling in all defaults.
+ *
+ * Pass `ctx` to apply production-sensitive defaults (capture off, shorter
+ * retention). Omitting it resolves as a non-production environment.
  */
 export declare function resolveToolbarConfig(partial: Partial<DevToolbarConfig> & {
     enabled: boolean;
-}): DevToolbarConfig;
+}, ctx?: ProductionContext): DevToolbarConfig;

package/dist/src/provider/dashboard_setup.js

@@ -73,13 +73,58 @@ function stripUndefined(obj) {
     }
     return result;
 }
+/** Retention default when running in production — shorter than the usual 7 days. */
+const PRODUCTION_RETENTION_DAYS = 3;
 /**
- * Resolve a partial DevToolbarConfig by filling in all defaults.
+ * Resolve which capture subsystems subscribe.
+ *
+ * Outside production everything captures, as it always has. In production every
+ * subsystem is off until asked for by name, because each one is the expensive,
+ * secret-adjacent half of this package: query bindings, mail bodies, log lines.
+ *
+ * `tracing: false` still wins over `capture.traces` — it is the pre-existing
+ * documented kill switch and must not be quietly re-enabled.
  */
-export function resolveToolbarConfig(partial) {
+function resolveCapture(ctx, tracing) {
+    const inProduction = ctx?.inProduction === true;
+    const requested = (inProduction ? ctx?.production?.capture : undefined) ?? {};
+    const isOn = (key) => requested[key] ?? !inProduction;
     return {
+        queries: isOn('queries'),
+        events: isOn('events'),
+        emails: isOn('emails'),
+        traces: tracing && isOn('traces'),
+        logs: isOn('logs'),
+    };
+}
+/**
+ * Resolve retention, preferring an explicit value from any source over the
+ * production default. Order: `production.retentionDays`, then whatever
+ * `dashboard`/`advanced` set, then 3 days in production, then 7.
+ */
+function resolveRetentionDays(ctx, explicit) {
+    const fromProduction = ctx?.inProduction ? ctx.production?.retentionDays : undefined;
+    if (fromProduction !== undefined)
+        return fromProduction;
+    if (explicit !== undefined)
+        return explicit;
+    return ctx?.inProduction ? PRODUCTION_RETENTION_DAYS : TOOLBAR_DEFAULTS.retentionDays;
+}
+/**
+ * Resolve a partial DevToolbarConfig by filling in all defaults.
+ *
+ * Pass `ctx` to apply production-sensitive defaults (capture off, shorter
+ * retention). Omitting it resolves as a non-production environment.
+ */
+export function resolveToolbarConfig(partial, ctx) {
+    const merged = {
         ...TOOLBAR_DEFAULTS,
         ...stripUndefined(partial),
         enabled: partial.enabled,
     };
+    return {
+        ...merged,
+        retentionDays: resolveRetentionDays(ctx, partial.retentionDays),
+        capture: resolveCapture(ctx, merged.tracing),
+    };
 }

package/dist/src/provider/server_stats_provider.d.ts

@@ -43,6 +43,13 @@ export default class ServerStatsProvider {
     whenReady(): Promise<void>;
     boot(): Promise<void>;
     private initBoot;
+    /**
+     * Whether this package should do anything in the current environment.
+     *
+     * Everything is on outside production. In production nothing is registered or
+     * built unless `production.enabled` opts in.
+     */
+    private isEnabledHere;
     private registerRoutes;
     ready(): Promise<void>;
     private initStats;

package/dist/src/provider/server_stats_provider.js

@@ -2,7 +2,7 @@ import { StatsEngine } from '../engine/stats_engine.js';
 import { setShouldShow, setExcludedPrefixes } from '../middleware/request_tracking_middleware.js';
 import { registerAllRoutes } from '../routes/register_routes.js';
 import { log, dim, setVerbose } from '../utils/logger.js';
-import { deriveEndpointPaths, computeDashboardPath, collectRegisteredPaths, warnAboutAuthMiddleware, warnAboutSessionMiddleware, warnAboutDomainWithToolbar, } from './boot_helpers.js';
+import { deriveEndpointPaths, computeDashboardPath, collectRegisteredPaths, warnAboutAuthMiddleware, warnAboutSessionMiddleware, warnAboutDomainWithToolbar, announceProductionMode, } from './boot_helpers.js';
 import { resolveToolbarConfig, buildExcludedPrefixes } from './dashboard_setup.js';
 import { buildDiagnostics } from './diagnostics.js';
 import { hookPinoToLogStream, setupLogStreamBroadcast, setupStatsIntervalHelper, checkDashboardDepsHelper, registerEdgePluginHelper, setupNonWebBridgeHelper, setupDevToolbarCore, applyToolbarResult, } from './provider_helpers_extra.js';
@@ -73,16 +73,29 @@ export default class ServerStatsProvider {
         if (config.shouldShow)
             setShouldShow(config.shouldShow);
         await this.registerRoutes(config);
-        this.edgePluginActive = await registerEdgePluginHelper(this.app, config);
+        // Only register the Edge tag when the routes it polls actually exist —
+        // otherwise the bar renders in production and 404s on every tick.
+        this.edgePluginActive = this.isEnabledHere(config)
+            ? await registerEdgePluginHelper(this.app, config)
+            : false;
+    }
+    /**
+     * Whether this package should do anything in the current environment.
+     *
+     * Everything is on outside production. In production nothing is registered or
+     * built unless `production.enabled` opts in.
+     */
+    isEnabledHere(config) {
+        return !this.app.inProduction || config.production?.enabled === true;
     }
     async registerRoutes(config) {
         const router = await this.resolve('router');
-        if (!router || this.app.inProduction)
+        if (!router || !this.isEnabledHere(config))
             return;
         this.dashboardDepsAvailable = await checkDashboardDepsHelper(config, this.app);
         const { statsEndpoint, debugEndpoint } = deriveEndpointPaths(config.endpoint, config.devToolbar);
         const dashboardPath = computeDashboardPath(config.devToolbar, this.dashboardDepsAvailable);
-        registerAllRoutes({
+        const registered = registerAllRoutes({
             router: router,
             getApiController: () => this.apiController,
             getStatsController: () => this.statsController,
@@ -95,16 +108,19 @@ export default class ServerStatsProvider {
             dashboardPath,
             shouldShow: config.shouldShow,
             unsafeAllowNoAuth: config.unsafeAllowNoAuth,
+            inProduction: this.app.inProduction,
             whenReady: () => this.whenReady(),
             domain: config.domain,
         });
         const paths = collectRegisteredPaths(statsEndpoint, debugEndpoint, dashboardPath, config.domain);
-        if (paths.length === 0)
+        if (!registered || paths.length === 0)
             return;
         log.list('routes auto-registered (no manual setup needed):', paths);
         warnAboutAuthMiddleware(config, this.app.makePath.bind(this.app));
         warnAboutSessionMiddleware(this.app.makePath.bind(this.app));
         warnAboutDomainWithToolbar(config);
+        if (this.app.inProduction)
+            announceProductionMode(config, paths);
     }
     async ready() {
         const config = this.app.config.get('server_stats');
@@ -132,7 +148,7 @@ export default class ServerStatsProvider {
         this.pinoHookActive = hookPinoToLogStream(await this.resolve('logger'));
         const SC = (await import('../controller/server_stats_controller.js')).default;
         this.statsController = new SC(this.engine);
-        if (config.devToolbar?.enabled && !this.app.inProduction) {
+        if (config.devToolbar?.enabled && this.isEnabledHere(config)) {
             this.checkLucidDebugFlag();
             await this.setupDevToolbar(config);
         }
@@ -158,7 +174,7 @@ export default class ServerStatsProvider {
         return r.collectors;
     }
     async setupDevToolbar(config) {
-        const tc = resolveToolbarConfig({ enabled: true, ...config.devToolbar });
+        const tc = resolveToolbarConfig({ enabled: true, ...config.devToolbar }, { inProduction: this.app.inProduction, production: config.production });
         try {
             const result = await setupDevToolbarCore({
                 tc,

package/dist/src/provider/toolbar_setup.js

@@ -20,7 +20,11 @@ export async function setupDevToolbarCore(opts) {
     await debugStore.start(em, await resolve('router'));
     const emailBridgeRedis = await setupBridgeInternal(em, debugStore, app);
     const debugController = await createDebugController(debugStore, config, getDiagnostics, app);
-    if (debugStore.traces)
+    // Also gated on capture: installing the collector is what makes the middleware
+    // wrap every request in AsyncLocalStorage and write a trace row per request.
+    // Gating only the emitter subscription would leave that cost in place and
+    // persist empty traces.
+    if (debugStore.capture.traces && debugStore.traces)
         setTraceCollector(debugStore.traces);
     const flushTimer = persistPath ? createFlushTimer(debugStore, persistPath) : null;
     const broadcast = await setupDebugBroadcastInternal(debugStore, resolve);

package/dist/src/routes/access_middleware.d.ts

@@ -1,8 +1,14 @@
+import type { AccessGuard } from '../types.js';
 import type { HttpContext } from '@adonisjs/core/http';
 /**
  * Create a middleware function that gates access using the shouldShow callback.
  * Returns 403 if the callback returns false.
  *
+ * The guard is awaited, so an async callback (the usual shape when it has to
+ * consult `ctx.auth` or the database) is resolved before the decision is made.
+ * Returning the promise unawaited would make every async guard pass, since a
+ * pending promise is truthy.
+ *
  * Shared by stats, debug, and dashboard route registrars.
  */
-export declare function createAccessMiddleware(shouldShow: (ctx: HttpContext) => boolean): (ctx: HttpContext, next: () => Promise<void>) => Promise<void>;
+export declare function createAccessMiddleware(shouldShow: AccessGuard): (ctx: HttpContext, next: () => Promise<void>) => Promise<void>;

package/dist/src/routes/access_middleware.js

@@ -4,12 +4,17 @@ let warnedShouldShow = false;
  * Create a middleware function that gates access using the shouldShow callback.
  * Returns 403 if the callback returns false.
  *
+ * The guard is awaited, so an async callback (the usual shape when it has to
+ * consult `ctx.auth` or the database) is resolved before the decision is made.
+ * Returning the promise unawaited would make every async guard pass, since a
+ * pending promise is truthy.
+ *
  * Shared by stats, debug, and dashboard route registrars.
  */
 export function createAccessMiddleware(shouldShow) {
     return async (ctx, next) => {
         try {
-            if (!shouldShow(ctx)) {
+            if (!(await shouldShow(ctx))) {
                 return ctx.response.forbidden({ error: 'Access denied' });
             }
         }

package/dist/src/routes/register_routes.d.ts

@@ -3,8 +3,8 @@ import type DebugController from '../controller/debug_controller.js';
 import type { DebugStore } from '../debug/debug_store.js';
 import type ServerStatsController from '../controller/server_stats_controller.js';
 import type DashboardController from '../dashboard/dashboard_controller.js';
+import type { AccessGuard } from '../types.js';
 import type { AdonisRouter } from './router_types.js';
-import type { HttpContext } from '@adonisjs/core/http';
 import type { ApplicationService } from '@adonisjs/core/types';
 /**
  * Options for the unified route registration function.
@@ -20,7 +20,7 @@ export interface RegisterRoutesOptions {
     statsEndpoint?: string | false;
     debugEndpoint?: string;
     dashboardPath?: string;
-    shouldShow?: (ctx: HttpContext) => boolean;
+    shouldShow?: AccessGuard;
     /**
      * Escape hatch to register the sensitive dashboard/debug/stats routes WITHOUT
      * any access guard when no `shouldShow` callback is provided. Off by default —
@@ -29,6 +29,12 @@ export interface RegisterRoutesOptions {
      * email bodies, and SQL) to anyone who can reach it. Local dev only.
      */
     unsafeAllowNoAuth?: boolean;
+    /**
+     * Whether the app is running in production. When true, `unsafeAllowNoAuth` is
+     * ignored — an unauthenticated dashboard in production is never correct, so
+     * the only way in is a real `shouldShow` guard.
+     */
+    inProduction?: boolean;
     /** Optional promise that resolves when controllers are initialized. */
     whenReady?: () => Promise<void>;
     /**
@@ -39,5 +45,9 @@ export interface RegisterRoutesOptions {
 }
 /**
  * Register all server-stats routes in a single call.
+ *
+ * Returns whether the routes were actually registered — false means the
+ * fail-closed guard check rejected the configuration, which callers need to
+ * know before announcing that anything is reachable.
  */
-export declare function registerAllRoutes(options: RegisterRoutesOptions): void;
+export declare function registerAllRoutes(options: RegisterRoutesOptions): boolean;

package/dist/src/routes/register_routes.js

@@ -8,16 +8,29 @@ import { log } from '../utils/logger.js';
 let _warnedNoAuth = false;
 /**
  * Register all server-stats routes in a single call.
+ *
+ * Returns whether the routes were actually registered — false means the
+ * fail-closed guard check rejected the configuration, which callers need to
+ * know before announcing that anything is reachable.
  */
 export function registerAllRoutes(options) {
     // Fail closed: without an access guard (`shouldShow`) the sensitive routes must
     // not be registered unless the caller explicitly opts in via `unsafeAllowNoAuth`.
     if (!options.shouldShow) {
+        // In production the escape hatch does not apply — there is no legitimate
+        // reason to serve secrets, email bodies, and SQL to unauthenticated callers
+        // on a production host, so the guard is the only way through.
+        if (options.inProduction) {
+            log.warn('server-stats: production mode is enabled but no `authorize`/`shouldShow` guard is ' +
+                'configured — sensitive routes (dashboard, debug API, stats) will NOT be registered. ' +
+                '`unsafeAllowNoAuth` is ignored in production. Provide an authorize callback.');
+            return false;
+        }
         if (!options.unsafeAllowNoAuth) {
             log.warn('server-stats: no `authorize`/`shouldShow` guard configured — sensitive routes ' +
                 '(dashboard, debug API, stats) will NOT be registered. Provide an authorize callback, ' +
                 'or set `unsafeAllowNoAuth: true` to expose them without auth (local dev only).');
-            return;
+            return false;
         }
         if (!_warnedNoAuth) {
             _warnedNoAuth = true;
@@ -63,4 +76,5 @@ export function registerAllRoutes(options) {
             domain: options.domain,
         });
     }
+    return true;
 }

package/dist/src/stubs/config.stub

@@ -19,4 +19,12 @@ export default defineConfig({
 
   // Log detailed initialization steps (SQLite, migrations, routes, etc.)
   // verbose: true,
+
+  // Nothing is registered in production unless you opt in here. Requires an
+  // `authorize` guard, and data capture stays off until you name a subsystem.
+  // production: {
+  //   enabled: true,
+  //   capture: { queries: true },
+  //   retentionDays: 3,
+  // },
 })

package/dist/src/types.d.ts

@@ -435,6 +435,94 @@ export interface DashboardConfig {
      */
     retentionDays?: number;
 }
+/**
+ * Access-control callback signature.
+ *
+ * May be sync or async — the route guard awaits it. An async guard is the usual
+ * shape once the check has to consult `ctx.auth` or the database.
+ *
+ * One caveat: the `@serverStats()` Edge tag evaluates the guard synchronously
+ * while rendering the template, so with an **async** guard the toolbar hides
+ * itself rather than risk showing when it shouldn't. The HTTP routes await it
+ * properly either way — only the cosmetic bar is affected.
+ */
+export type AccessGuard = (ctx: import('@adonisjs/core/http').HttpContext) => boolean | Promise<boolean>;
+/**
+ * Which capture subsystems are active.
+ *
+ * Each one hooks a global: queries and events subscribe to the Lucid/app
+ * emitter, emails subscribe to the mail events, traces wrap every request in
+ * `AsyncLocalStorage`. Turning one off means its collector is never subscribed,
+ * so it costs nothing — its dashboard pane simply stays empty.
+ *
+ * Outside production every field defaults to `true`. In production every field
+ * defaults to **`false`** and must be opted into individually.
+ */
+export interface CaptureConfig {
+    /** SQL text, bindings, and timings for every query. */
+    queries?: boolean;
+    /** Application events (in-memory only — never persisted to SQLite). */
+    events?: boolean;
+    /** Sent mail, including subject and body. */
+    emails?: boolean;
+    /** Per-request spans and the request timeline. */
+    traces?: boolean;
+    /** Log lines written into the dashboard's SQLite store. */
+    logs?: boolean;
+}
+/**
+ * Opt in to running the dashboard in production.
+ *
+ * By default this package registers **no routes** when `NODE_ENV=production`
+ * and never builds the debug or dashboard stores. Setting `enabled: true` lifts
+ * that, but only with an {@link ServerStatsConfig.authorize} guard in place —
+ * `unsafeAllowNoAuth` is ignored in production.
+ *
+ * Data capture stays **off** unless you ask for it. Without any `capture`
+ * flags you still get the request list, the overview, and the charts (those
+ * come from request rows and 1-minute metric buckets), at a small fraction of
+ * the write volume of a full dev-mode capture.
+ *
+ * @example
+ * ```ts
+ * export default defineConfig({
+ *   authorize: async (ctx) => (await ctx.auth.check()) && ctx.auth.user?.isAdmin === true,
+ *   dashboard: true,
+ *   production: {
+ *     enabled: true,
+ *     capture: { queries: true },
+ *     retentionDays: 3,
+ *   },
+ * })
+ * ```
+ */
+export interface ProductionConfig {
+    /**
+     * Register routes and build the dashboard when `NODE_ENV=production`.
+     *
+     * Requires an `authorize` guard — without one the routes are still not
+     * registered, and a warning explains why.
+     *
+     * @default false
+     */
+    enabled?: boolean;
+    /**
+     * Which capture subsystems to switch on. Every field defaults to `false` in
+     * production, so capture is opt-in one subsystem at a time.
+     *
+     * @see {@link CaptureConfig}
+     */
+    capture?: CaptureConfig;
+    /**
+     * How many days of history to keep in SQLite, overriding the usual default
+     * of 7. Retention deletes rows hourly but never runs `VACUUM`, so the
+     * database file reuses pages rather than shrinking — watch actual size via
+     * the dashboard's storage panel.
+     *
+     * @default 3
+     */
+    retentionDays?: number;
+}
 /**
  * Advanced options that most users never need to touch.
  *
@@ -699,7 +787,7 @@ export interface ServerStatsConfig {
      *
      * @deprecated Use {@link authorize} instead. Will be removed in the next major version.
      */
-    shouldShow?: (ctx: import('@adonisjs/core/http').HttpContext) => boolean;
+    shouldShow?: AccessGuard;
     /**
      * How often (in **milliseconds**) to run all collectors and
      * broadcast updated stats.
@@ -750,7 +838,7 @@ export interface ServerStatsConfig {
      * authorize: () => process.env.NODE_ENV === 'development'
      * ```
      */
-    authorize?: (ctx: import('@adonisjs/core/http').HttpContext) => boolean;
+    authorize?: AccessGuard;
     /**
      * Register the sensitive dashboard/debug/stats routes WITHOUT any access
      * guard when no {@link authorize} callback is provided.
@@ -833,6 +921,21 @@ export interface ServerStatsConfig {
      * ```
      */
     domain?: string;
+    /**
+     * Opt in to running in production, where this package otherwise registers
+     * nothing at all.
+     *
+     * Requires an {@link authorize} guard, and leaves data capture off unless you
+     * enable it per subsystem.
+     *
+     * @see {@link ProductionConfig}
+     *
+     * @example
+     * ```ts
+     * production: { enabled: true, capture: { queries: true } }
+     * ```
+     */
+    production?: ProductionConfig;
     /**
      * Advanced options for fine-tuning internal behavior.
      *
@@ -878,7 +981,7 @@ export interface ResolvedServerStatsConfig {
     /** Optional dev toolbar configuration. */
     devToolbar?: DevToolbarOptions;
     /** Optional access-control callback. */
-    shouldShow?: (ctx: import('@adonisjs/core/http').HttpContext) => boolean;
+    shouldShow?: AccessGuard;
     /** Collection interval in milliseconds (new name for {@link intervalMs}). */
     pollInterval?: number;
     /** Whether real-time (SSE) broadcasting is enabled (new name for {@link transport}). */
@@ -886,7 +989,7 @@ export interface ResolvedServerStatsConfig {
     /** HTTP endpoint path or `false` to disable (new name for {@link endpoint}). */
     statsEndpoint?: string | false;
     /** Access-control callback (new name for {@link shouldShow}). */
-    authorize?: (ctx: import('@adonisjs/core/http').HttpContext) => boolean;
+    authorize?: AccessGuard;
     /**
      * Escape hatch to register sensitive routes without an access guard.
      * Exposes the dashboard without auth — local development only.
@@ -902,4 +1005,6 @@ export interface ResolvedServerStatsConfig {
     verbose: boolean;
     /** Optional domain restriction for all routes. */
     domain?: string;
+    /** Opt-in production behavior. Absent means this package is inert in production. */
+    production?: ProductionConfig;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "adonisjs-server-stats",
-  "version": "1.15.0",
+  "version": "1.16.1",
   "description": "Real-time server monitoring for AdonisJS v6 applications",
   "keywords": [
     "adonisjs",