Skip to content

feat: add diagnostic channels for request lifecycle#7171

Open
OussemaNehdi wants to merge 1 commit intoexpressjs:masterfrom
OussemaNehdi:feat/diagnostics-channel-request-lifecycle
Open

feat: add diagnostic channels for request lifecycle#7171
OussemaNehdi wants to merge 1 commit intoexpressjs:masterfrom
OussemaNehdi:feat/diagnostics-channel-request-lifecycle

Conversation

@OussemaNehdi
Copy link
Copy Markdown

Summary

Adds diagnostics_channel support for Express request lifecycle, as requested
in #6353. This enables APM and monitoring tools to observe request processing
without monkey-patching.

Channels

Channel When Message
express.request.start Before routing begins { req, res }
express.request.finish Response fully sent { req, res }
express.request.error Connection error (ECONNRESET, etc.) { req, res, error }

Design decisions

  • Zero overhead: Every publish() call is guarded by hasSubscribers,
    so there is no performance cost when no diagnostic tool is listening
  • on-finished for completion tracking: Uses the existing on-finished
    dependency (already used by res.sendFile) to detect when the response is
    fully sent, covering all code paths including streaming and error responses
  • Complements feat: add diagnostics_channel support for app initialization #7041: PR feat: add diagnostics_channel support for app initialization #7041 adds an express.initialization channel for
    app startup. This PR covers the request lifecycle, which is the primary use
    case for APM tools like OpenTelemetry and Datadog

Example usage

const dc = require('node:diagnostics_channel');

dc.subscribe('express.request.start', ({ req, res }) => {
  req._startTime = performance.now();
});

dc.subscribe('express.request.finish', ({ req, res }) => {
  const duration = performance.now() - req._startTime;
  console.log(`${req.method} ${req.url} ${res.statusCode} ${duration.toFixed(1)}ms`);
});

Test plan

- express.request.start publishes before routing with { req, res }
- express.request.start fires for every request (verified with 2 sequential requests)
- No overhead when no subscribers (request works normally)
- express.request.finish fires after response with correct statusCode
- express.request.finish fires for 500 error responses
- express.request.finish fires for 404 responses
- express.request.error does NOT fire on normal responses
- start always fires before finish (ordering verified)
- All 1257 tests pass (1252 existing + 5 new)
- ESLint clean 

Add Node.js diagnostics_channel support for observing Express request
processing. This enables APM tools, monitoring systems, and
instrumentation libraries to hook into Express without monkey-patching.

Channels added:
  - express.request.start   — published before routing begins
  - express.request.finish  — published when the response is fully sent
  - express.request.error   — published on connection-level errors

All channels use hasSubscribers guards so there is zero overhead when
no diagnostic tool is listening.

Closes expressjs#6353
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant