Core concepts

Sessions

A session groups events for one HTTP request (or a short-lived orphan batch for background work).

Field	Meaning
`id`	Unique session id
`kind`	`request` or `orphan`
`method` / `url`	From the first `req` event
`statusCode` / `durationMs`	From `res`
`active`	Still open until response finishes

Concurrent requests get different session ids via AsyncLocalStorage. There is no process-global “current session” static.

Events (`TraceEvent`)

Every stored server event has:

{
  id, type, sessionId, timestamp, sequence, appName, environment, payload;
}

sequence is monotonic per process and powers polling (sinceSequence) and SSE.

Event types

Type	Role
`req`	Incoming request snapshot
`res`	Response status, headers, elapsed time
`functionCall`	Wrapped function I/O — with `phase: 'enter' \| 'exit'`
`middlewareCall`	Middleware name
`reqModified` / `resModified`	Field mutations (`source: 'app' \| 'framework'`)
`error`	Request-scoped errors
`dbQuery`	ORM/driver query nested under the issuing function

Double-point paths

Wrappers emit enter when a function is called and exit when it returns. The UI path graph therefore reads:

request → controller↓ → service↓ → db query → service↑ → controller↑ → response

instead of only deepest-first exit events. Database calls are dbQuery events with the same parentName / executionOrder as functions, so the UI call tree shows controller → service → query.

Redaction

Before store.record, payloads are walked and sensitive keys replaced with ***:

authorization, cookie, password, token, api_key, …

Add more via redactKeys in config.

Store

In-memory ring buffer:

maxSessions (default 200)
maxEventsPerSession (default 500)
maxTotalEvents (default 10_000)

Subscribers power the SSE stream at {basePath}/api/stream.

UI base path

Default /__idebug. Hosts:

Static SPA (@idebug/ui dist)
REST + SSE under /api/*

See HTTP API.

Database queries

@idebug/db emits dbQuery events on the same session. Wrap ORM clients (instrumentDrizzle, instrumentPrisma, …) and wrap the functions that call them — queries become leaves of that call tree. Live demo: sample-db-api on port 3003. Guide: Database queries.

Configuration Overview