server-devtools 0.1.3 → 0.1.5

package/README.md

@@ -3,7 +3,7 @@
 **Chrome DevTools for your backend.**
 
 ServerDevTools is an embeddable backend inspector for Node.js
-applications.
+applications: **Chrome DevTools for your Node.js backend.**
 
 It gives you a live dashboard for inspecting:
 
@@ -16,6 +16,9 @@ It gives you a live dashboard for inspecting:
 -   database operations
 -   errors
 -   timing
+-   current/authenticated user context
+-   server-side request search
+-   request filtering by HTTP method and status
 
 Instead of jumping between logs, traces, and multiple observability
 tools, ServerDevTools lets you inspect what your backend is doing from
@@ -83,6 +86,9 @@ full production observability platforms.
 npm install server-devtools
 ```
 
+ServerDevTools includes the supported OpenTelemetry instrumentation libraries;
+you do not need to install the database instrumentation packages separately.
+
 ------------------------------------------------------------------------
 
 ## Quick Start
@@ -159,6 +165,18 @@ server.listen(3000);
 tsx watch --import ./server-devtools.ts src/main.ts
 ```
 
+`await devtools.start()` automatically registers OpenTelemetry's ESM loader hook
+once per process before starting the OpenTelemetry SDK. Keep startup in the
+preload module and let it complete before application dependencies load, including
+normal Redis (ioredis) imports. Already-loaded dependencies cannot be instrumented
+retroactively.
+
+The installed OpenTelemetry hook exports asynchronous loader hooks, which require
+`node:module.register()`. Newer Node.js versions deprecate this API; its
+`registerHooks()` replacement takes synchronous hooks and cannot directly load
+OpenTelemetry's `hook.mjs`. This compatibility requirement does not change the
+startup command or configuration.
+
 The application can import the same instance normally and mount it in Express:
 
 ```ts
@@ -440,16 +458,33 @@ http://localhost:3000
 
 ## Current Support
 
-Initial support focuses on Node.js applications:
+ServerDevTools currently supports:
 
--   Node.js HTTP
+-   Node.js
 -   Express
 -   NestJS middleware and error interception
--   MongoDB operations
+-   MongoDB
+-   PostgreSQL through `pg`
+-   MySQL through `mysql2`
+-   Redis (ioredis)
 -   native HTTP/HTTPS and fetch/Undici requests, including headers and bodies
+-   request search and filtering by HTTP method and status
+-   current/authenticated user context when supplied by the application
 -   OpenTelemetry-powered activity capture
 
-Support will expand as the project develops.
+### Database tracing
+
+Supported database operations automatically appear inside the request
+execution trace when using these supported drivers:
+
+-   MongoDB
+-   PostgreSQL (`pg`)
+-   MySQL (`mysql2`)
+-   Redis (ioredis)
+
+Redis command spans include command inspection, arguments, timings, request
+links, and command errors. Redis (ioredis) support has been verified in
+Express and NestJS applications, including pipelines and transactions.
 
 ------------------------------------------------------------------------
 
@@ -486,40 +521,12 @@ Expect APIs and configuration to evolve before `1.0`.
 
 ------------------------------------------------------------------------
 
-## Roadmap
-
-Near-term:
-
--   [x] HTTP request capture
--   [x] Request headers
--   [x] Query parameters
--   [x] Route parameters
--   [x] Request body
--   [x] HTTP response status
--   [x] Response headers
--   [x] Response body
--   [x] Execution tree
--   [x] Native HTTP/HTTPS and fetch/Undici inspection
--   [x] MongoDB inspection
--   [x] Error inspection
--   [x] NestJS integration and error interception
--   [x] Encryption at rest for selected fields
--   [ ] Request/response redaction
--   [ ] Body-size limits
--   [ ] Production-safe configuration
--   [ ] Broader NestJS compatibility
--   [x] Static dashboard packaging
-
-Future ideas:
-
--   Redis
--   PostgreSQL
--   MySQL
--   additional Node frameworks
--   trace filtering
--   request search
--   configurable retention
--   multi-instance support
+## Coming next
+
+Planned, not yet available:
+
+-   Configurable trace storage, including storing ServerDevTools data through
+    user-configured storage instead of only the default local SQLite storage
 
 ------------------------------------------------------------------------
 
@@ -558,6 +565,19 @@ The goal is simple:
 
 The project is still early.
 
+### Redis (ioredis) integration tests
+
+The ioredis integration tests require a disposable Redis instance. Run
+them with its connection URL:
+
+```sh
+REDIS_TEST_URL=redis://127.0.0.1:6379 npx tsx --test tests/ioredis-integration.test.ts
+```
+
+When `REDIS_TEST_URL` is not set, the Redis integration tests are
+reported as skipped. The tests use isolated keys and clean up their
+clients and data.
+
 Issues, ideas, bug reports, and contributions are welcome.
 
 ------------------------------------------------------------------------