@noodleseed/one 0.22.0 → 0.24.0

package/node_modules/undici/docs/docs/api/Debug.md

@@ -1,16 +1,29 @@
 # Debug
 
-Undici (and subsenquently `fetch` and `websocket`) exposes a debug statement that can be enabled by setting `NODE_DEBUG` within the environment.
+<!--type=misc-->
 
-The flags available are:
+Undici emits human-readable debug logs through Node.js' built-in
+[`util.debuglog()`][]. The logs are disabled by default and are turned on by
+listing one or more namespaces in the `NODE_DEBUG` environment variable. Because
+`util.debuglog()` reads `NODE_DEBUG` once, when the namespace is first used, the
+variable must be set before the process starts.
 
-## `undici`
+Each log line is prefixed with the namespace (uppercased) and the process id,
+for example `UNDICI 16241: connecting to nodejs.org using https:h1`. Multiple
+namespaces can be enabled at once by separating them with commas, for example
+`NODE_DEBUG=undici,websocket`.
+
+The following sections describe the namespaces exposed by undici.
 
-This flag enables debug statements for the core undici library.
+## `undici`
 
-```sh
-NODE_DEBUG=undici node script.js
+Enables debug logs for the core undici library, covering connection setup,
+request dispatch, responses, and trailers. The `fetch` and `websocket` APIs are
+built on top of this core, so enabling `undici` also surfaces activity that
+originates from them.
 
+```console
+$ NODE_DEBUG=undici node script.js
 UNDICI 16241: connecting to nodejs.org using https:h1
 UNDICI 16241: connecting to nodejs.org using https:h1
 UNDICI 16241: connected to nodejs.org using https:h1
@@ -26,13 +39,12 @@ UNDICI 16241: trailers received from GET https://nodejs.org/en
 
 ## `fetch`
 
-This flag enables debug statements for the `fetch` API.
-
-> **Note**: statements are pretty similar to the ones in the `undici` flag, but scoped to `fetch`
-
-```sh
-NODE_DEBUG=fetch node script.js
+Enables debug logs scoped to the `fetch` API. The output mirrors the `undici`
+namespace but is emitted only for requests made through [`fetch()`][], which
+makes it useful for isolating `fetch` traffic from other undici activity.
 
+```console
+$ NODE_DEBUG=fetch node script.js
 FETCH 16241: connecting to nodejs.org using https:h1
 FETCH 16241: connecting to nodejs.org using https:h1
 FETCH 16241: connected to nodejs.org using https:h1
@@ -48,15 +60,19 @@ FETCH 16241: trailers received from GET https://nodejs.org/en
 
 ## `websocket`
 
-This flag enables debug statements for the `Websocket` API.
-
-> **Note**: statements can overlap with `UNDICI` ones if `undici` or `fetch` flag has been enabled as well.
-
-```sh
-NODE_DEBUG=websocket node script.js
+Enables debug logs scoped to the [`WebSocket`][] API, covering the opening
+handshake and connection lifecycle. When the `undici` or `fetch` namespace is
+also enabled, some lines may appear under both namespaces because the handshake
+is performed through the core library.
 
+```console
+$ NODE_DEBUG=websocket node script.js
 WEBSOCKET 18309: connecting to echo.websocket.org using https:h1
 WEBSOCKET 18309: connected to echo.websocket.org using https:h1
 WEBSOCKET 18309: sending request to GET https://echo.websocket.org/
 WEBSOCKET 18309: connection opened <ip_address>
 ```
+
+[`WebSocket`]: WebSocket.md#class-websocket
+[`fetch()`]: Fetch.md
+[`util.debuglog()`]: https://nodejs.org/api/util.html#utildebuglogsection-callback