adonisjs-server-stats 1.15.0 → 1.16.0

package/README.md

@@ -182,6 +182,7 @@ All fields are optional. `defineConfig({})` works with zero configuration.
 | `authorize`     | `(ctx) => boolean`                | --                          | Per-request visibility guard                                     |
 | `unsafeAllowNoAuth` | `boolean`                     | `false`                     | Register the dashboard/debug/stats routes even with **no** `authorize` guard. Off by default (routes fail closed). Local dev only — exposes secrets, email bodies, and SQL. |
 | `domain`        | `string`                          | --                          | Restrict every route to one host, e.g. `'admin.example.com'`. See [Custom domain](#custom-domain) |
+| `production`    | `ProductionConfig`                | --                          | Opt in to running in production. Off by default -- see [Production](#production) |
 | `onStats`       | `(stats) => void`                 | --                          | Callback after each collection tick                              |
 | `toolbar`       | `boolean \| ToolbarConfig`        | --                          | `true` to enable with defaults, or pass a `ToolbarConfig` object |
 | `dashboard`     | `boolean \| DashboardConfig`      | --                          | `true` to enable at `/__stats`, or pass a `DashboardConfig`      |
@@ -205,6 +206,16 @@ All fields are optional. `defineConfig({})` works with zero configuration.
 | `path`          | `string` | `'/__stats'` | URL path for the dashboard page        |
 | `retentionDays` | `number` | `7`          | Days to keep historical data in SQLite |
 
+### `ProductionConfig`
+
+| Option          | Type            | Default | Description                                                            |
+| --------------- | --------------- | ------- | ---------------------------------------------------------------------- |
+| `enabled`       | `boolean`       | `false` | Register routes and build the dashboard when `NODE_ENV=production`      |
+| `capture`       | `CaptureConfig` | all off | Which capture subsystems to switch on -- opt in one at a time           |
+| `retentionDays` | `number`        | `3`     | SQLite history to keep in production (the usual default is 7)           |
+
+`CaptureConfig` fields, each `boolean` and each defaulting to `false` in production: `queries`, `events`, `emails`, `traces`, `logs`.
+
 ### `AdvancedConfig`
 
 | Option          | Type                | Default                                      | Description                                     |
@@ -384,6 +395,81 @@ export default defineConfig({
 
 ---
 
+## Production
+
+By default this package does **nothing** when `NODE_ENV=production` -- no routes are registered and neither the debug nor the dashboard store is built. The metrics engine still runs, so `onStats`, Prometheus, and Transmit broadcasting keep working; there is simply no HTTP surface.
+
+Set `production.enabled` to lift that:
+
+```ts
+export default defineConfig({
+  authorize: async (ctx) => (await ctx.auth.check()) && ctx.auth.user?.isAdmin === true,
+  dashboard: true,
+
+  production: {
+    enabled: true,
+    capture: { queries: true }, // everything else stays off
+    retentionDays: 3,
+  },
+})
+```
+
+### An `authorize` guard is mandatory
+
+`unsafeAllowNoAuth` is **ignored** in production. Without a guard the routes are not registered and a warning explains why -- an unauthenticated dashboard on a production host is never correct.
+
+When production mode is active you get an unmissable startup banner, so nobody enables this and forgets:
+
+```
+[ server-stats ] DASHBOARD IS LIVE IN PRODUCTION
+  reachable at:  /admin/api/server-stats, /admin/api/debug/*, /__stats/*
+  guard:         authorize() configured
+  capturing:     queries
+  data at:       .adonisjs/server-stats/dashboard.sqlite3 (retention: 3 days)
+```
+
+### Capture is off unless you ask for it
+
+Each capture subsystem hooks something global and stores something sensitive, so in production every one starts **off** and is enabled by name:
+
+| `capture` flag | What it records                     | Why it's off by default                          |
+| -------------- | ----------------------------------- | ------------------------------------------------ |
+| `queries`      | SQL text, bindings, timings         | Bindings can hold values you would not log       |
+| `events`       | Application events (memory only)    | Patches the emitter's `emit()` process-wide      |
+| `emails`       | Sent mail incl. subject and body    | Highest-sensitivity payload in the package       |
+| `traces`       | Per-request spans                   | Wraps every request in `AsyncLocalStorage`       |
+| `logs`         | Log lines into SQLite               | Highest write volume, and logs quote payloads    |
+
+**With no capture flags at all you still get the useful core:** the request list, the overview, and the charts. Those come from request rows and 1-minute metric buckets, at a small fraction of full dev-mode write volume. Turn capture on when you are actually debugging something.
+
+A disabled subsystem is never subscribed, so it costs nothing -- its dashboard pane simply stays empty.
+
+> [!NOTE]
+> `toolbar: { tracing: false }` still overrides `capture.traces`. It is the older kill switch and keeps winning.
+
+### Disk
+
+Retention prunes rows older than `retentionDays` on boot and hourly. It does **not** run `VACUUM`, so the `.sqlite3` file reuses freed pages rather than shrinking -- expect the file to plateau, not shrink. Watch real numbers in the dashboard's storage panel (`GET {dashboardPath}/api/storage`), which reports file size, WAL size, and per-table row counts.
+
+There is no sampling and no hard size cap. On a high-traffic app, enable capture deliberately and keep `retentionDays` short.
+
+### Async guards and the toolbar
+
+An `authorize` callback may be sync or async -- the route guard awaits it, so `async (ctx) => { await ctx.auth.authenticate(); ... }` is safe.
+
+> [!WARNING]
+> The `@serverStats()` Edge toolbar evaluates the guard **synchronously** while rendering, so it cannot await. With an async guard the stats bar hides itself rather than risk showing when it shouldn't, and logs a warning once. The HTTP routes are guarded correctly either way -- only the cosmetic bar is affected. Use a synchronous guard if you want the bar in production.
+
+### What this does not give you
+
+Worth knowing before you expose it, even behind an admin guard:
+
+- **One guard, no tiers.** Anyone who passes `authorize` can also `DELETE /api/cache/:key` and `POST /api/jobs/:id/retry`. Scope cache access with `SERVER_STATS_CACHE_KEY_PREFIX` -- unset means unrestricted.
+- **No audit log and no rate limiting** on those mutating endpoints.
+- **SQL bindings are truncated at 256 characters but not redacted by key name.** A short secret passed as a bound parameter is stored as-is. Config and env values *are* redacted; query bindings are not.
+
+---
+
 ## Auto-Registered Routes
 
 All API routes are registered automatically by the package during `boot()` -- no manual controllers or route definitions needed. Each route group is gated by the `authorize` callback if configured.
@@ -466,7 +552,7 @@ Pass a bare host. A protocol, path, or port (`https://admin.example.com`, `admin
 
 > **The toolbar follows the domain.** The `@serverStats()` Edge tag and the React/Vue components request **relative** URLs, so they only work on pages served from the configured domain. Render the toolbar on `example.com` while `domain` points at `admin.example.com` and the bar will sit empty -- its polls 404 against the wrong host. Either serve the toolbar from the same domain, or leave `domain` unset and rely on `authorize` alone.
 
-> **Reminder:** routes are never registered in production regardless of this setting (`app.inProduction` short-circuits registration), so `domain` applies to your dev and staging environments.
+> **Reminder:** routes are not registered in production unless you opt in via [`production.enabled`](#production). Without that, `domain` applies to your dev and staging environments only.
 
 ### Global middleware note
 
@@ -653,7 +739,7 @@ Found a bug? Have feedback? [Open an issue](https://github.com/simulieren/adonis
 
 ## Dev Toolbar
 
-Adds a debug panel with SQL query inspection, event tracking, email capture with HTML preview, route table, live logs, and per-request tracing. Only active in non-production environments.
+Adds a debug panel with SQL query inspection, event tracking, email capture with HTML preview, route table, live logs, and per-request tracing. Active in non-production environments by default; see [Production](#production) to opt in there.
 
 ```ts
 export default defineConfig({

package/dist/core/debug/types.d.ts

@@ -288,6 +288,20 @@ export interface DevToolbarConfig {
     dbPath: string;
     /** Base path for the debug toolbar API endpoints. */
     debugEndpoint: string;
+    /**
+     * Which capture subsystems are subscribed. Fully resolved — every field is
+     * present. All true outside production; all false in production unless the
+     * user opted in via `production.capture`.
+     */
+    capture: ResolvedCapture;
+}
+/** Fully-resolved capture flags. See {@link CaptureConfig} for the user-facing shape. */
+export interface ResolvedCapture {
+    queries: boolean;
+    events: boolean;
+    emails: boolean;
+    traces: boolean;
+    logs: boolean;
 }
 /**
  * Color names available for the `badge` column format.

package/dist/core/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/dist/src/dashboard/dashboard_controller.d.ts

@@ -26,6 +26,13 @@ export default class DashboardController {
     createSavedFilter(ctx: HttpContext): Promise<void>;
     deleteSavedFilter(ctx: HttpContext): Promise<void>;
     private withDb;
+    /**
+     * Re-check the access guard for the dashboard page itself.
+     *
+     * Awaited: an async guard would otherwise return a truthy promise and let
+     * everyone through. The route middleware already applies the same guard, so
+     * this is defense in depth for the HTML page.
+     */
     private checkAccess;
     private getDashboardPath;
 }

package/dist/src/dashboard/dashboard_controller.js

@@ -23,7 +23,7 @@ export default class DashboardController {
         this.pageAssets = new DashboardPageAssets();
     }
     async page(ctx) {
-        if (!this.checkAccess(ctx))
+        if (!(await this.checkAccess(ctx)))
             return ctx.response.forbidden({ error: 'Access denied' });
         const config = this.app.config.get('server_stats');
         const tc = config?.devToolbar ?? {};
@@ -163,12 +163,19 @@ export default class DashboardController {
             return response.json(emptyValue);
         }
     }
-    checkAccess(ctx) {
+    /**
+     * Re-check the access guard for the dashboard page itself.
+     *
+     * Awaited: an async guard would otherwise return a truthy promise and let
+     * everyone through. The route middleware already applies the same guard, so
+     * this is defense in depth for the HTML page.
+     */
+    async checkAccess(ctx) {
         const config = this.app.config.get('server_stats');
         if (!config?.shouldShow)
             return true;
         try {
-            return config.shouldShow(ctx);
+            return await config.shouldShow(ctx);
         }
         catch {
             return false;

package/dist/src/debug/debug_store.d.ts

@@ -3,7 +3,7 @@ import { EventCollector } from './event_collector.js';
 import { QueryCollector } from './query_collector.js';
 import { RouteInspector } from './route_inspector.js';
 import { TraceCollector } from './trace_collector.js';
-import type { DevToolbarConfig } from './types.js';
+import type { DevToolbarConfig, ResolvedCapture } from './types.js';
 /**
  * Singleton store holding all debug data collectors.
  * Bound to the AdonisJS container as `debug.store`.
@@ -14,6 +14,8 @@ export declare class DebugStore {
     readonly emails: EmailCollector;
     readonly routes: RouteInspector;
     readonly traces: TraceCollector | null;
+    /** Which collectors are allowed to subscribe in {@link start}. */
+    readonly capture: ResolvedCapture;
     constructor(config: DevToolbarConfig);
     /**
      * Register a callback that fires whenever any collector records a new item.
@@ -39,6 +41,18 @@ export declare class DebugStore {
             max: number;
         };
     };
+    /**
+     * Subscribe the enabled collectors.
+     *
+     * A disabled collector is left constructed but never subscribed, so its
+     * dashboard pane renders empty instead of erroring, and it costs nothing at
+     * runtime. This also keeps two process-wide side effects off in production:
+     * the event collector patches the emitter's `emit()`, and the trace collector
+     * patches `console.warn`.
+     *
+     * Route inspection is not gated — it reads the router table once at boot and
+     * captures no request data.
+     */
     start(emitter: unknown, router: unknown): Promise<void>;
     stop(): void;
     /** Serialize all collector data to a JSON file (atomic write). */

package/dist/src/debug/debug_store.js

@@ -48,12 +48,24 @@ export class DebugStore {
     emails;
     routes;
     traces;
+    /** Which collectors are allowed to subscribe in {@link start}. */
+    capture;
     constructor(config) {
         this.queries = new QueryCollector(config.maxQueries, config.slowQueryThresholdMs);
         this.events = new EventCollector(config.maxEvents);
         this.emails = new EmailCollector(config.maxEmails);
         this.routes = new RouteInspector();
         this.traces = config.tracing ? new TraceCollector(config.maxTraces) : null;
+        // Default to capturing everything when unset. `DebugStore` is a public
+        // export (`adonisjs-server-stats/debug`), so a config built before `capture`
+        // existed must keep behaving exactly as it did.
+        this.capture = config.capture ?? {
+            queries: true,
+            events: true,
+            emails: true,
+            traces: true,
+            logs: true,
+        };
     }
     /**
      * Register a callback that fires whenever any collector records a new item.
@@ -74,17 +86,33 @@ export class DebugStore {
             traces: this.traces?.getBufferInfo() ?? { current: 0, max: 0 },
         };
     }
+    /**
+     * Subscribe the enabled collectors.
+     *
+     * A disabled collector is left constructed but never subscribed, so its
+     * dashboard pane renders empty instead of erroring, and it costs nothing at
+     * runtime. This also keeps two process-wide side effects off in production:
+     * the event collector patches the emitter's `emit()`, and the trace collector
+     * patches `console.warn`.
+     *
+     * Route inspection is not gated — it reads the router table once at boot and
+     * captures no request data.
+     */
     async start(emitter, router) {
         // Runtime-check the emitter before passing to collectors.
         // The container returns `unknown`; collectors guard internally too.
         const e = emitter;
-        await this.queries.start(e);
-        this.events.start(e);
-        await this.emails.start(e);
+        if (this.capture.queries)
+            await this.queries.start(e);
+        if (this.capture.events)
+            this.events.start(e);
+        if (this.capture.emails)
+            await this.emails.start(e);
         if (router && typeof router.toJSON === 'function') {
             this.routes.inspect(router);
         }
-        this.traces?.start(e);
+        if (this.capture.traces)
+            this.traces?.start(e);
     }
     stop() {
         this.queries.stop();

package/dist/src/debug/types.d.ts

@@ -288,6 +288,20 @@ export interface DevToolbarConfig {
     dbPath: string;
     /** Base path for the debug toolbar API endpoints. */
     debugEndpoint: string;
+    /**
+     * Which capture subsystems are subscribed. Fully resolved — every field is
+     * present. All true outside production; all false in production unless the
+     * user opted in via `production.capture`.
+     */
+    capture: ResolvedCapture;
+}
+/** Fully-resolved capture flags. See {@link CaptureConfig} for the user-facing shape. */
+export interface ResolvedCapture {
+    queries: boolean;
+    events: boolean;
+    emails: boolean;
+    traces: boolean;
+    logs: boolean;
 }
 /**
  * Color names available for the `badge` column format.

package/dist/src/define_config.js

@@ -126,6 +126,27 @@ function resolveDevToolbar(config) {
 function first(primary, fallback, defaultVal) {
     return primary ?? fallback ?? defaultVal;
 }
+/**
+ * Warn about a production block that cannot do what it looks like it does.
+ *
+ * Both mistakes here are silent at runtime — the dashboard simply isn't there,
+ * or is there with nothing in it — so they're worth naming at config time.
+ */
+function warnAboutProduction(config) {
+    const production = config.production;
+    if (!production?.enabled)
+        return;
+    if (!config.authorize && !config.shouldShow) {
+        log.warn('server-stats: `production.enabled` is set but no `authorize` guard is configured — ' +
+            'the routes will NOT be registered in production. `unsafeAllowNoAuth` is deliberately ' +
+            'ignored there: an unauthenticated dashboard in production is never correct.');
+    }
+    const dashboardOn = config.dashboard !== undefined && config.dashboard !== false;
+    if (!dashboardOn && !config.toolbar) {
+        log.warn('server-stats: `production.enabled` is set but neither `dashboard` nor `toolbar` is ' +
+            'enabled, so there is nothing to expose. Set `dashboard: true` to serve the dashboard.');
+    }
+}
 /**
  * Warn about `domain` values that AdonisJS will never match.
  *
@@ -154,6 +175,7 @@ export function defineConfig(config) {
     logDeprecationWarnings(config);
     if (config.domain)
         warnAboutDomain(config.domain);
+    warnAboutProduction(config);
     return {
         intervalMs: first(config.pollInterval, config.intervalMs, 3000),
         transport: resolveTransport(config),
@@ -167,5 +189,6 @@ export function defineConfig(config) {
         unsafeAllowNoAuth: config.unsafeAllowNoAuth,
         verbose,
         domain: config.domain,
+        production: config.production,
     };
 }

package/dist/src/middleware/request_tracking_middleware.d.ts

@@ -1,10 +1,11 @@
 import type { TraceCollector } from '../debug/trace_collector.js';
 import type { TraceRecord } from '../debug/types.js';
+import type { AccessGuard } from '../types.js';
 import type { HttpContext } from '@adonisjs/core/http';
 import type { NextFn } from '@adonisjs/core/types/http';
 /** Returns true if the current async context is inside an excluded request. */
 export declare function isExcludedRequest(): boolean;
-export declare function setShouldShow(fn: ((ctx: HttpContext) => boolean) | null): void;
+export declare function setShouldShow(fn: AccessGuard | null): void;
 export declare function setTraceCollector(collector: TraceCollector | null): void;
 export declare function setDashboardPath(path: string | null): void;
 export declare function setExcludedPrefixes(prefixes: string[]): void;

package/dist/src/middleware/request_tracking_middleware.js

@@ -9,6 +9,8 @@ export function isExcludedRequest() {
 }
 let warnedShouldShow = false;
 let shouldShowFn = null;
+/** One-time latch for the async-guard-with-Edge-toolbar warning. */
+let warnedAsyncShouldShow = false;
 export function setShouldShow(fn) {
     shouldShowFn = fn;
 }
@@ -36,7 +38,20 @@ function shareShouldShowWithEdge(ctx) {
     ctxView.share({
         __ssShowFn: () => {
             try {
-                return shouldShowFn(ctx);
+                const visible = shouldShowFn(ctx);
+                // Edge evaluates this inside a compiled template statement, so it has to
+                // be synchronous. An async guard hands back a promise, which is truthy —
+                // showing the bar to everyone. Hide it instead and say why once.
+                if (typeof visible?.then === 'function') {
+                    if (!warnedAsyncShouldShow) {
+                        warnedAsyncShouldShow = true;
+                        log.warn('the `authorize` guard is async, which the @serverStats() toolbar cannot await — ' +
+                            'the stats bar stays hidden. Routes are still guarded correctly. Use a ' +
+                            'synchronous guard if you want the bar to render.');
+                    }
+                    return false;
+                }
+                return visible;
             }
             catch (err) {
                 if (!warnedShouldShow) {

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

@@ -26,5 +26,14 @@ export declare function warnAboutAuthMiddleware(config: ResolvedServerStatsConfi
  * say it out loud at boot.
  */
 export declare function warnAboutDomainWithToolbar(config: ResolvedServerStatsConfig): void;
+/**
+ * Announce that the dashboard is live in production.
+ *
+ * Deliberately `log.warn` rather than the `log.block` its neighbours use:
+ * `log.block` is suppressed unless `verbose` is on, and this is the one message
+ * that must reach every operator who enables production mode. It only fires
+ * after routes were really registered, so it never over-promises.
+ */
+export declare function announceProductionMode(config: ResolvedServerStatsConfig, paths: string[]): void;
 export declare function warnAboutSessionMiddleware(makePath: (dir: string, file: string) => string): void;
 export declare function logDashboardError(category: 'missing-dep' | 'timeout' | 'unknown', err: unknown): void;

package/dist/src/provider/boot_helpers.js

@@ -75,6 +75,37 @@ export function warnAboutDomainWithToolbar(config) {
         dim(`served from ${config.domain}. On any other host the bar will stay empty.`),
     ]);
 }
+/** Human-readable list of the capture subsystems that are switched on. */
+function describeCapture(config) {
+    const requested = config.production?.capture;
+    if (!requested)
+        return 'nothing (request metadata only)';
+    const on = ['queries', 'events', 'emails', 'traces', 'logs'].filter((key) => requested[key] === true);
+    return on.length > 0 ? on.join(', ') : 'nothing (request metadata only)';
+}
+/**
+ * Announce that the dashboard is live in production.
+ *
+ * Deliberately `log.warn` rather than the `log.block` its neighbours use:
+ * `log.block` is suppressed unless `verbose` is on, and this is the one message
+ * that must reach every operator who enables production mode. It only fires
+ * after routes were really registered, so it never over-promises.
+ */
+export function announceProductionMode(config, paths) {
+    if (!config.production?.enabled)
+        return;
+    const retention = config.production.retentionDays ?? 3;
+    const dbPath = config.devToolbar?.dbPath ?? '.adonisjs/server-stats/dashboard.sqlite3';
+    const lines = [
+        `  reachable at:  ${paths.join(', ')}`,
+        `  guard:         ${config.shouldShow ? 'authorize() configured' : 'NONE'}`,
+        `  capturing:     ${describeCapture(config)}`,
+    ];
+    if (config.devToolbar?.dashboard) {
+        lines.push(`  data at:       ${dbPath} (retention: ${retention} days)`);
+    }
+    log.warn('DASHBOARD IS LIVE IN PRODUCTION\n' + lines.join('\n'));
+}
 export function warnAboutSessionMiddleware(makePath) {
     const found = detectGlobalSessionMiddleware(makePath);
     if (found.length === 0)

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,

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.0",
   "description": "Real-time server monitoring for AdonisJS v6 applications",
   "keywords": [
     "adonisjs",