Stability: Experimental.
\nUndici supports the diagnostics_channel (currently available only on Node.js v16+).\nIt is the preferred way to instrument Undici and retrieve internal information.
The channels available are the following.
", "modules": [ { "textRaw": "`undici:request:create`", "name": "`undici:request:create`", "type": "module", "desc": "This message is published when a new outgoing request is created.
\nimport diagnosticsChannel from '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) // array of strings, e.g: ['foo', 'bar']\n request.addHeader('hello', 'world')\n console.log('headers', request.headers) // e.g. ['foo', 'bar', 'hello', 'world']\n})\nNote: a request is only loosely completed to a given socket.
", "displayName": "`undici:request:create`" }, { "textRaw": "`undici:request:bodyChunkSent`", "name": "`undici:request:bodychunksent`", "type": "module", "desc": "This message is published when a chunk of the request body is being sent.
\nimport diagnosticsChannel from 'diagnostics_channel'\n\ndiagnosticsChannel.channel('undici:request:bodyChunkSent').subscribe(({ request, chunk }) => {\n // request is the same object undici:request:create\n})\nThis message is published after the request body has been fully sent.
\nimport diagnosticsChannel from 'diagnostics_channel'\n\ndiagnosticsChannel.channel('undici:request:bodySent').subscribe(({ request }) => {\n // request is the same object undici:request:create\n})\nThis message is published after the response headers have been received.
\nimport diagnosticsChannel from 'diagnostics_channel'\n\ndiagnosticsChannel.channel('undici:request:headers').subscribe(({ request, response }) => {\n // request is the same object undici:request:create\n console.log('statusCode', response.statusCode)\n console.log(response.statusText)\n // response.headers are buffers.\n console.log(response.headers.map((x) => x.toString()))\n})\nThis message is published after a chunk of the response body has been received.
\nimport diagnosticsChannel from 'diagnostics_channel'\n\ndiagnosticsChannel.channel('undici:request:bodyChunkReceived').subscribe(({ request, chunk }) => {\n // request is the same object undici:request:create\n})\nThis message is published after the response body and trailers have been received, i.e. the response has been completed.
\nimport diagnosticsChannel from 'diagnostics_channel'\n\ndiagnosticsChannel.channel('undici:request:trailers').subscribe(({ request, trailers }) => {\n // request is the same object undici:request:create\n console.log('completed', request.completed)\n // trailers are buffers.\n console.log(trailers.map((x) => x.toString()))\n})\nThis message is published if the request is going to error, but it has not errored yet.
\nimport diagnosticsChannel from 'diagnostics_channel'\n\ndiagnosticsChannel.channel('undici:request:error').subscribe(({ request, error }) => {\n // request is the same object undici:request:create\n})\nThis message is published right before the first byte of the request is written to the socket.
\nNote: It will publish the exact headers that will be sent to the server in raw format.
\nimport diagnosticsChannel from 'diagnostics_channel'\n\ndiagnosticsChannel.channel('undici:client:sendHeaders').subscribe(({ request, headers, socket }) => {\n // request is the same object undici:request:create\n console.log(`Full headers list ${headers.split('\\r\\n')}`);\n})\nThis message is published before creating a new connection for any request.\nYou can not assume that this event is related to any specific request.
\nimport diagnosticsChannel from 'diagnostics_channel'\n\ndiagnosticsChannel.channel('undici:client:beforeConnect').subscribe(({ connectParams, connector }) => {\n // const { host, hostname, protocol, port, servername, version } = connectParams\n // connector is a function that creates the socket\n})\nThis message is published after a connection is established.
\nimport diagnosticsChannel from 'diagnostics_channel'\n\ndiagnosticsChannel.channel('undici:client:connected').subscribe(({ socket, connectParams, connector }) => {\n // const { host, hostname, protocol, port, servername, version } = connectParams\n // connector is a function that creates the socket\n})\nThis message is published if it did not succeed to create new connection
\nimport diagnosticsChannel from 'diagnostics_channel'\n\ndiagnosticsChannel.channel('undici:client:connectError').subscribe(({ error, socket, connectParams, connector }) => {\n // const { host, hostname, protocol, port, servername, version } = connectParams\n // connector is a function that creates the socket\n console.log(`Connect failed with ${error.message}`)\n})\nThis message is published after the client has successfully connected to a server.
\nimport diagnosticsChannel from 'diagnostics_channel'\n\ndiagnosticsChannel.channel('undici:websocket:open').subscribe(({ \n address, // { address: string, family: string, port: number }\n protocol, // string - negotiated subprotocol\n extensions, // string - negotiated extensions\n websocket, // WebSocket - the WebSocket instance\n handshakeResponse // object - HTTP response that upgraded the connection\n}) => {\n console.log(address) // address, family, and port\n console.log(protocol) // negotiated subprotocols\n console.log(extensions) // negotiated extensions\n console.log(websocket) // the WebSocket instance\n \n // Handshake response details\n console.log(handshakeResponse.status) // 101 for HTTP/1.1, 200 for HTTP/2 extended CONNECT\n console.log(handshakeResponse.statusText) // 'Switching Protocols' for HTTP/1.1, commonly 'OK' for HTTP/2 in Node.js\n console.log(handshakeResponse.headers) // Object containing response headers\n})\nThe handshakeResponse object contains the HTTP response that established the WebSocket connection:
status (number): The HTTP status code (101 for HTTP/1.1 upgrade, 200 for HTTP/2 extended CONNECT)
statusText (string): The HTTP status message ('Switching Protocols' for HTTP/1.1, commonly 'OK' for HTTP/2 in Node.js)
headers (object): The HTTP response headers from the server, including:
sec-websocket-accept and other WebSocket-related headersupgrade: 'websocket'connection: 'upgrade'The upgrade and connection headers are only present for HTTP/1.1 handshakes.
This information is particularly useful for debugging and monitoring WebSocket connections, as it provides access to the initial HTTP handshake response that established the WebSocket connection.
", "displayName": "Handshake Response Object" } ], "displayName": "`undici:websocket:open`" }, { "textRaw": "`undici:websocket:close`", "name": "`undici:websocket:close`", "type": "module", "desc": "This message is published after the connection has closed.
\nimport diagnosticsChannel from 'diagnostics_channel'\n\ndiagnosticsChannel.channel('undici:websocket:close').subscribe(({ websocket, code, reason }) => {\n console.log(websocket) // the WebSocket instance\n console.log(code) // the closing status code\n console.log(reason) // the closing reason\n})\nThis message is published if the socket experiences an error.
\nimport diagnosticsChannel from 'diagnostics_channel'\n\ndiagnosticsChannel.channel('undici:websocket:socket_error').subscribe((error) => {\n console.log(error)\n})\nThis message is published after the client receives a ping frame, if the connection is not closing.
\nimport diagnosticsChannel from 'diagnostics_channel'\n\ndiagnosticsChannel.channel('undici:websocket:ping').subscribe(({ payload, websocket }) => {\n // a Buffer or undefined, containing the optional application data of the frame\n console.log(payload)\n console.log(websocket) // the WebSocket instance\n})\nThis message is published after the client receives a pong frame.
\nimport diagnosticsChannel from 'diagnostics_channel'\n\ndiagnosticsChannel.channel('undici:websocket:pong').subscribe(({ payload, websocket }) => {\n // a Buffer or undefined, containing the optional application data of the frame\n console.log(payload)\n console.log(websocket) // the WebSocket instance\n})\nThis message is published after the ProxyAgent establishes a connection to the proxy server.
import diagnosticsChannel from 'diagnostics_channel'\n\ndiagnosticsChannel.channel('undici:proxy:connected').subscribe(({ socket, connectParams }) => {\n console.log(socket)\n console.log(connectParams)\n // const { origin, port, path, signal, headers, servername } = connectParams\n})\nThis message is published when the deduplicate interceptor's pending request map changes. This is useful for monitoring and debugging request deduplication behavior.
\nThe deduplicate interceptor automatically deduplicates concurrent requests for the same resource. When multiple identical requests are made while one is already in-flight, only one request is sent to the origin server, and all waiting handlers receive the same response.
\nimport diagnosticsChannel from 'diagnostics_channel'\n\ndiagnosticsChannel.channel('undici:request:pending-requests').subscribe(({ type, size, key }) => {\n console.log(type) // 'added' or 'removed'\n console.log(size) // current number of pending requests\n console.log(key) // the deduplication key for this request\n})\ntype (string): Either 'added' when a new pending request is registered, or 'removed' when a pending request completes (successfully or with an error).size (number): The current 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 'diagnostics_channel'\n\nconst channel = diagnosticsChannel.channel('undici:request:pending-requests')\n\nchannel.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 can be useful for:
\n