On this page

Diagnostics Channel Support

History
Stability: 1Experimental

Undici is instrumented with Node.js' built-in diagnostics_channel module. It is the preferred way to observe undici's internal behaviour without patching the library, and it backs the human-readable debug logs.

Each integration point is exposed as a named channel. To observe an event, obtain the channel by name and subscribe to it:

import diagnosticsChannel from 'node:diagnostics_channel'

diagnosticsChannel.channel('undici:request:create').subscribe(({ request }) => {
  console.log(request.method, request.origin, request.path)
})
JavaScript

The message published to a channel is always a single object whose shape depends on the channel. The sections below describe every channel and the object it publishes. Subscriber callbacks run synchronously inside undici, so they should be fast and must not throw.

The same request object is shared across all undici:request:* channels for a given request, so a subscriber may correlate the lifecycle of one request by identity.

E

undici:request:create

History

Published when a new outgoing request is created, before it is dispatched.

Attributes
message:<Object>
request:<Object>
The request being created.
origin:<string> | <URL>
The origin the request is sent to.
completed:<boolean>
Whether the request has completed.  false at this point.
method:<string>
The HTTP method, e.g.  'GET' .
path:<string>
The request path, including any query string.
headers:<string>
[] The request headers as a flat array of strings, alternating between header name and value.

The request object also exposes an addHeader(name, value) method that appends a header before the request is sent.

import diagnosticsChannel from 'node:diagnostics_channel'

diagnosticsChannel.channel('undici:request:create').subscribe(({ request }) => {
  console.log('origin', request.origin)
  console.log('completed', request.completed)
  console.log('method', request.method)
  console.log('path', request.path)
  console.log('headers', request.headers)
  request.addHeader('hello', 'world')
})
JavaScript

A request is only loosely bound to a given socket at this stage.

E

undici:request:bodyChunkSent

History

Published each time a chunk of the request body is written to the socket.

Attributes
message:<Object>
request:<Object>
The same object published by  'undici:request:create' .
chunk:<Uint8Array> | <string>
The body chunk being sent.
import diagnosticsChannel from 'node:diagnostics_channel'

diagnosticsChannel.channel('undici:request:bodyChunkSent').subscribe(({ request, chunk }) => {
  console.log('sent', chunk.length, 'bytes')
})
JavaScript
E

undici:request:bodySent

History

Published after the request body has been fully sent.

Attributes
message:<Object>
request:<Object>
The same object published by  'undici:request:create' .
import diagnosticsChannel from 'node:diagnostics_channel'

diagnosticsChannel.channel('undici:request:bodySent').subscribe(({ request }) => {
  // request is the same object as in 'undici:request:create'
})
JavaScript
E

undici:request:headers

History

Published after the response headers have been received.

Attributes
message:<Object>
request:<Object>
The same object published by  'undici:request:create' .
response:<Object>
The response being received.
statusCode:<number>
The HTTP status code.
statusText:<string>
The HTTP status message.
headers:<Buffer>
[] The raw response headers as an array of buffers, alternating between header name and value.
import diagnosticsChannel from 'node:diagnostics_channel'

diagnosticsChannel.channel('undici:request:headers').subscribe(({ request, response }) => {
  console.log('statusCode', response.statusCode)
  console.log(response.statusText)
  console.log(response.headers.map((x) => x.toString()))
})
JavaScript
E

undici:request:bodyChunkReceived

History

Published each time a chunk of the response body is received.

Attributes
message:<Object>
request:<Object>
The same object published by  'undici:request:create' .
chunk:<Buffer>
The body chunk that was received.
import diagnosticsChannel from 'node:diagnostics_channel'

diagnosticsChannel.channel('undici:request:bodyChunkReceived').subscribe(({ request, chunk }) => {
  console.log('received', chunk.length, 'bytes')
})
JavaScript
E

undici:request:trailers

History

Published after the response body and trailers have been received, that is, once the response has fully completed.

