adonisjs-server-stats 1.5.1 → 1.5.2

package/README.md

@@ -159,16 +159,13 @@ export default defineConfig({
 })
 ```
 
-### 4. Add a route
+### 4. Add routes
 
-```ts
-// start/routes.ts
-router
-  .get('/admin/api/server-stats', '#controllers/admin/server_stats_controller.index')
-  .use(middleware.superadmin()) // Replace with your own middleware
-```
+The package has three layers of functionality, each with its own routes:
 
-### 5. Create the controller
+#### Stats bar API route (required)
+
+The stats bar polls this endpoint for live metrics. Create a controller and route:
 
 ```ts
 // app/controllers/admin/server_stats_controller.ts
@@ -184,7 +181,148 @@ export default class ServerStatsController {
 }
 ```
 
-### 6. Render the stats bar
+```ts
+// start/routes.ts
+router
+  .get('/admin/api/server-stats', '#controllers/admin/server_stats_controller.index')
+  .use(middleware.superadmin())
+```
+
+> The route path must match `endpoint` in your config (default: `/admin/api/server-stats`).
+
+#### Debug toolbar routes (optional -- when `devToolbar.enabled: true`)
+
+The debug toolbar panels fetch data from these API endpoints. Create a controller and routes:
+
+```ts
+// app/controllers/admin/debug_controller.ts
+import app from '@adonisjs/core/services/app'
+import type { HttpContext } from '@adonisjs/core/http'
+import type { DebugStore } from 'adonisjs-server-stats/debug'
+
+export default class DebugController {
+  private async getStore(): Promise<DebugStore | null> {
+    try {
+      return (await app.container.make('debug.store')) as DebugStore
+    } catch {
+      return null
+    }
+  }
+
+  async queries({ response }: HttpContext) {
+    const store = await this.getStore()
+    if (!store) return response.notFound({ error: 'Debug toolbar not enabled' })
+    return response.json({ queries: store.queries.getLatest(500), summary: store.queries.getSummary() })
+  }
+
+  async events({ response }: HttpContext) {
+    const store = await this.getStore()
+    if (!store) return response.notFound({ error: 'Debug toolbar not enabled' })
+    return response.json({ events: store.events.getLatest(200), total: store.events.getTotalCount() })
+  }
+
+  async routes({ response }: HttpContext) {
+    const store = await this.getStore()
+    if (!store) return response.notFound({ error: 'Debug toolbar not enabled' })
+    return response.json({ routes: store.routes.getRoutes(), total: store.routes.getRouteCount() })
+  }
+
+  async logs({ response }: HttpContext) {
+    const store = await this.getStore()
+    if (!store) return response.notFound({ error: 'Debug toolbar not enabled' })
+    return response.json({ logs: store.logs.getLatest(500), total: store.logs.getTotalCount() })
+  }
+
+  async emails({ response }: HttpContext) {
+    const store = await this.getStore()
+    if (!store) return response.notFound({ error: 'Debug toolbar not enabled' })
+    const emails = store.emails.getLatest(100)
+    const stripped = emails.map(({ html, text, ...rest }) => rest)
+    return response.json({ emails: stripped, total: store.emails.getTotalCount() })
+  }
+
+  async emailPreview({ params, response }: HttpContext) {
+    const store = await this.getStore()
+    if (!store) return response.notFound({ error: 'Debug toolbar not enabled' })
+    const html = store.emails.getEmailHtml(Number(params.id))
+    if (!html) return response.notFound({ error: 'Email not found' })
+    return response.header('Content-Type', 'text/html; charset=utf-8').send(html)
+  }
+
+  async traces({ response }: HttpContext) {
+    const store = await this.getStore()
+    if (!store) return response.notFound({ error: 'Debug toolbar not enabled' })
+    if (!store.traces) return response.json({ traces: [], total: 0 })
+    const traces = store.traces.getLatest(100)
+    const list = traces.map(({ spans, warnings, ...rest }: any) => ({
+      ...rest,
+      warningCount: warnings.length,
+    }))
+    return response.json({ traces: list, total: store.traces.getTotalCount() })
+  }
+
+  async traceDetail({ params, response }: HttpContext) {
+    const store = await this.getStore()
+    if (!store) return response.notFound({ error: 'Debug toolbar not enabled' })
+    if (!store.traces) return response.notFound({ error: 'Tracing not enabled' })
+    const trace = store.traces.getTrace(Number(params.id))
+    if (!trace) return response.notFound({ error: 'Trace not found' })
+    return response.json(trace)
+  }
+}
+```
+
+```ts
+// start/routes.ts
+router
+  .group(() => {
+    router.get('queries', '#controllers/admin/debug_controller.queries')
+    router.get('events', '#controllers/admin/debug_controller.events')
+    router.get('routes', '#controllers/admin/debug_controller.routes')
+    router.get('logs', '#controllers/admin/debug_controller.logs')
+    router.get('emails', '#controllers/admin/debug_controller.emails')
+    router.get('emails/:id/preview', '#controllers/admin/debug_controller.emailPreview')
+    router.get('traces', '#controllers/admin/debug_controller.traces')
+    router.get('traces/:id', '#controllers/admin/debug_controller.traceDetail')
+  })
+  .prefix('/admin/api/debug')
+  .use(middleware.superadmin())
+```
+
+#### Dashboard routes (automatic -- when `devToolbar.dashboard: true`)
+
+The full-page dashboard at `/__stats` **registers its own routes automatically** -- no manual route setup needed. The following routes are created under the configured `dashboardPath` (default: `/__stats`):
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/` | Dashboard page (HTML) |
+| GET | `/api/overview` | Overview metrics |
+| GET | `/api/overview/chart` | Time-series chart data |
+| GET | `/api/requests` | Paginated request history |
+| GET | `/api/requests/:id` | Request detail with queries/trace |
+| GET | `/api/queries` | Paginated query list |
+| GET | `/api/queries/grouped` | Queries grouped by normalized SQL |
+| GET | `/api/queries/:id/explain` | EXPLAIN plan for a query |
+| GET | `/api/events` | Paginated event list |
+| GET | `/api/routes` | Route table |
+| GET | `/api/logs` | Paginated log entries |
+| GET | `/api/emails` | Paginated email list |
+| GET | `/api/emails/:id/preview` | Email HTML preview |
+| GET | `/api/traces` | Paginated trace list |
+| GET | `/api/traces/:id` | Trace detail with spans |
+| GET | `/api/cache` | Cache stats and key listing |
+| GET | `/api/cache/:key` | Cache key detail |
+| GET | `/api/jobs` | Job queue overview |
+| GET | `/api/jobs/:id` | Job detail |
+| POST | `/api/jobs/:id/retry` | Retry a failed job |
+| GET | `/api/config` | App config (secrets redacted) |
+| GET | `/api/filters` | Saved filters |
+| POST | `/api/filters` | Create saved filter |
+| DELETE | `/api/filters/:id` | Delete saved filter |
+
+All dashboard routes are gated by the `shouldShow` callback if configured.
+
+### 5. Render the stats bar
 
 **Edge** (add before `</body>`):
 
