Undici is instrumented with Node.js' built-in diagnostics_channel module.\nIt is the preferred way to observe undici's internal behaviour without patching\nthe library, and it backs the human-readable debug logs.
Each integration point is exposed as a named channel. To observe an event,\nobtain the channel by name and subscribe to it:
\nimport diagnosticsChannel from 'node:diagnostics_channel'\n\ndiagnosticsChannel.channel('undici:request:create').subscribe(({ request }) => {\n console.log(request.method, request.origin, request.path)\n})\nconst diagnosticsChannel = require('node:diagnostics_channel')\n\ndiagnosticsChannel.channel('undici:request:create').subscribe(({ request }) => {\n console.log(request.method, request.origin, request.path)\n})\nThe message published to a channel is always a single object whose shape depends\non the channel. The sections below describe every channel and the object it\npublishes. Subscriber callbacks run synchronously inside undici, so they should\nbe fast and must not throw.
\nThe same request object is shared across all undici:request:* channels for a\ngiven request, so a subscriber may correlate the lifecycle of one request by\nidentity.
Published when a new outgoing request is created, before it is dispatched.
\nThe request object also exposes an addHeader(name, value) method that\nappends a header before the request is sent.
import diagnosticsChannel from 'node:diagnostics_channel'\n\ndiagnosticsChannel.channel('undici:request:create').subscribe(({ request }) => {\n console.log('origin', request.origin)\n console.log('completed', request.completed)\n console.log('method', request.method)\n console.log('path', request.path)\n console.log('headers', request.headers)\n request.addHeader('hello', 'world')\n})\nA request is only loosely bound to a given socket at this stage.
" }, { "textRaw": "Event: `'undici:request:bodyChunkSent'`", "name": "undici:request:bodyChunkSent", "type": "event", "meta": { "added": [ "v7.11.0" ], "changes": [] }, "params": [ { "textRaw": "`message` {Object}", "name": "message", "type": "Object", "options": [ { "textRaw": "`request` {Object} The same object published by `'undici:request:create'`.", "name": "request", "type": "Object", "desc": "The same object published by `'undici:request:create'`." }, { "textRaw": "`chunk` {Uint8Array|string} The body chunk being sent.", "name": "chunk", "type": "Uint8Array|string", "desc": "The body chunk being sent." } ] } ], "desc": "Published each time a chunk of the request body is written to the socket.
\nimport diagnosticsChannel from 'node:diagnostics_channel'\n\ndiagnosticsChannel.channel('undici:request:bodyChunkSent').subscribe(({ request, chunk }) => {\n console.log('sent', chunk.length, 'bytes')\n})\nPublished after the request body has been fully sent.
\nimport diagnosticsChannel from 'node:diagnostics_channel'\n\ndiagnosticsChannel.channel('undici:request:bodySent').subscribe(({ request }) => {\n // request is the same object as in 'undici:request:create'\n})\nPublished after the response headers have been received.
\nimport diagnosticsChannel from 'node:diagnostics_channel'\n\ndiagnosticsChannel.channel('undici:request:headers').subscribe(({ request, response }) => {\n console.log('statusCode', response.statusCode)\n console.log(response.statusText)\n console.log(response.headers.map((x) => x.toString()))\n})\nPublished each time a chunk of the response body is received.
\nimport diagnosticsChannel from 'node:diagnostics_channel'\n\ndiagnosticsChannel.channel('undici:request:bodyChunkReceived').subscribe(({ request, chunk }) => {\n console.log('received', chunk.length, 'bytes')\n})\nPublished after the response body and trailers have been received, that is, once\nthe response has fully completed.
\nimport diagnosticsChannel from 'node:diagnostics_channel'\n\ndiagnosticsChannel.channel('undici:request:trailers').subscribe(({ request, trailers }) => {\n console.log('completed', request.completed)\n console.log(trailers.map((x) => x.toString()))\n})\nPublished when the request is about to error, before the error is surfaced to\nthe caller.
\nimport diagnosticsChannel from 'node:diagnostics_channel'\n\ndiagnosticsChannel.channel('undici:request:error').subscribe(({ request, error }) => {\n console.error(error)\n})\nPublished immediately before the first byte of the request is written to the\nsocket. The headers are published exactly as they will be sent to the server, in\nraw form.
\nimport diagnosticsChannel from 'node:diagnostics_channel'\n\ndiagnosticsChannel.channel('undici:client:sendHeaders').subscribe(({ request, headers, socket }) => {\n console.log(`Full headers list: ${headers.split('\\r\\n')}`)\n})\nPublished before a new connection is opened for any request. This event cannot be\nattributed to a specific request, because connections are pooled and shared.
\nimport diagnosticsChannel from 'node:diagnostics_channel'\n\ndiagnosticsChannel.channel('undici:client:beforeConnect').subscribe(({ connectParams, connector }) => {\n const { host, hostname, protocol, port, servername } = connectParams\n // connector is the function that creates the socket\n})\nPublished after a connection has been successfully established.
\nimport diagnosticsChannel from 'node:diagnostics_channel'\n\ndiagnosticsChannel.channel('undici:client:connected').subscribe(({ socket, connectParams, connector }) => {\n const { host, hostname, protocol, port, servername } = connectParams\n})\nPublished when a connection could not be established.
\nimport diagnosticsChannel from 'node:diagnostics_channel'\n\ndiagnosticsChannel.channel('undici:client:connectError').subscribe(({ error, socket, connectParams, connector }) => {\n console.error(`Connect failed with ${error.message}`)\n})\nPublished after a WebSocket has successfully connected to a server.
import diagnosticsChannel from 'node:diagnostics_channel'\n\ndiagnosticsChannel.channel('undici:websocket:open').subscribe(({\n address,\n protocol,\n extensions,\n websocket,\n handshakeResponse\n}) => {\n console.log(address)\n console.log(protocol)\n console.log(extensions)\n console.log(handshakeResponse.status)\n console.log(handshakeResponse.headers)\n})\nPublished after the WebSocket connection has closed.
import diagnosticsChannel from 'node:diagnostics_channel'\n\ndiagnosticsChannel.channel('undici:websocket:close').subscribe(({ websocket, code, reason }) => {\n console.log(code, reason)\n})\nPublished when the underlying WebSocket socket experiences an error. Unlike the\nother WebSocket channels, the published message is the error itself.
\nimport diagnosticsChannel from 'node:diagnostics_channel'\n\ndiagnosticsChannel.channel('undici:websocket:socket_error').subscribe((error) => {\n console.error(error)\n})\nPublished after the client receives a ping frame.
\nimport diagnosticsChannel from 'node:diagnostics_channel'\n\ndiagnosticsChannel.channel('undici:websocket:ping').subscribe(({ payload, websocket }) => {\n console.log(payload)\n})\nPublished after the client receives a pong frame.
\nimport diagnosticsChannel from 'node:diagnostics_channel'\n\ndiagnosticsChannel.channel('undici:websocket:pong').subscribe(({ payload, websocket }) => {\n console.log(payload)\n})\nPublished after a ProxyAgent has established a tunnel to the proxy server.
import diagnosticsChannel from 'node:diagnostics_channel'\n\ndiagnosticsChannel.channel('undici:proxy:connected').subscribe(({ socket, connectParams }) => {\n const { origin, port, path, signal, headers, servername } = connectParams\n})\nPublished when the dedupe interceptor's set of pending requests changes.\nThe interceptor coalesces concurrent identical requests so that only one reaches\nthe origin; this channel exposes that bookkeeping for monitoring and debugging.
import diagnosticsChannel from 'node:diagnostics_channel'\n\ndiagnosticsChannel.channel('undici:request:pending-requests').subscribe(({ type, size, key }) => {\n if (type === 'added') {\n console.log(`New pending request: ${key} (${size} total pending)`)\n } else {\n console.log(`Request completed: ${key} (${size} remaining)`)\n }\n})\nThis is useful for verifying that deduplication is working, monitoring the number\nof concurrent in-flight requests, and debugging deduplication behaviour in\nproduction.
" } ] } ] }