@rantingjs/inspector

A debug assistant for ranting apps: it records the requests, commands, scheduled tasks and queued jobs the app runs, and everything they did (queries, exceptions, logs, mail, notifications, events, cache and Redis calls, outgoing HTTP requests, gate checks, models, views, dumps), and shows them in a dashboard at /inspector.

bun add --dev @rantingjs/inspector
bunx ranting install @rantingjs/inspector --skip-add   # src/config/inspector.ts
bunx ranting migrate                                 # inspector_entries, inspector_entries_tags, inspector_monitoring

The app needs DatabaseModule.

Who may open it

Everyone while app.env is local. Elsewhere whoever the viewInspector ability allows: nobody until the app defines it (nor in an app without AuthModule). Define it where the app starts:

constructor(gate: Gatekeeper) {
  gate.define('viewInspector', (user: User) => ['[email protected]'].includes(user.email));
}

Guests are refused without asking it, and the gate's before callbacks count. An authorize option ((request) => boolean) replaces the whole rule, local included.

The dashboard

A sidebar lists every kind of entry: Requests, Commands, Schedule, Jobs, then Batches, Cache, Dumps, Events, Exceptions, Gates, HTTP Client, Logs, Mail, Models, Notifications, Queries, Redis and Views. Each list loads new entries as they come in (or offers to, with auto-load off), pages back with "Load Older Entries" and filters by tag (/ focuses the search). An entry's page shows its details, its tags, the signed-in user, and for a request, command or job everything else it recorded, in tabs.

The header pauses and resumes recording (for every process, through the cache), clears every entry (Cmd/Ctrl+K too), switches auto-loading, and opens Monitoring, where tags such as Order:15 or Auth:3 are watched.

Config

src/config/inspector.ts (bunx ranting publish @rantingjs/inspector):

| Key | Default | | |---|---|---| | enabled | INSPECTOR_ENABLED, true | Off: nothing is recorded and the dashboard is gone. | | path | INSPECTOR_PATH, inspector | Where the dashboard and its API (/inspector/inspector-api) live. | | domain | INSPECTOR_DOMAIN, any | Serve the dashboard on this domain only (404 on others). | | storage.connection | INSPECTOR_DB_CONNECTION, the default | The connection of the inspector tables. | | onlyPaths / ignorePaths | [] / ['metrics*', '.well-known*'] | Which request paths are recorded (* matches anything). | | ignoreCommands | [] | Commands during which nothing is recorded (workers record each job instead of themselves). | | watchers | all on | One key per watcher, true/false or options; each has an INSPECTOR_<NAME>_WATCHER switch. | | filter | everything locally, else failures | Which entries are kept (see below). | | filterBatch, tag | unset | Decide on a whole batch; add tags to entries. | | hideRequestHeaders | authorization (+ cookie, set-cookie, CSRF headers outside local) | Shown as ********. | | hideRequestParameters | password, password_confirmation (+ _token outside local) | Shown as ********, dot notation for nested ones. | | hideResponseParameters | [] | | | recordFrameworkEvents | false | Show the framework's own events on the Events screen too. | | night | false | The dark theme. | | avatar, authorize | Gravatar, unset | The signed-in user's picture; who may open the dashboard instead of the rule above. |

Watcher options: cache.hidden / cache.ignore (key patterns), clientRequest.ignoreHosts / sizeLimit, command.ignore, dump.always, event.ignore, gate.ignoreAbilities, log.level (error by default), model.hydrations / model.ignore, query.slow (100 ms) / ignorePaths, request.sizeLimit (64 KB) / ignoreHttpMethods / ignoreStatusCodes.

The default filter keeps everything in the local environment; elsewhere only reported exceptions, failed requests (5xx) and jobs, scheduled tasks and entries carrying a monitored tag:

filter: (entry) => local || entry.isReportableException() || entry.isFailedRequest() || entry.isFailedJob() || entry.isScheduledTask() || entry.hasMonitoredTag(),

How it records

• Everything one request, command or job records is stored together when it ends, as one batch, through the running transaction if there is one. A queued job's entry is recorded when it is dispatched (pending) and updated by the worker that runs it (processed, or failed with its exception and the failed tag).
• Tags come by themselves: Auth:<id> for the signed-in user, Order:15 for the models an event, job, mail, notification or exception carries (an object's own tags() method wins), the recipients of mail, the host of an outgoing request, slow for slow queries.
• Queries show the line of the app's code that ran them, when the stack still has it; the inspector's own queries are left out.
• Exceptions are grouped by the place they were thrown: the list shows each once with its count, and an entry can be marked resolved.
• dump(value) (from @rantingjs/framework) prints to the console; while the Dumps screen is open (or with dump.always) dumps go there instead.
• Files served from public/ are not requests of the app: they are left out.

Commands

bunx ranting inspector:list [type] [--tag Auth:1] [--limit 20] [--before 1234] [--json]
bunx ranting inspector:show <id | latest | latest:query> [--full] [--json]   # an entry and what its batch did
bunx ranting inspector:prune --hours 48 [--keep-exceptions]                     # older than 48 hours (24 by default)
bunx ranting inspector:clear
bunx ranting inspector:pause / inspector:resume

Schedule pruning in src/schedule.ts: schedule.command('inspector:prune').daily().