Attributes
message:<Object>
request:<Object>
The same object published by  'undici:request:create' . request.completed is now true .
trailers:<Buffer>
[] The raw response trailers as an array of buffers, alternating between header name and value.
import diagnosticsChannel from 'node:diagnostics_channel'

diagnosticsChannel.channel('undici:request:trailers').subscribe(({ request, trailers }) => {
  console.log('completed', request.completed)
  console.log(trailers.map((x) => x.toString()))
})
JavaScript
E

undici:request:error

History

Published when the request is about to error, before the error is surfaced to the caller.

Attributes
message:<Object>
request:<Object>
The same object published by  'undici:request:create' .
error:<Error>
The error the request is about to fail with.
import diagnosticsChannel from 'node:diagnostics_channel'

diagnosticsChannel.channel('undici:request:error').subscribe(({ request, error }) => {
  console.error(error)
})
JavaScript

Published immediately before the first byte of the request is written to the socket. The headers are published exactly as they will be sent to the server, in raw form.

Attributes
message:<Object>
request:<Object>
The same object published by  'undici:request:create' .
headers:<string>
The request headers as a single raw string, with lines separated by  \r\n .
socket:<net.Socket>
The socket the request is written to.
import diagnosticsChannel from 'node:diagnostics_channel'

diagnosticsChannel.channel('undici:client:sendHeaders').subscribe(({ request, headers, socket }) => {
  console.log(`Full headers list: ${headers.split('\r\n')}`)
})
JavaScript

Published before a new connection is opened for any request. This event cannot be attributed to a specific request, because connections are pooled and shared.

Attributes
message:<Object>
connectParams:<Object>
The parameters used to open the connection.
host:<string>
The connection host, including the port if present.
hostname:<string>
The connection hostname.
protocol:<string>
The protocol, e.g.  'https:' .
port:<string>
The connection port.
servername:<string> | <null>
The TLS server name, or  null .
connector:<Function>
The function that creates the socket.
import diagnosticsChannel from 'node:diagnostics_channel'

diagnosticsChannel.channel('undici:client:beforeConnect').subscribe(({ connectParams, connector }) => {
  const { host, hostname, protocol, port, servername } = connectParams
  // connector is the function that creates the socket
})
JavaScript

Published after a connection has been successfully established.

Attributes
message:<Object>
socket:<net.Socket>
The newly connected socket.
connectParams:<Object>
The parameters used to open the connection. See  'undici:client:beforeConnect' for the field descriptions.
connector:<Function>
The function that created the socket.
import diagnosticsChannel from 'node:diagnostics_channel'

diagnosticsChannel.channel('undici:client:connected').subscribe(({ socket, connectParams, connector }) => {
  const { host, hostname, protocol, port, servername } = connectParams
})
JavaScript

Published when a connection could not be established.

Attributes
message:<Object>
error:<Error>
The error that prevented the connection.
socket:<net.Socket>
The socket associated with the failed attempt.
connectParams:<Object>
The parameters used to open the connection. See  'undici:client:beforeConnect' for the field descriptions.
connector:<Function>
The function that created the socket.
import diagnosticsChannel from 'node:diagnostics_channel'

diagnosticsChannel.channel('undici:client:connectError').subscribe(({ error, socket, connectParams, connector }) => {
  console.error(`Connect failed with ${error.message}`)
})
JavaScript
E

undici:websocket:open

History

Published after a WebSocket has successfully connected to a server.

Attributes
message:<Object>
address:<Object> | <null>
The remote socket address, as returned by  socket.address() , or null if it cannot be determined. When present, it contains address , family , and port .
protocol:<string>
The negotiated subprotocol.
extensions:<string>
The negotiated extensions.
websocket:<WebSocket>
The  WebSocket instance.
handshakeResponse:<Object>
The HTTP response that upgraded the connection.
status:<number>
The HTTP status code:  101 for an HTTP/1.1 upgrade, or 200 for an HTTP/2 extended CONNECT .
statusText:<string>
The HTTP status message:  'Switching Protocols' for HTTP/1.1, and commonly 'OK' for HTTP/2.
headers:<Object>
The response headers from the server. The  upgrade and connection headers are only present for HTTP/1.1 handshakes.
import diagnosticsChannel from 'node:diagnostics_channel'

