Devtools

Two modes:

• Inspector — captures individual requests, queries, exceptions, logs, and jobs. Every entry is stored in full and grouped into batches so you can trace a single request across all its queries, logs, and side effects.
• Metrics — records pre-aggregated performance data (slow requests, slow queries) in time buckets for at-a-glance monitoring without scanning raw entries.

Installation

bun add @strav/devtools
bun strav install devtools

• config/devtools.ts — toggle collectors, recorders, thresholds.
• database/schemas/devtools_entries.ts — the entries table schema.
• database/schemas/devtools_aggregates.ts — the aggregates table schema.

Setup

Register the provider

import { DevtoolsProvider } from '@strav/devtools'

app.use(new DevtoolsProvider())

That's it. The provider automatically:

• Registers DevtoolsManager as a singleton
• Creates the storage tables
• Adds the request-tracking middleware to the router
• Mounts the dashboard at /_devtools
• Tears down collectors on shutdown

Options:

To add a custom dashboard auth guard:

app.use(new DevtoolsProvider({
  guard: (ctx) => ctx.get('user')?.isAdmin === true,
}))

To disable auto-registration of middleware or dashboard (for manual control):

app.use(new DevtoolsProvider({ middleware: false, dashboard: false }))

Manual setup

If you prefer full control over middleware and route placement:

import DevtoolsManager from '@strav/devtools'
import { devtools } from '@strav/devtools'
import { registerDashboard } from '@strav/devtools/dashboard/routes'

// Register and resolve the manager
app.singleton(DevtoolsManager)
app.resolve(DevtoolsManager)

// Create tables
await devtools.ensureTables()
// Or via CLI: bun strav devtools:setup

// Add request-tracking middleware
router.use(devtools.middleware())

// Mount the dashboard
registerDashboard(router)

The middleware captures request/response data, sets a batch ID on the context, and triggers query collection via a SQL proxy. All other collectors (exceptions, logs, jobs) activate automatically through Emitter events.

Configure

import { env } from '@strav/kernel'

export default {
  enabled: env('DEVTOOLS_ENABLED', 'true').bool(),

  routes: {
    aliases: {
      dashboard: 'devtools.dashboard',  // Dashboard routes
      api: 'devtools.api'              // API routes
    },
    subdomain: undefined               // Optional subdomain
  },

  storage: {
    pruneAfter: 24, // hours
  },

  collectors: {
    request: { enabled: true, sizeLimit: 64 },
    query: { enabled: true, slow: 100 },
    exception: { enabled: true },
    log: { enabled: true, level: 'debug' },
    job: { enabled: true },
  },

  recorders: {
    slowRequests: { enabled: true, threshold: 1000, sampleRate: 1.0 },
    slowQueries: { enabled: true, threshold: 1000, sampleRate: 1.0 },
  },
}

Configuration reference

Collectors

Collectors capture individual events and store them as entries.

Request

collectors: {
  request: { enabled: true, sizeLimit: 64 },
}

Query

collectors: {
  query: { enabled: true, slow: 100 },
}

Exception

Log

collectors: {
  log: { enabled: true, level: 'debug' },
}

Job

Recorders

Recorders aggregate metrics into time buckets for the dashboard. They don't store individual entries — they update counters and extreme values.

Slow Requests

recorders: {
  slowRequests: { enabled: true, threshold: 1000, sampleRate: 1.0 },
}

Slow Queries

recorders: {
  slowQueries: { enabled: true, threshold: 1000, sampleRate: 1.0 },
}

sampleRate

Batch correlation

Downstream code can read the batch ID:

const batchId = ctx.get('_devtools_batch_id')

devtools helper

import { devtools } from '@strav/devtools'

Querying entries

// List recent entries (all types)
const entries = await devtools.entries()

// Filter by type
const requests = await devtools.entries('request', 50)
const queries = await devtools.entries('query', 100, 0)

// Find by UUID
const entry = await devtools.find('550e8400-e29b-41d4-a716-446655440000')

// Find all entries in a batch
const batch = await devtools.batch(entry.batchId)

// Search by tag
const slow = await devtools.byTag('slow')
const user42 = await devtools.byTag('user:42')

// Count
const total = await devtools.count()
const exceptions = await devtools.count('exception')

Querying metrics

import { PERIODS } from '@strav/devtools'

// Time-series data
const hourly = await devtools.aggregates('slow_request', PERIODS.ONE_HOUR, 'count')
const daily = await devtools.aggregates('slow_query', PERIODS.ONE_DAY, 'max')

// Top offenders
const topSlow = await devtools.topKeys('slow_request', PERIODS.ONE_HOUR, 'count', 10)

Pruning

// Prune entries older than the configured pruneAfter value
const { entries, aggregates } = await devtools.prune()

// Or specify hours explicitly
const result = await devtools.prune(48)

Dashboard

Clicking any entry opens a detail view with full content and all related batch entries. The dashboard auto-refreshes every 5 seconds.

Dashboard auth

To allow access in production, pass a custom guard:

import { registerDashboard } from '@strav/devtools/dashboard/routes'

registerDashboard(router, (ctx) => {
  const user = ctx.get('user')
  return user?.isAdmin === true
})

You can also use the middleware directly:

import { dashboardAuth } from '@strav/devtools/dashboard/middleware'

router.group({
  prefix: '/_devtools',
  middleware: [dashboardAuth((ctx) => ctx.get('user')?.isAdmin)]
}, (r) => {
  // custom routes
})

CLI commands

devtools:setup

Create the storage tables (idempotent):

bun strav devtools:setup

devtools:prune

Delete old entries and aggregates:

bun strav devtools:prune
bun strav devtools:prune --hours 48

• --hours — Delete data older than this many hours (default: 24).

Dashboard routes and API

The dashboard includes both frontend routes and a REST API, organized with configurable route aliases for easy programmatic access.

Dashboard routes (devtools.dashboard alias)

API routes (devtools.api alias)

Using named routes

With route aliases configured, you can access the devtools API programmatically:

import { route, routeUrl } from '@strav/http'

// Get recent entries
const entries = await route('devtools.api.entries', {
  params: { type: 'request', limit: 50 }
})

// Get a specific entry
const entry = await route('devtools.api.entry', {
  params: { uuid: '550e8400-e29b-41d4-a716-446655440000' }
})

// Get all entries in a batch
const batchEntries = await route('devtools.api.entry_batch', {
  params: { uuid: entry.uuid }
})

// Get entries by tag
const slowEntries = await route('devtools.api.entries_by_tag', {
  params: { tag: 'slow' }
})

// Get metrics data
const metrics = await route('devtools.api.metrics', {
  params: { type: 'slow_request' },
  query: { period: '3600', aggregate: 'count', limit: '24' }
})

// Get top performers
const topQueries = await route('devtools.api.metrics_top', {
  params: { type: 'slow_query' },
  query: { period: '3600', aggregate: 'count', limit: '10' }
})

// Get stats
const stats = await route('devtools.api.stats')

// Prune old data
await route('devtools.api.prune_entries', {
  method: 'DELETE',
  query: { hours: '48' }
})

// Generate dashboard URL
const dashboardUrl = routeUrl('devtools.dashboard.home')

Custom route aliases

You can customize the route aliases in your devtools configuration:

// config/devtools.ts
export default {
  routes: {
    aliases: {
      dashboard: 'debug.dashboard',  // Routes: debug.dashboard.home
      api: 'debug.api'              // Routes: debug.api.entries, etc.
    }
  }
}

// Or mount on a subdomain
export default {
  routes: {
    subdomain: 'devtools'  // Accessible at devtools.example.com
  }
}

Entry types

type EntryType =
  | 'request'
  | 'query'
  | 'exception'
  | 'log'
  | 'job'
  | 'cache'     // reserved for future use
  | 'mail'      // reserved for future use
  | 'event'     // reserved for future use
  | 'schedule'  // reserved for future use

Aggregate functions

type AggregateFunction = 'count' | 'min' | 'max' | 'sum' | 'avg'

Aggregate periods

import { PERIODS } from '@strav/devtools'

PERIODS.ONE_HOUR    // 3600
PERIODS.SIX_HOURS   // 21600
PERIODS.ONE_DAY     // 86400
PERIODS.SEVEN_DAYS  // 604800

Database tables

_strav_devtools_entries

_strav_devtools_aggregates

Zero-cost when disabled

if (Emitter.listenerCount('log:entry') === 0) return

Error handling

import { DevtoolsError } from '@strav/devtools'

Testing

Disable devtools in tests to avoid recording test traffic:

.env.test
DEVTOOLS_ENABLED=false

Full setup example

import { app } from '@strav/kernel'
import { DevtoolsProvider } from '@strav/devtools'

app.use(new DevtoolsProvider({
  guard: (ctx) => {
    if (process.env.NODE_ENV === 'production') {
      const user = ctx.get('user')
      return user?.isAdmin === true
    }
    return true
  },
}))

await app.start()