fuc-new/doc/node_modules/undici/docs/docs/api/DiagnosticsChannel.md

Diagnostics Channel Support

Stability: Experimental.

Undici supports the diagnostics_channel (currently available only on Node.js v16+). It is the preferred way to instrument Undici and retrieve internal information.

The channels available are the following.

undici:request:create

This message is published when a new outgoing request is created.

import diagnosticsChannel from '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) // array of strings, e.g: ['foo', 'bar']
  request.addHeader('hello', 'world')
  console.log('headers', request.headers) // e.g. ['foo', 'bar', 'hello', 'world']
})

Note: a request is only loosely completed to a given socket.

undici:request:bodyChunkSent

This message is published when a chunk of the request body is being sent.

import diagnosticsChannel from 'diagnostics_channel'

diagnosticsChannel.channel('undici:request:bodyChunkSent').subscribe(({ request, chunk }) => {
  // request is the same object undici:request:create
})

undici:request:bodySent

This message is published after the request body has been fully sent.

import diagnosticsChannel from 'diagnostics_channel'

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

undici:request:headers

This message is published after the response headers have been received.

import diagnosticsChannel from 'diagnostics_channel'

diagnosticsChannel.channel('undici:request:headers').subscribe(({ request, response }) => {
  // request is the same object undici:request:create
  console.log('statusCode', response.statusCode)
  console.log(response.statusText)
  // response.headers are buffers.
  console.log(response.headers.map((x) => x.toString()))
})

undici:request:bodyChunkReceived

This message is published after a chunk of the response body has been received.

import diagnosticsChannel from 'diagnostics_channel'

diagnosticsChannel.channel('undici:request:bodyChunkReceived').subscribe(({ request, chunk }) => {
  // request is the same object undici:request:create
})

undici:request:trailers

This message is published after the response body and trailers have been received, i.e. the response has been completed.

import diagnosticsChannel from 'diagnostics_channel'

diagnosticsChannel.channel('undici:request:trailers').subscribe(({ request, trailers }) => {
  // request is the same object undici:request:create
  console.log('completed', request.completed)
  // trailers are buffers.
  console.log(trailers.map((x) => x.toString()))
})

undici:request:error

This message is published if the request is going to error, but it has not errored yet.

import diagnosticsChannel from 'diagnostics_channel'

diagnosticsChannel.channel('undici:request:error').subscribe(({ request, error }) => {
  // request is the same object undici:request:create
})

undici:client:sendHeaders

This message is published right before the first byte of the request is written to the socket.

Note: It will publish the exact headers that will be sent to the server in raw format.

import diagnosticsChannel from 'diagnostics_channel'

diagnosticsChannel.channel('undici:client:sendHeaders').subscribe(({ request, headers, socket }) => {
  // request is the same object undici:request:create
  console.log(`Full headers list ${headers.split('\r\n')}`);
})

undici:client:beforeConnect

This message is published before creating a new connection for any request. You can not assume that this event is related to any specific request.

import diagnosticsChannel from 'diagnostics_channel'

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

undici:client:connected

This message is published after a connection is established.

import diagnosticsChannel from 'diagnostics_channel'

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

undici:client:connectError

This message is published if it did not succeed to create new connection

import diagnosticsChannel from 'diagnostics_channel'

diagnosticsChannel.channel('undici:client:connectError').subscribe(({ error, socket, connectParams, connector }) => {
  // const { host, hostname, protocol, port, servername, version } = connectParams
  // connector is a function that creates the socket
  console.log(`Connect failed with ${error.message}`)
})

undici:websocket:open

This message is published after the client has successfully connected to a server.

import diagnosticsChannel from 'diagnostics_channel'

diagnosticsChannel.channel('undici:websocket:open').subscribe(({ 
  address,           // { address: string, family: string, port: number }
  protocol,          // string - negotiated subprotocol
  extensions,        // string - negotiated extensions
  websocket,         // WebSocket - the WebSocket instance
  handshakeResponse  // object - HTTP response that upgraded the connection
}) => {
  console.log(address) // address, family, and port
  console.log(protocol) // negotiated subprotocols
  console.log(extensions) // negotiated extensions
  console.log(websocket) // the WebSocket instance
  
  // Handshake response details
  console.log(handshakeResponse.status) // 101 for successful WebSocket upgrade
  console.log(handshakeResponse.statusText) // 'Switching Protocols'
  console.log(handshakeResponse.headers) // Object containing response headers
})

Handshake Response Object

The handshakeResponse object contains the HTTP response that upgraded the connection to WebSocket:

• status (number): The HTTP status code (101 for successful WebSocket upgrade)
• statusText (string): The HTTP status message ('Switching Protocols' for successful upgrade)
• headers (object): The HTTP response headers from the server, including:
  • upgrade: 'websocket'
  • connection: 'upgrade'
  • sec-websocket-accept and other WebSocket-related headers

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.

undici:websocket:close

This message is published after the connection has closed.

import diagnosticsChannel from 'diagnostics_channel'

diagnosticsChannel.channel('undici:websocket:close').subscribe(({ websocket, code, reason }) => {
  console.log(websocket) // the WebSocket instance
  console.log(code) // the closing status code
  console.log(reason) // the closing reason
})

undici:websocket:socket_error

This message is published if the socket experiences an error.

import diagnosticsChannel from 'diagnostics_channel'

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

undici:websocket:ping

This message is published after the client receives a ping frame, if the connection is not closing.

import diagnosticsChannel from 'diagnostics_channel'

diagnosticsChannel.channel('undici:websocket:ping').subscribe(({ payload, websocket }) => {
  // a Buffer or undefined, containing the optional application data of the frame
  console.log(payload)
  console.log(websocket) // the WebSocket instance
})

undici:websocket:pong

This message is published after the client receives a pong frame.

import diagnosticsChannel from 'diagnostics_channel'

diagnosticsChannel.channel('undici:websocket:pong').subscribe(({ payload, websocket }) => {
  // a Buffer or undefined, containing the optional application data of the frame
  console.log(payload)
  console.log(websocket) // the WebSocket instance
})