diagnosticsChannel.channel('undici:websocket:open').subscribe(({
  address,
  protocol,
  extensions,
  websocket,
  handshakeResponse
}) => {
  console.log(address)
  console.log(protocol)
  console.log(extensions)
  console.log(handshakeResponse.status)
  console.log(handshakeResponse.headers)
})
JavaScript
E

undici:websocket:close

History

Published after the WebSocket connection has closed.

Attributes
message:<Object>
websocket:<WebSocket>
The  WebSocket instance.
code:<number>
The closing status code.
reason:<string>
The closing reason.
import diagnosticsChannel from 'node:diagnostics_channel'

diagnosticsChannel.channel('undici:websocket:close').subscribe(({ websocket, code, reason }) => {
  console.log(code, reason)
})
JavaScript
E

undici:websocket:socket_error

History

Published when the underlying WebSocket socket experiences an error. Unlike the other WebSocket channels, the published message is the error itself.

Attributes
error:<Error>
The socket error.
import diagnosticsChannel from 'node:diagnostics_channel'

diagnosticsChannel.channel('undici:websocket:socket_error').subscribe((error) => {
  console.error(error)
})
JavaScript
E

undici:websocket:ping

History

Published after the client receives a ping frame.

Attributes
message:<Object>
payload:<Buffer> | <undefined>
The optional application data carried by the frame.
websocket:<WebSocket>
The  WebSocket instance.
import diagnosticsChannel from 'node:diagnostics_channel'

diagnosticsChannel.channel('undici:websocket:ping').subscribe(({ payload, websocket }) => {
  console.log(payload)
})
JavaScript
E

undici:websocket:pong

History

Published after the client receives a pong frame.

Attributes
message:<Object>
payload:<Buffer> | <undefined>
The optional application data carried by the frame.
websocket:<WebSocket>
The  WebSocket instance.
import diagnosticsChannel from 'node:diagnostics_channel'

diagnosticsChannel.channel('undici:websocket:pong').subscribe(({ payload, websocket }) => {
  console.log(payload)
})
JavaScript
E

undici:proxy:connected

History

Published after a ProxyAgent has established a tunnel to the proxy server.

Attributes
message:<Object>
socket:<net.Socket>
The socket connected to the proxy.
connectParams:<Object>
The parameters used to establish the tunnel.
origin:<string> | <URL>
The proxy origin.
port:<string>
The proxy port.
path:<string>
The requested tunnel target, e.g.  'example.com:443' .
signal:<AbortSignal> | <undefined>
The signal associated with the request.
headers:<Object>
The headers sent in the  CONNECT request.
servername:<string> | <undefined>
The TLS server name used for the proxy.
import diagnosticsChannel from 'node:diagnostics_channel'

diagnosticsChannel.channel('undici:proxy:connected').subscribe(({ socket, connectParams }) => {
  const { origin, port, path, signal, headers, servername } = connectParams
})
JavaScript
E

undici:request:pending-requests

History

Published when the dedupe interceptor's set of pending requests changes. The interceptor coalesces concurrent identical requests so that only one reaches the origin; this channel exposes that bookkeeping for monitoring and debugging.

Attributes
message:<Object>
type:<string>
Either  'added' when a new pending request is registered, or 'removed' when a pending request completes, whether successfully or with an error.
size:<number>
The number of pending requests after the change.
key:<string>
The deduplication key for the request, composed of the origin, method, path, and request headers.
import diagnosticsChannel from 'node:diagnostics_channel'

diagnosticsChannel.channel('undici:request:pending-requests').subscribe(({ type, size, key }) => {
  if (type === 'added') {
    console.log(`New pending request: ${key} (${size} total pending)`)
  } else {
    console.log(`Request completed: ${key} (${size} remaining)`)
  }
})
JavaScript

This is useful for verifying that deduplication is working, monitoring the number of concurrent in-flight requests, and debugging deduplication behaviour in production.