@@ -226,7 +364,7 @@ export default class ServerStatsController {
 | `dashboardPath`        | `string`            | `'/__stats'`                                 | URL path for the dashboard page                                                                                                                                                                              |
 | `retentionDays`        | `number`            | `7`                                          | Days to keep historical data in SQLite                                                                                                                                                                       |
 | `dbPath`               | `string`            | `'.adonisjs/server-stats/dashboard.sqlite3'` | Path to the SQLite database file (relative to app root)                                                                                                                                                      |
-| `excludeFromTracing`   | `string[]`          | `[]`                                         | URL prefixes to exclude from tracing and dashboard persistence. Requests still count toward HTTP metrics but won't appear in the timeline or be stored. The stats endpoint is always excluded automatically. |
+| `excludeFromTracing`   | `string[]`          | `['/admin/api/debug', '/admin/api/server-stats']`                                         | URL prefixes to exclude from tracing and dashboard persistence. Requests still count toward HTTP metrics but won't appear in the timeline or be stored. The stats endpoint is always excluded automatically. |
 | `panes`                | `DebugPane[]`       | --                                           | Custom debug panel tabs                                                                                                                                                                                      |
 
 ---
@@ -393,28 +531,22 @@ export default defineConfig({
 })
 ```
 
-Register the debug API routes:
-
-```ts
-// start/routes.ts
-router
-  .group(() => {
-    router.get('queries', '#controllers/admin/debug_controller.queries')
-    router.get('events', '#controllers/admin/debug_controller.events')
-    router.get('routes', '#controllers/admin/debug_controller.routes')
-    router.get('emails', '#controllers/admin/debug_controller.emails')
-    router.get('emails/:id/preview', '#controllers/admin/debug_controller.emailPreview')
-    router.get('traces', '#controllers/admin/debug_controller.traces')
-    router.get('traces/:id', '#controllers/admin/debug_controller.traceDetail')
-  })
-  .prefix('/admin/api/debug')
-  .use(middleware.admin())
-```
+Register the debug API routes (see [step 4](#4-add-routes) for the full controller and route setup).
 
 ### Built-in Emails Tab
 
 The debug toolbar captures all emails sent via AdonisJS mail (`mail:sending`, `mail:sent`, `mail:queued`, `queued:mail:error` events). Click any email row to preview its HTML in an iframe.
 
+> **Note:** Email previews are rendered in an iframe. If your app uses `@adonisjs/shield` with the default `X-Frame-Options: DENY` header, the preview will be blocked. Change it to `SAMEORIGIN` in your shield config:
+>
+> ```ts
+> // config/shield.ts
+> xFrame: {
+>   enabled: true,
+>   action: 'SAMEORIGIN',
+> },
+> ```
+
 ### Persistent Debug Data
 
 Enable `persistDebugData: true` to save queries, events, and emails to `.adonisjs/server-stats/debug-data.json`. You can also pass a custom path (relative to app root) like `persistDebugData: 'custom/debug.json'`. Data is:

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

@@ -1 +1 @@
-{"version":3,"file":"server_stats_provider.d.ts","sourceRoot":"","sources":["../../../src/provider/server_stats_provider.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAA;AAE9D,MAAM,CAAC,OAAO,OAAO,mBAAmB;IAY1B,SAAS,CAAC,GAAG,EAAE,kBAAkB;IAX7C,OAAO,CAAC,UAAU,CAA8C;IAChE,OAAO,CAAC,MAAM,CAA2B;IACzC,OAAO,CAAC,UAAU,CAA0B;IAC5C,OAAO,CAAC,cAAc,CAA8B;IACpD,OAAO,CAAC,mBAAmB,CAAmC;IAC9D,OAAO,CAAC,kBAAkB,CAAgC;IAC1D,OAAO,CAAC,uBAAuB,CAA8C;IAC7E,OAAO,CAAC,mBAAmB,CAA6C;IACxE,OAAO,CAAC,WAAW,CAAsB;IACzC,OAAO,CAAC,UAAU,CAA8C;gBAE1C,GAAG,EAAE,kBAAkB;IAEvC,IAAI;IAkCJ,KAAK;YA8EG,eAAe;IAmF7B;;;;;;OAMG;YACW,cAAc;IAoGtB,QAAQ;CAwCf"}
+{"version":3,"file":"server_stats_provider.d.ts","sourceRoot":"","sources":["../../../src/provider/server_stats_provider.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAA;AAE9D,MAAM,CAAC,OAAO,OAAO,mBAAmB;IAY1B,SAAS,CAAC,GAAG,EAAE,kBAAkB;IAX7C,OAAO,CAAC,UAAU,CAA8C;IAChE,OAAO,CAAC,MAAM,CAA2B;IACzC,OAAO,CAAC,UAAU,CAA0B;IAC5C,OAAO,CAAC,cAAc,CAA8B;IACpD,OAAO,CAAC,mBAAmB,CAAmC;IAC9D,OAAO,CAAC,kBAAkB,CAAgC;IAC1D,OAAO,CAAC,uBAAuB,CAA8C;IAC7E,OAAO,CAAC,mBAAmB,CAA6C;IACxE,OAAO,CAAC,WAAW,CAAsB;IACzC,OAAO,CAAC,UAAU,CAA8C;gBAE1C,GAAG,EAAE,kBAAkB;IAEvC,IAAI;IAkCJ,KAAK;YA+EG,eAAe;IAmF7B;;;;;;OAMG;YACW,cAAc;IAoGtB,QAAQ;CAwCf"}

package/dist/src/provider/server_stats_provider.js

@@ -79,7 +79,8 @@ export default class ServerStatsProvider {
             });
             // Exclude the stats endpoint and user-specified prefixes from tracing
             // so the debug panel's own polling doesn't flood the timeline
-            const prefixes = [...(toolbarConfig.excludeFromTracing ?? [])];
+            const defaultExcludes = ['/admin/api/debug', '/admin/api/server-stats'];
+            const prefixes = [...(toolbarConfig.excludeFromTracing ?? defaultExcludes)];
             if (typeof config.endpoint === 'string') {
                 prefixes.push(config.endpoint);
             }

package/dist/src/types.d.ts

@@ -281,10 +281,10 @@ export interface DevToolbarOptions {
      *
      * @example
      * ```ts
-     * excludeFromTracing: ['/admin/api/debug']
+     * excludeFromTracing: ['/admin/api/debug', '/admin/api/server-stats']
      * ```
      *
-     * @default []
+     * @default ['/admin/api/debug', '/admin/api/server-stats']
      */
     excludeFromTracing?: string[];
 }

package/package.json

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