How It Works

When start() runs, ServerDevTools registers OpenTelemetry instrumentations for HTTP, Express, MongoDB, PostgreSQL, MySQL2, ioredis, and Undici. It also installs the OpenTelemetry ESM loader hook once per process.

Request lifecycle

1. An incoming HTTP span becomes the root of a request trace.
2. Framework, database, Redis, and outbound HTTP spans become child operations when they run within that request context.
3. The exporter writes spans and trace summaries to a local SQLite database.
4. The middleware serves /_devtools and captures response bodies and optional user context for application requests.

Why preload matters

Instrumentation must be active before instrumented libraries are imported. Use --import ./server-devtools.ts or NODE_OPTIONS='--import ./server-devtools.js' so the SDK starts before application dependencies load. Already-loaded modules cannot be instrumented retroactively.

Storage

The SDK creates server-devtools.db in the process working directory. SQLite stores spans, trace summaries, request metadata, dashboard sessions, and outbound HTTP details. Call shutdown() during controlled process teardown when you need to close the SDK cleanly.

What can be captured

Depending on the instrumented library and request context, traces can include request and response metadata, selected headers and bodies, middleware and handler spans, MongoDB/PostgreSQL/MySQL/Redis operations, outbound native HTTP/HTTPS and Undici requests, errors, timings, and optional current-user data.

Sensitive application data can therefore be captured. Header redaction covers configured HTTP header values before persistence, including matching HTTP header span attributes; it does not currently cover bodies, URL/query values, or arbitrary span attributes. Configure the SDK deliberately and do not treat the dashboard as a complete redaction boundary.

Retention and deletion

Trace data remains in the SQLite database until it is deleted from the dashboard or the database is removed. The SDK does not automatically expire or prune trace history. Dashboard sessions have their own expiry, but that does not delete trace data.

Performance considerations

Instrumentation creates spans and persists them while requests run. Capturing bodies, database operations, and outbound calls adds copying, buffering, parsing, and persistence work proportional to request volume and payload size; optional field encryption adds processing. Native outbound request and response body capture skips bodies above 256 KiB rather than truncating them, while inbound response and fetch capture have no SDK byte limit. No reproducible benchmark is published, so measure overhead in the environment and workload where you plan to use the SDK.