adonisjs-server-stats 1.11.6 → 1.12.0

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

@@ -23,6 +23,8 @@ export interface DiagnosticsInput {
     hasQueueCollector?: boolean;
     resolvedCollectors?: CollectorRef[];
     config: DiagnosticsConfig | null;
+    /** Lucid connections that have debug: true (empty = no query events emitted). */
+    lucidDebugConnections?: string[];
 }
 interface DiagnosticsConfig {
     intervalMs: number;
@@ -130,5 +132,6 @@ export declare function buildDiagnostics(input: DiagnosticsInput): {
         slowQueryThresholdMs: number;
         enabled: boolean;
     };
+    lucidDebugConnections: string[];
 };
 export {};

package/dist/src/provider/diagnostics.js

@@ -123,5 +123,6 @@ export function buildDiagnostics(input) {
         integrations: buildIntegrationsDiagnostics(input),
         config: buildConfigDiagnostics(input.config),
         devToolbar: buildDevToolbarDiagnostics(input.config),
+        lucidDebugConnections: input.lucidDebugConnections ?? [],
     };
 }

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

@@ -31,6 +31,7 @@ export default class ServerStatsProvider {
     transmitChannels: string[];
     private resolvedConfig;
     private resolvedCollectors;
+    private lucidDebugConnections;
     /** Resolves when initStats completes (or rejects). Null if not yet scheduled. */
     private initPromise;
     constructor(app: ApplicationService);
@@ -49,6 +50,11 @@ export default class ServerStatsProvider {
     private setupDevToolbar;
     private setupLogBroadcast;
     private resolve;
+    /**
+     * Check Lucid database connections for `debug: true` and warn if missing.
+     * Without it, Lucid won't emit `db:query` events and no queries will be captured.
+     */
+    private checkLucidDebugFlag;
     getDiagnostics(): {
         timers: {
             collectionInterval: {
@@ -124,6 +130,7 @@ export default class ServerStatsProvider {
             slowQueryThresholdMs: number;
             enabled: boolean;
         };
+        lucidDebugConnections: string[];
     };
     shutdown(): Promise<void>;
 }

package/dist/src/provider/server_stats_provider.js

@@ -33,6 +33,7 @@ export default class ServerStatsProvider {
     transmitChannels = [];
     resolvedConfig = null;
     resolvedCollectors = [];
+    lucidDebugConnections = [];
     /** Resolves when initStats completes (or rejects). Null if not yet scheduled. */
     initPromise = null;
     constructor(app) {
@@ -87,6 +88,8 @@ export default class ServerStatsProvider {
             getStatsController: () => this.statsController,
             getDebugController: () => this.debugController,
             getDashboardController: () => this.dashboardController,
+            getDebugStore: () => this.debugStore,
+            getApp: () => this.app,
             statsEndpoint,
             debugEndpoint,
             dashboardPath,
@@ -126,6 +129,7 @@ export default class ServerStatsProvider {
         const SC = (await import('../controller/server_stats_controller.js')).default;
         this.statsController = new SC(this.engine);
         if (config.devToolbar?.enabled && !this.app.inProduction) {
+            this.checkLucidDebugFlag();
             await this.setupDevToolbar(config);
         }
         const iv = await setupStatsIntervalHelper(this.engine, config, container);
@@ -193,6 +197,39 @@ export default class ServerStatsProvider {
             return null;
         }
     }
+    /**
+     * Check Lucid database connections for `debug: true` and warn if missing.
+     * Without it, Lucid won't emit `db:query` events and no queries will be captured.
+     */
+    checkLucidDebugFlag() {
+        const dbConfig = this.app.config.get('database');
+        if (!dbConfig?.connections)
+            return;
+        const enabled = [];
+        const disabled = [];
+        for (const [name, conn] of Object.entries(dbConfig.connections)) {
+            if (conn?.debug)
+                enabled.push(name);
+            else
+                disabled.push(name);
+        }
+        this.lucidDebugConnections = enabled;
+        if (enabled.length === 0 && disabled.length > 0) {
+            log.block('query capture is disabled — no Lucid connections have debug: true', [
+                '',
+                dim('Lucid only emits db:query events when debug is enabled on a connection.'),
+                dim('Add this to your database connection in config/database.ts:'),
+                '',
+                `  ${disabled[0]}: {`,
+                `    client: '...',`,
+                `    debug: true,      ${dim('// ← enables query capture')}`,
+                `    connection: { ... },`,
+                `  }`,
+                '',
+                dim(`Connections without debug: ${disabled.join(', ')}`),
+            ]);
+        }
+    }
     getDiagnostics() {
         return buildDiagnostics({
             intervalId: this.intervalId,
@@ -209,6 +246,7 @@ export default class ServerStatsProvider {
             hasCacheCollector: this.resolvedCollectors.some((c) => c.name === 'redis'),
             hasQueueCollector: this.resolvedCollectors.some((c) => c.name === 'queue'),
             config: this.resolvedConfig,
+            lucidDebugConnections: this.lucidDebugConnections,
         });
     }
     async shutdown() {

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

@@ -1,12 +1,16 @@
 import type { ApiController } from '../controller/api_controller.js';
 import type DebugController from '../controller/debug_controller.js';
+import type { DebugStore } from '../debug/debug_store.js';
 import type { AdonisRouter } from './router_types.js';
 import type { HttpContext } from '@adonisjs/core/http';
+import type { ApplicationService } from '@adonisjs/core/types';
 interface DebugRoutesOpts {
     router: AdonisRouter;
     debugEndpoint: string;
     getDebugController: () => DebugController | null;
     getApiController: () => ApiController | null;
+    getDebugStore?: () => DebugStore | null;
+    getApp?: () => ApplicationService | null;
     middleware: Array<(ctx: HttpContext, next: () => Promise<void>) => Promise<void>>;
     whenReady?: () => Promise<void>;
 }

package/dist/src/routes/debug_routes.js

@@ -1,3 +1,4 @@
+import { getAppDbClient, buildExplainSql, extractPlan } from '../dashboard/query_explain_handler.js';
 let _whenReady;
 function bindDebug(getController, method) {
     return async (ctx) => {
@@ -89,6 +90,49 @@ function registerDebugTraceRoutes(router, getApiController) {
     }))
         .as('server-stats.debug.traceDetail');
 }
+function registerDebugExplainRoute(router, getDebugStore, getApp) {
+    if (!getDebugStore || !getApp)
+        return;
+    router
+        .get('/queries/:id/explain', async (ctx) => {
+        if (_whenReady)
+            await _whenReady();
+        const store = getDebugStore();
+        const app = getApp();
+        if (!store || !app) {
+            return ctx.response.serviceUnavailable({ error: 'Debug store not ready' });
+        }
+        const query = store.queries.getQueryById(Number(ctx.params.id));
+        if (!query)
+            return ctx.response.notFound({ error: 'Query not found' });
+        if (!query.sql.trim().toUpperCase().startsWith('SELECT')) {
+            return ctx.response.badRequest({ error: 'EXPLAIN is only supported for SELECT queries' });
+        }
+        try {
+            const appDb = await getAppDbClient(app, query.connection || undefined);
+            if (!appDb) {
+                return ctx.response.serviceUnavailable({ error: 'App database connection not available' });
+            }
+            const bindings = Array.isArray(query.bindings) ? query.bindings : [];
+            const explainSql = buildExplainSql(query.sql, appDb.dialect);
+            if (!explainSql) {
+                return ctx.response.badRequest({
+                    error: `EXPLAIN is not supported for ${appDb.dialect} databases`,
+                });
+            }
+            const explainResult = await appDb.raw(explainSql, bindings);
+            const plan = extractPlan(explainResult, appDb.dialect);
+            return ctx.response.json({ queryId: query.id, sql: query.sql, plan });
+        }
+        catch (error) {
+            return ctx.response.internalServerError({
+                error: 'EXPLAIN failed',
+                message: error?.message ?? 'Unknown error',
+            });
+        }
+    })
+        .as('server-stats.debug.queryExplain');
+}
 /** Register debug panel API routes. */
 export function registerDebugRoutes(opts) {
     const { router, debugEndpoint, getDebugController, getApiController, middleware } = opts;
@@ -99,6 +143,7 @@ export function registerDebugRoutes(opts) {
         .group(() => {
         registerDebugConfigRoutes(router, getDebugController);
         registerDebugQueryAndEventRoutes(router, getApiController);
+        registerDebugExplainRoute(router, opts.getDebugStore, opts.getApp);
         registerDebugLogRoutes(router, getApiController);
         registerDebugEmailRoutes(router, getApiController);
         registerDebugTraceRoutes(router, getApiController);

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

@@ -1,9 +1,11 @@
 import type { ApiController } from '../controller/api_controller.js';
 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 { 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.
  */
@@ -13,6 +15,8 @@ export interface RegisterRoutesOptions {
     getStatsController: () => ServerStatsController | null;
     getDebugController: () => DebugController | null;
     getDashboardController: () => DashboardController | null;
+    getDebugStore?: () => DebugStore | null;
+    getApp?: () => ApplicationService | null;
     statsEndpoint?: string | false;
     debugEndpoint?: string;
     dashboardPath?: string;

package/dist/src/routes/register_routes.js

@@ -16,6 +16,8 @@ export function registerAllRoutes(options) {
             debugEndpoint: options.debugEndpoint,
             getDebugController: options.getDebugController,
             getApiController: options.getApiController,
+            getDebugStore: options.getDebugStore,
+            getApp: options.getApp,
             middleware,
             whenReady: options.whenReady,
         });

package/dist/src/styles/components.css

@@ -94,13 +94,29 @@
 .ss-dash-empty,
 .ss-dbg-empty {
   display: flex;
+  flex-direction: column;
   align-items: center;
   justify-content: center;
+  gap: 6px;
   height: 100%;
   min-height: 120px;
   color: var(--ss-dim);
   font-size: 12px;
 }
+.ss-empty-hint {
+  font-size: 11px;
+  color: var(--ss-dim);
+  opacity: 0.7;
+  max-width: 420px;
+  text-align: center;
+  line-height: 1.5;
+}
+.ss-empty-hint code {
+  background: var(--ss-surface, rgba(255,255,255,0.06));
+  padding: 1px 5px;
+  border-radius: 3px;
+  font-size: 10px;
+}
 
 /* ── Info cards ───────────────────────────────────────────────── */
 .ss-info-cards,
@@ -435,6 +451,7 @@
   background: var(--ss-surface);
   border-bottom: 1px solid var(--ss-border);
   white-space: nowrap;
+  z-index: 2;
 }
 .ss-table td,
 .ss-dash-table td,
@@ -446,6 +463,7 @@
   text-overflow: ellipsis;
   white-space: nowrap;
   color: var(--ss-text);
+  max-width: 0;
 }
 .ss-table tr:hover td,
 .ss-dash-table tr:hover td,
@@ -517,6 +535,242 @@
   background: var(--ss-red-bg);
   color: var(--ss-red-fg);
 }
+/* SQL method variants (query tables) */
+.ss-method-select,
+.ss-dash-method-select,
+.ss-dbg-method-select {
+  background: var(--ss-green-bg);
+  color: var(--ss-green-fg);
+}
+.ss-method-insert,
+.ss-dash-method-insert,
+.ss-dbg-method-insert {
+  background: var(--ss-blue-bg);
+  color: var(--ss-blue-fg);
+}
+.ss-method-update,
+.ss-dash-method-update,
+.ss-dbg-method-update {
+  background: var(--ss-amber-bg);
+  color: var(--ss-amber-fg);
+}
+.ss-method-head,
+.ss-method-options,
+.ss-method-raw,
+.ss-dash-method-head,
+.ss-dash-method-options,
+.ss-dash-method-raw,
+.ss-dbg-method-head,
+.ss-dbg-method-options,
+.ss-dbg-method-raw {
+  background: var(--ss-surface);
+  color: var(--ss-dim);
+}
+
+/* ── SQL cell text ───────────────────────────────────────────── */
+.ss-sql,
+.ss-dash-sql,
+.ss-dbg-sql {
+  font-size: 11px;
+  color: var(--ss-sql-color);
+  word-break: break-all;
+  cursor: pointer;
+  max-width: 600px;
+  display: inline-block;
+}
+.ss-sql.ss-expanded,
+.ss-dash-sql.ss-dash-expanded,
+.ss-dbg-sql.ss-dbg-expanded {
+  white-space: pre-wrap;
+  max-width: none;
+}
+
+/* ── Duplicate query badge ───────────────────────────────────── */
+.ss-dup,
+.ss-dash-dup,
+.ss-dbg-dup {
+  color: var(--ss-purple-fg);
+  font-size: 10px;
+  font-weight: 600;
+}
+
+/* ── Scrollable table container ──────────────────────────────── */
+.ss-table-wrap,
+.ss-dash-table-wrap,
+.ss-dbg-table-wrap {
+  flex: 1;
+  overflow-x: auto;
+  overflow-y: visible;
+  margin: 0 -2px;
+  padding: 0 2px;
+  scrollbar-width: thin;
+  scrollbar-color: var(--ss-border) transparent;
+}
+
+/* ── Sortable column headers ─────────────────────────────────── */
+.ss-sortable,
+.ss-dash-sortable,
+.ss-dbg-sortable {
+  cursor: pointer;
+  user-select: none;
+}
+.ss-sortable:hover,
+.ss-dash-sortable:hover,
+.ss-dbg-sortable:hover {
+  color: var(--ss-accent);
+}
+.ss-sort-arrow,
+.ss-dash-sort-arrow,
+.ss-dbg-sort-arrow {
+  font-size: 10px;
+  color: var(--ss-accent);
+  margin-left: 2px;
+}
+
+/* ── Clickable table rows ────────────────────────────────────── */
+.ss-table tr.ss-clickable,
+.ss-dash-table tr.ss-dash-clickable,
+.ss-dbg-table tr.ss-dbg-clickable {
+  cursor: pointer;
+}
+.ss-table tr.ss-clickable:hover td,
+.ss-dash-table tr.ss-dash-clickable:hover td,
+.ss-dbg-table tr.ss-dbg-clickable:hover td {
+  background: var(--ss-hover-accent);
+}
+
+/* ── Event time ──────────────────────────────────────────────── */
+.ss-event-time,
+.ss-dash-event-time,
+.ss-dbg-event-time {
+  color: var(--ss-dim);
+  font-size: 10px;
+}
+
+/* ── EXPLAIN panel ───────────────────────────────────────────── */
+.ss-explain-row td,
+.ss-dash-explain-row td,
+.ss-dbg-explain-row td {
+  white-space: normal;
+  overflow: visible;
+  max-width: none;
+}
+.ss-table tr.ss-explain-row:hover td,
+.ss-dash-table tr.ss-dash-explain-row:hover td,
+.ss-dbg-table tr.ss-dbg-explain-row:hover td {
+  background: var(--ss-surface-alt);
+}
+.ss-explain,
+.ss-dash-explain,
+.ss-dbg-explain {
+  padding: 12px 16px;
+  background: var(--ss-surface-alt);
+  border-top: 1px solid var(--ss-border-dim);
+  font-size: 11px;
+  overflow: hidden;
+  word-break: break-word;
+}
+.ss-explain-btn,
+.ss-dash-explain-btn,
+.ss-dbg-explain-btn {
+  padding: 2px 8px;
+  font-size: 9px;
+  color: var(--ss-purple-fg);
+  background: var(--ss-purple-bg);
+  border: none;
+  border-radius: 3px;
+  cursor: pointer;
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+  font-weight: 600;
+}
+.ss-explain-btn:hover,
+.ss-dash-explain-btn:hover,
+.ss-dbg-explain-btn:hover {
+  opacity: 0.8;
+}
+.ss-explain-btn-active,
+.ss-dash-explain-btn-active,
+.ss-dbg-explain-btn-active {
+  background: var(--ss-purple-fg);
+  color: #fff;
+}
+.ss-explain-result,
+.ss-dash-explain-result,
+.ss-dbg-explain-result {
+  margin-top: 6px;
+  font-size: 11px;
+  color: var(--ss-text-secondary);
+}
+.ss-explain-error,
+.ss-dash-explain-error,
+.ss-dbg-explain-error {
+  color: var(--ss-red-fg);
+  padding: 8px;
+  background: var(--ss-red-bg);
+  border-radius: 4px;
+}
+.ss-explain-node,
+.ss-dash-explain-node,
+.ss-dbg-explain-node {
+  padding: 4px 0;
+  border-left: 2px solid var(--ss-border-dim);
+  padding-left: 10px;
+  margin-top: 2px;
+}
+.ss-explain-node:first-child,
+.ss-dash-explain-node:first-child,
+.ss-dbg-explain-node:first-child {
+  border-left: 2px solid var(--ss-purple-fg);
+}
+.ss-explain-node-header,
+.ss-dash-explain-node-header,
+.ss-dbg-explain-node-header {
+  font-weight: 600;
+  color: var(--ss-text-primary);
+  font-size: 11px;
+}
+.ss-explain-node-type,
+.ss-dash-explain-node-type,
+.ss-dbg-explain-node-type {
+  color: var(--ss-purple-fg);
+  font-weight: 700;
+}
+.ss-explain-metrics,
+.ss-dash-explain-metrics,
+.ss-dbg-explain-metrics {
+  font-size: 10px;
+  color: var(--ss-dim);
+  margin-top: 1px;
+  font-family: var(--ss-font-mono);
+  word-break: break-all;
+  overflow-wrap: break-word;
+}
+.ss-explain-result table,
+.ss-dash-explain-result table,
+.ss-dbg-explain-result table {
+  width: 100%;
+  border-collapse: collapse;
+  margin-top: 4px;
+}
+.ss-explain-result th,
+.ss-dash-explain-result th,
+.ss-dbg-explain-result th {
+  padding: 3px 8px;
+  text-align: left;
+  font-weight: 600;
+  color: var(--ss-muted);
+  border-bottom: 1px solid var(--ss-border);
+  font-size: 9px;
+  text-transform: uppercase;
+}
+.ss-explain-result td,
+.ss-dash-explain-result td,
+.ss-dbg-explain-result td {
+  padding: 3px 8px;
+  border-bottom: 1px solid var(--ss-border-faint);
+  color: var(--ss-text-secondary);
+}
 
 /* ── 3. Log system ───────────────────────────────────────────── */
 /* Log entry row: dashboard uses 16px horizontal padding, debug uses 12px.