adonisjs-server-stats 1.10.0 → 1.11.0

package/README.md

@@ -7,7 +7,7 @@
 [![AdonisJS](https://img.shields.io/badge/AdonisJS-v6-5A45FF.svg)](https://adonisjs.com/)
 [![AdonisJS](https://img.shields.io/badge/AdonisJS-v7-5A45FF.svg)](https://adonisjs.com/)
 
-A Laravel Telescope-inspired dev toolbar and real-time server monitor for **AdonisJS v6**.
+A Laravel Telescope-inspired dev toolbar and real-time server monitor for **AdonisJS v6 & v7**.
 
 Drop a single Edge tag into your layout and get a live stats bar showing CPU, memory, requests/sec, database pool, Redis, queues, and logs -- plus a full debug toolbar with SQL query inspection, event tracing, route listing, live log tailing, and custom panels.
 
@@ -178,7 +178,7 @@ All fields are optional. `defineConfig({})` works with zero configuration.
 | Option               | Type       | Default                                           | Description                                     |
 | -------------------- | ---------- | ------------------------------------------------- | ----------------------------------------------- |
 | `slowQueryThreshold` | `number`   | `100`                                             | Slow query threshold (ms)                        |
-| `tracing`            | `boolean`  | `false`                                           | Enable per-request tracing with timeline         |
+| `tracing`            | `boolean`  | `true`                                            | Enable per-request tracing with timeline         |
 | `persist`            | `boolean`  | `false`                                           | Persist debug data to disk across restarts       |
 | `panes`              | `DebugPane[]` | --                                             | Custom debug panel tabs                          |
 | `excludeFromTracing` | `string[]` | `['/admin/api/debug', '/admin/api/server-stats']` | URL prefixes to exclude from tracing/persistence |
@@ -231,7 +231,7 @@ The following field names still work but will show deprecation warnings at boot.
 | `maxEmails`            | `number`            | `100`                                             | Max emails to buffer                                                                                                                                                                                         |
 | `slowQueryThresholdMs` | `number`            | `100`                                             | Slow query threshold (ms)                                                                                                                                                                                    |
 | `persistDebugData`     | `boolean \| string` | `false`                                           | Persist debug data to disk across restarts. `true` writes to `.adonisjs/server-stats/debug-data.json`, or pass a custom path.                                                                                |
-| `tracing`              | `boolean`           | `false`                                           | Enable per-request tracing with timeline visualization                                                                                                                                                       |
+| `tracing`              | `boolean`           | `true`                                            | Enable per-request tracing with timeline visualization                                                                                                                                                       |
 | `maxTraces`            | `number`            | `200`                                             | Max request traces to buffer                                                                                                                                                                                 |
 | `dashboard`            | `boolean`           | `false`                                           | Enable the full-page dashboard (requires `better-sqlite3`)                                                                                                                                                   |
 | `dashboardPath`        | `string`            | `'/__stats'`                                      | URL path for the dashboard page                                                                                                                                                                              |
@@ -381,16 +381,18 @@ Registered when `statsEndpoint` is a string (default: `/admin/api/server-stats`)
 
 Registered when `toolbar` is enabled. Base path configurable via `advanced.debugEndpoint` (default: `/admin/api/debug`).
 
-| Method | Path                  | Description                     |
-| ------ | --------------------- | ------------------------------- |
-| GET    | `/queries`            | SQL queries with summary stats  |
-| GET    | `/events`             | Application events              |
-| GET    | `/routes`             | Registered route table          |
-| GET    | `/logs`               | Log file entries (last 256KB)   |
-| GET    | `/emails`             | Captured emails (stripped HTML) |
-| GET    | `/emails/:id/preview` | Email HTML preview              |
-| GET    | `/traces`             | Request traces                  |
-| GET    | `/traces/:id`         | Trace detail with spans         |
+| Method | Path                  | Description                              |
+| ------ | --------------------- | ---------------------------------------- |
+| GET    | `/queries`            | SQL queries with summary stats           |
+| GET    | `/events`             | Application events                       |
+| GET    | `/routes`             | Registered route table                   |
+| GET    | `/logs`               | Paginated log entries (up to 200)        |
+| GET    | `/emails`             | Captured emails (stripped HTML)          |
+| GET    | `/emails/:id/preview` | Email HTML preview                       |
+| GET    | `/traces`             | Request traces with log correlation      |
+| GET    | `/traces/:id`         | Trace detail with spans and related logs |
+| GET    | `/config`             | Debug store configuration                |
+| GET    | `/diagnostics`        | Provider diagnostics and status          |
 
 ### Dashboard routes
 
@@ -415,6 +417,7 @@ Registered when `dashboard` is enabled. Base path configurable via `dashboard.pa
 | GET    | `/api/traces/:id`          | Trace detail with spans           |
 | GET    | `/api/cache`               | Cache stats and key listing       |
 | GET    | `/api/cache/:key`          | Cache key detail                  |
+| DELETE | `/api/cache/:key`          | Delete a cache key                |
 | GET    | `/api/jobs`                | Job queue overview                |
 | GET    | `/api/jobs/:id`            | Job detail                        |
 | POST   | `/api/jobs/:id/retry`      | Retry a failed job                |
@@ -582,7 +585,7 @@ The React and Vue components share the same theme system as Edge. Dark/light pre
 - The dashboard page is large — lazy-loading helps but initial bundle may be significant
 - Some edge cases in custom pane rendering may not be fully covered yet
 - Error boundaries are minimal — a bad API response may cause a blank panel
-- Only tested with React 18+ and Vue 3.3+
+- Only tested with React 18/19 and Vue 3.3+
 
 Found a bug? Have feedback? [Open an issue](https://github.com/simulieren/adonisjs-server-stats/issues) — it helps a lot.
 
@@ -714,6 +717,12 @@ const result = await trace('organization.fetchMembers', async () => {
 
 If tracing is disabled or no request is active, `trace()` executes the function directly with no overhead.
 
+#### Related Logs
+
+When viewing a trace detail (either in the debug panel Timeline tab or the dashboard), related log entries are automatically correlated using the HTTP request ID (`ctx.request.id()`). Any logs emitted during the request appear in a "Related Logs" section below the waterfall chart.
+
+This works with both SQLite persistence (joins on `http_request_id`) and in-memory mode (scans the log file for matching `request_id` entries). No configuration needed — if your app uses AdonisJS request IDs, correlation happens automatically.
+
 ### Full-Page Dashboard
 
 The dashboard is a dedicated page that provides historical data, charts, query analysis, and integration inspectors -- all persisted to a local SQLite database. It's like having Laravel Telescope built into your dev toolbar.

package/dist/core/config-utils.d.ts

@@ -20,6 +20,14 @@ export interface FormattedValue {
  * Redacted objects have the shape `{ __redacted: true, display: string, value: string }`.
  */
 export declare function isRedactedValue(val: ConfigValue): val is RedactedValue;
+/**
+ * Check whether a config value is a plain config object (not null, not an
+ * array, not a redacted value). This consolidates the repeated
+ * null/typeof/array/redacted checks into a single reusable guard.
+ */
+export declare function isPlainConfigObject(val: ConfigValue): val is {
+    [key: string]: ConfigValue;
+};
 /**
  * Recursively flatten a nested config object into a list of dot-path entries.
  *

package/dist/core/constants.d.ts

@@ -8,3 +8,7 @@ export declare const DEBUG_REFRESH_MS = 3000;
 export declare const SLOW_DURATION_MS = 100;
 /** Duration (ms) above which a query/request is considered very slow. */
 export declare const VERY_SLOW_DURATION_MS = 500;
+/** Max data points in the sparkline history buffer per metric. */
+export declare const MAX_HISTORY = 60;
+/** Milliseconds after last success before connection is considered stale. */
+export declare const STALE_MS = 10000;

package/dist/core/dashboard-data-controller.d.ts

@@ -153,6 +153,22 @@ export declare class DashboardDataController {
      * Get the underlying `ApiClient` instance.
      */
     getClient(): ApiClient;
+    /** Whether this fetch call should be skipped entirely. */
+    private shouldSkipFetch;
+    /** Prepare abort controller, increment fetch ID, set loading state. */
+    private prepareFetch;
+    /** Execute the actual API fetch for the current section. */
+    private executeFetch;
+    /** Check if a response is stale (fetch ID mismatch or controller stopped). */
+    private isStaleResponse;
+    /** Check if an error should be silently ignored (abort or stale). */
+    private shouldIgnoreError;
+    /** Build query string from current controller state. */
+    private buildCurrentQueryString;
+    /** Apply a successful fetch result to the callbacks. */
+    private applyFetchResult;
+    /** Handle a fetch error (unauthorized, network, etc.). */
+    private handleFetchError;
     private startRefreshTimer;
     private stopRefreshTimer;
 }

package/dist/core/dashboard-data-helpers.d.ts

@@ -0,0 +1,12 @@
+import { PaginatedResponse } from './types.js';
+/**
+ * Check if a result is a paginated response (has data + meta).
+ */
+export declare function isPaginatedResult(result: unknown): result is {
+    data: unknown;
+    meta: PaginatedResponse<unknown>['meta'];
+};
+/**
+ * Check if an error is an AbortError (request was cancelled).
+ */
+export declare function isAbortedRequest(err: unknown, signal: AbortSignal): boolean;

package/dist/core/debug-data-controller.d.ts

@@ -86,4 +86,8 @@ export declare class DebugDataController<T = unknown> {
      */
     clearCache(): void;
     private fetchData;
+    /** Serve cached data if available. Returns true if cache hit. */
+    private serveFromCache;
+    /** Handle errors from fetchData. */
+    private handleFetchError;
 }

package/dist/core/define-config-helpers.d.ts

@@ -0,0 +1,25 @@
+import { DevToolbarOptions, ServerStatsConfig, ToolbarConfig } from '../types.js';
+/**
+ * Return the first defined (non-undefined) value from the arguments.
+ * Falls back to the last argument (the default).
+ */
+export declare function firstDefined<T>(...args: Array<T | undefined>): T;
+/**
+ * Apply a toolbar boolean or ToolbarConfig onto the result DevToolbarOptions.
+ */
+export declare function applyToolbarSetting(toolbar: boolean | ToolbarConfig, result: DevToolbarOptions): void;
+/**
+ * Apply a dashboard boolean or DashboardConfig onto the result DevToolbarOptions.
+ */
+export declare function applyDashboardSetting(dashboard: boolean | {
+    path?: string;
+    retentionDays?: number;
+}, result: DevToolbarOptions): void;
+/**
+ * Apply advanced config fields onto the result DevToolbarOptions.
+ */
+export declare function applyAdvancedConfig(advanced: NonNullable<ServerStatsConfig['advanced']>, result: DevToolbarOptions): void;
+/**
+ * Resolve transport from new and deprecated config options.
+ */
+export declare function resolveTransport(config: ServerStatsConfig): 'transmit' | 'none';

package/dist/core/feature-detect-helpers.d.ts

@@ -0,0 +1,36 @@
+import { FeatureFlags, FeatureConfig } from './types.js';
+/**
+ * Mapping from FeatureConfig keys to their default value.
+ * Used to data-drive the flattenFlags function.
+ */
+export declare const FEATURE_KEYS: Array<keyof Omit<FeatureConfig, 'customPanes'>>;
+/**
+ * Flatten a FeatureFlags response to a FeatureConfig using the
+ * data-driven FEATURE_KEYS list.
+ */
+export declare function flattenFlagsFromKeys(flags: FeatureFlags): FeatureConfig;
+/**
+ * Rules for mapping feature flags to metric groups in getVisibleMetricGroups.
+ */
+export interface FlagGroupRule {
+    flag: string;
+    group: string;
+}
+/**
+ * Which flags enable which metric groups.
+ * Some groups can be triggered by multiple flags (e.g. memory by process or system).
+ */
+export declare const FLAG_TO_GROUP: FlagGroupRule[];
+/**
+ * Rules for detecting metric groups from actual stats data.
+ * Each rule maps stat field names to a group name.
+ */
+export interface StatsGroupRule {
+    group: string;
+    fields: string[];
+}
+export declare const STATS_GROUP_RULES: StatsGroupRule[];
+/**
+ * Check if a value is a number (including 0).
+ */
+export declare function hasStatValue(v: unknown): v is number;

package/dist/core/field-resolvers.d.ts

@@ -0,0 +1,64 @@
+type Row = Record<string, unknown>;
+/**
+ * Resolve a field value from a row, trying multiple candidate key names.
+ * Returns the first truthy value found, or the fallback.
+ */
+export declare function resolveField<T>(row: Row, ...keys: string[]): T | undefined;
+/**
+ * Resolve a timestamp field. Tries `createdAt`, `created_at`, `timestamp`.
+ */
+export declare function resolveTimestamp(row: Row): string | number | undefined;
+/**
+ * Resolve a timestamp for jobs. Tries `timestamp`, `createdAt`, `processedAt`, `created_at`.
+ */
+export declare function resolveJobTimestamp(row: Row): string | number | undefined;
+/**
+ * Resolve HTTP status code. Tries `statusCode`, `status_code`.
+ */
+export declare function resolveStatusCode(row: Row): number | undefined;
+/**
+ * Resolve request duration. Tries `total_duration`, `totalDuration`, `duration`.
+ */
+export declare function resolveDuration(row: Row): number;
+/**
+ * Resolve span count. Tries `span_count`, `spanCount`.
+ */
+export declare function resolveSpanCount(row: Row): number;
+/**
+ * Resolve warning count. Tries `warning_count`, `warningCount`.
+ */
+export declare function resolveWarningCount(row: Row): number;
+/**
+ * Resolve email "from" address. Tries `from_addr`, `from`.
+ */
+export declare function resolveFromAddr(row: Row): string;
+/**
+ * Resolve email "to" address. Tries `to_addr`, `to`.
+ */
+export declare function resolveToAddr(row: Row): string;
+/**
+ * Resolve email CC address. Tries `cc`, `cc_addr`.
+ */
+export declare function resolveCcAddr(row: Row): string;
+/**
+ * Resolve attachment count. Tries `attachment_count`, `attachmentCount`.
+ */
+export declare function resolveAttachmentCount(row: Row): number;
+/**
+ * Resolve event name. Tries `event_name`, `eventName`, `event`.
+ */
+export declare function resolveEventName(row: Row): string;
+/**
+ * Resolve SQL method. Tries `method`, `sql_method`.
+ */
+export declare function resolveSqlMethod(row: Row): string;
+/**
+ * Resolve normalized SQL text. Tries `sqlNormalized`, `normalizedSql`, `sql_normalized`, `sql`.
+ */
+export declare function resolveNormalizedSql(row: Row): string;
+/**
+ * Resolve overview metric with snake_case fallback. Returns the camelCase
+ * value if present, otherwise converts the snake_case raw value to a number.
+ */
+export declare function resolveMetric(metrics: Row, camelKey: string, snakeKey: string): number;
+export {};

package/dist/core/formatters-helpers.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Create a compact preview of a string value.
+ * Truncates at 40 characters and wraps in quotes.
+ */
+export declare function previewString(value: string): string;
+/**
+ * Create a compact preview of an array value.
+ * Shows first 3 items with a summary for larger arrays.
+ *
+ * @param value  - The array to preview.
+ * @param maxLen - Maximum preview string length before falling back to a summary.
+ * @param recurse - Function to recursively preview nested values.
+ */
+export declare function previewArray(value: unknown[], maxLen: number, recurse: (v: unknown, max: number) => string): string;
+/**
+ * Create a compact preview of a plain object value.
+ * Shows first 4 key-value pairs with a summary for larger objects.
+ *
+ * @param value  - The object to preview.
+ * @param maxLen - Maximum preview string length before falling back to keys-only.
+ * @param recurse - Function to recursively preview nested values.
+ */
+export declare function previewObject(value: Record<string, unknown>, maxLen: number, recurse: (v: unknown, max: number) => string): string;

package/dist/core/formatters.d.ts

@@ -144,6 +144,21 @@ export declare function statusColor(statusCode: number): ThresholdColor;
  * @param ms - Duration in milliseconds.
  */
 export declare function durationSeverity(ms: number): 'normal' | 'slow' | 'very-slow';
+/**
+ * Return a CSS severity class for a duration value.
+ *
+ * Combines {@link durationSeverity} with a CSS-prefix to produce the
+ * appropriate class name.  Returns an empty string for normal durations.
+ *
+ * Examples (with default prefix `'ss-dash'`):
+ * - `> 500ms` -> `'ss-dash-very-slow'`
+ * - `> 100ms` -> `'ss-dash-slow'`
+ * - Otherwise -> `''`
+ *
+ * @param ms     - Duration in milliseconds.
+ * @param prefix - CSS class prefix (default `'ss-dash'`).
+ */
+export declare function durationClassName(ms: number, prefix?: string): string;
 /**
  * Truncate a request ID to a short preview.
  *

package/dist/core/index.d.ts

@@ -6,7 +6,7 @@ export type { ServerStats, MetricValue, ServerStatsConfig, ResolvedServerStatsCo
 export { getTheme, setTheme, toggleTheme, onThemeChange } from './theme.js';
 export { generateSparklinePoints, generateSparklinePath, generateGradientId, computeStats, buildSparklineData, } from './sparkline.js';
 export type { SparklineStats, SparklineData } from './sparkline.js';
-export { formatUptime, formatBytes, formatMb, formatCount, formatDuration, formatTime, timeAgo, formatStatNum, getThresholdColor, getThresholdColorInverse, getRatioColor, compactPreview, statusColor, durationSeverity, shortReqId, THRESHOLD_CSS_CLASS, THRESHOLD_HEX_FALLBACK, THRESHOLD_CSS_VAR, formatTtl, formatCacheSize, } from './formatters.js';
+export { formatUptime, formatBytes, formatMb, formatCount, formatDuration, formatTime, timeAgo, formatStatNum, getThresholdColor, getThresholdColorInverse, getRatioColor, compactPreview, statusColor, durationSeverity, durationClassName, shortReqId, THRESHOLD_CSS_CLASS, THRESHOLD_HEX_FALLBACK, THRESHOLD_CSS_VAR, formatTtl, formatCacheSize, } from './formatters.js';
 export { DEFAULT_PER_PAGE, buildQueryString, buildQueryParams, computePagination, parsePaginatedResponse, createPaginationState, createFilterState, createSortState, getPageNumbers, } from './pagination.js';
 export type { RawPaginatedResponse } from './pagination.js';
 export { fetchFeatures, detectFeatures, DEFAULT_FEATURES, getVisibleMetricGroups, detectMetricGroupsFromStats, } from './feature-detect.js';