Add Node.js diagnostic channel support

sindresorhus · sindresorhus · commit 3e2a781c8e4f · 2025-10-16T14:05:07.000+09:00
Fixes #1792
diff --git a/documentation/diagnostics-channel.md b/documentation/diagnostics-channel.md
@@ -0,0 +1,93 @@
+[> Back to homepage](../readme.md#documentation)
+
+## Diagnostics Channel
+
+Got integrates with Node.js [diagnostic channels](https://nodejs.org/api/diagnostics_channel.html) for low-overhead observability. Events are only published when subscribers exist.
+
+### Channels
+
+#### `got:request:create`
+
+Emitted when a request is created.
+
+```ts
+{requestId: string, url: string, method: string}
+```
+
+#### `got:request:start`
+
+Emitted before the native HTTP request is sent.
+
+```ts
+{requestId: string, url: string, method: string, headers: Record<string, string | string[] | undefined>}
+```
+
+#### `got:response:start`
+
+Emitted when response headers are received.
+
+```ts
+{requestId: string, url: string, statusCode: number, headers: Record<string, string | string[] | undefined>, isFromCache: boolean}
+```
+
+#### `got:response:end`
+
+Emitted when the response completes.
+
+```ts
+{requestId: string, url: string, statusCode: number, bodySize?: number, timings?: Timings}
+```
+
+#### `got:request:retry`
+
+Emitted when retrying a request.
+
+```ts
+{requestId: string, retryCount: number, error: RequestError, delay: number}
+```
+
+#### `got:request:error`
+
+Emitted when a request fails.
+
+```ts
+{requestId: string, url: string, error: RequestError, timings?: Timings}
+```
+
+#### `got:response:redirect`
+
+Emitted when following a redirect.
+
+```ts
+{requestId: string, fromUrl: string, toUrl: string, statusCode: number}
+```
+
+### Example
+
+```js
+import diagnosticsChannel from 'node:diagnostics_channel';
+
+const channel = diagnosticsChannel.channel('got:request:start');
+
+channel.subscribe(message => {
+	console.log(`${message.method} ${message.url}`);
+});
+```
+
+All events for a single request share the same `requestId`.
+
+### TypeScript
+
+All message types are exported from the main package:
+
+```ts
+import type {
+	DiagnosticRequestCreate,
+	DiagnosticRequestStart,
+	DiagnosticResponseStart,
+	DiagnosticResponseEnd,
+	DiagnosticRequestRetry,
+	DiagnosticRequestError,
+	DiagnosticResponseRedirect,
+} from 'got';
+```
diff --git a/readme.md b/readme.md
@@ -127,6 +127,7 @@ By default, Got will retry on failure. To disable this option, set [`options.ret
 
 #### Integration
 
+- [x] [Diagnostics Channel](documentation/diagnostics-channel.md)
 - [x] [TypeScript support](documentation/typescript.md)
 - [x] [AWS](documentation/tips.md#aws)
 - [x] [Testing](documentation/tips.md#testing)
diff --git a/source/core/diagnostics-channel.ts b/source/core/diagnostics-channel.ts
@@ -0,0 +1,147 @@
+import {randomUUID} from 'node:crypto';
+import diagnosticsChannel from 'node:diagnostics_channel';
+import type {Timings} from '@szmarczak/http-timer';
+import type {RequestError} from './errors.js';
+
+const channels = {
+	requestCreate: diagnosticsChannel.channel('got:request:create'),
+	requestStart: diagnosticsChannel.channel('got:request:start'),
+	responseStart: diagnosticsChannel.channel('got:response:start'),
+	responseEnd: diagnosticsChannel.channel('got:response:end'),
+	retry: diagnosticsChannel.channel('got:request:retry'),
+	error: diagnosticsChannel.channel('got:request:error'),
+	redirect: diagnosticsChannel.channel('got:response:redirect'),
+};
+
+export type RequestId = string;
+
+/**
+Message for the `got:request:create` diagnostic channel.
+
+Emitted when a request is created.
+*/
+export type DiagnosticRequestCreate = {
+	requestId: RequestId;
+	url: string;
+	method: string;
+};
+
+/**
+Message for the `got:request:start` diagnostic channel.
+
+Emitted before the native HTTP request is sent.
+*/
+export type DiagnosticRequestStart = {
+	requestId: RequestId;
+	url: string;
+	method: string;
+	headers: Record<string, string | string[] | undefined>;
+};
+
+/**
+Message for the `got:response:start` diagnostic channel.
+
+Emitted when response headers are received.
+*/
+export type DiagnosticResponseStart = {
+	requestId: RequestId;
+	url: string;
+	statusCode: number;
+	headers: Record<string, string | string[] | undefined>;
+	isFromCache: boolean;
+};
+
+/**
+Message for the `got:response:end` diagnostic channel.
+
+Emitted when the response completes.
+*/
+export type DiagnosticResponseEnd = {
+	requestId: RequestId;
+	url: string;
+	statusCode: number;
+	bodySize?: number;
+	timings?: Timings;
+};
+
+/**
+Message for the `got:request:retry` diagnostic channel.
+
+Emitted when retrying a request.
+*/
+export type DiagnosticRequestRetry = {
+	requestId: RequestId;
+	retryCount: number;
+	error: RequestError;
+	delay: number;
+};
+
+/**
+Message for the `got:request:error` diagnostic channel.
+
+Emitted when a request fails.
+*/
+export type DiagnosticRequestError = {
+	requestId: RequestId;
+	url: string;
+	error: RequestError;
+	timings?: Timings;
+};
+
+/**
+Message for the `got:response:redirect` diagnostic channel.
+
+Emitted when following a redirect.
+*/
+export type DiagnosticResponseRedirect = {
+	requestId: RequestId;
+	fromUrl: string;
+	toUrl: string;
+	statusCode: number;
+};
+
+export function generateRequestId(): RequestId {
+	return randomUUID();
+}
+
+export function publishRequestCreate(message: DiagnosticRequestCreate): void {
+	if (channels.requestCreate.hasSubscribers) {
+		channels.requestCreate.publish(message);
+	}
+}
+
+export function publishRequestStart(message: DiagnosticRequestStart): void {
+	if (channels.requestStart.hasSubscribers) {
+		channels.requestStart.publish(message);
+	}
+}
+
+export function publishResponseStart(message: DiagnosticResponseStart): void {
+	if (channels.responseStart.hasSubscribers) {
+		channels.responseStart.publish(message);
+	}
+}
+
+export function publishResponseEnd(message: DiagnosticResponseEnd): void {
+	if (channels.responseEnd.hasSubscribers) {
+		channels.responseEnd.publish(message);
+	}
+}
+
+export function publishRetry(message: DiagnosticRequestRetry): void {
+	if (channels.retry.hasSubscribers) {
+		channels.retry.publish(message);
+	}
+}
+
+export function publishError(message: DiagnosticRequestError): void {
+	if (channels.error.hasSubscribers) {
+		channels.error.publish(message);
+	}
+}
+
+export function publishRedirect(message: DiagnosticResponseRedirect): void {
+	if (channels.redirect.hasSubscribers) {
+		channels.redirect.publish(message);
+	}
+}
diff --git a/source/core/index.ts b/source/core/index.ts
@@ -43,6 +43,17 @@ import {
 	CacheError,
 	AbortError,
 } from './errors.js';
+import {
+	type RequestId,
+	generateRequestId,
+	publishRequestCreate,
+	publishRequestStart,
+	publishResponseStart,
+	publishResponseEnd,
+	publishRetry,
+	publishError,
+	publishRedirect,
+} from './diagnostics-channel.js';
 
 type Error = NodeJS.ErrnoException;
 
@@ -200,6 +211,7 @@ export default class Request extends Duplex implements RequestEvents<Request> {
 	private _aborted: boolean;
 	private _expectedContentLength?: number;
 	private _byteCounter?: ByteCounter;
+	private readonly _requestId: RequestId;
 
 	// We need this because `this._request` if `undefined` when using cache
 	private _requestInitialized: boolean;
@@ -229,6 +241,7 @@ export default class Request extends Duplex implements RequestEvents<Request> {
 		this.retryCount = 0;
 
 		this._stopRetry = noop;
+		this._requestId = generateRequestId();
 
 		this.on('pipe', (source: any) => {
 			if (source?.headers) {
@@ -254,6 +267,13 @@ export default class Request extends Duplex implements RequestEvents<Request> {
 			}
 
 			this.requestUrl = this.options.url as URL;
+
+			// Publish request creation event
+			publishRequestCreate({
+				requestId: this._requestId,
+				url: this.options.url?.toString() ?? '',
+				method: this.options.method,
+			});
 		} catch (error: any) {
 			const {options} = error as OptionsError;
 			if (options) {
@@ -509,6 +529,14 @@ export default class Request extends Duplex implements RequestEvents<Request> {
 						// and will detect it's a consumed stream, which is the correct behavior.
 					}
 
+					// Publish retry event
+					publishRetry({
+						requestId: this._requestId,
+						retryCount: this.retryCount + 1,
+						error: typedError,
+						delay: backoff,
+					});
+
 					this.emit('retry', this.retryCount + 1, error, (updatedOptions?: OptionsInit) => {
 						const request = new Request(options.url, updatedOptions, options);
 						request.retryCount = this.retryCount + 1;
@@ -823,6 +851,15 @@ export default class Request extends Duplex implements RequestEvents<Request> {
 
 		this.response = typedResponse;
 
+		// Publish response start event
+		publishResponseStart({
+			requestId: this._requestId,
+			url: typedResponse.url,
+			statusCode,
+			headers: response.headers,
+			isFromCache: typedResponse.isFromCache,
+		});
+
 		// Workaround for http-timer bug: when connecting to an IP address (no DNS lookup),
 		// http-timer sets lookup = connect instead of lookup = socket, resulting in
 		// dns = lookup - socket being a small positive number instead of 0.
@@ -978,6 +1015,14 @@ export default class Request extends Duplex implements RequestEvents<Request> {
 						await hook(updatedOptions as NormalizedOptions, typedResponse);
 					}
 
+					// Publish redirect event
+					publishRedirect({
+						requestId: this._requestId,
+						fromUrl: url!.toString(),
+						toUrl: redirectUrl.toString(),
+						statusCode,
+					});
+
 					this.emit('redirect', updatedOptions, typedResponse);
 
 					this.options = updatedOptions;
@@ -1027,6 +1072,16 @@ export default class Request extends Duplex implements RequestEvents<Request> {
 
 			this._responseSize = this._downloadedSize;
 			this.emit('downloadProgress', this.downloadProgress);
+
+			// Publish response end event
+			publishResponseEnd({
+				requestId: this._requestId,
+				url: typedResponse.url,
+				statusCode,
+				bodySize: this._downloadedSize,
+				timings: this.timings,
+			});
+
 			this.push(null);
 		});
 
@@ -1124,6 +1179,14 @@ export default class Request extends Duplex implements RequestEvents<Request> {
 		const {options} = this;
 		const {timeout, url} = options;
 
+		// Publish request start event
+		publishRequestStart({
+			requestId: this._requestId,
+			url: url?.toString() ?? '',
+			method: options.method,
+			headers: options.headers,
+		});
+
 		timer(request);
 
 		this._cancelTimeouts = timedOut(request, timeout, url as URL);
@@ -1531,6 +1594,14 @@ export default class Request extends Duplex implements RequestEvents<Request> {
 			error = new RequestError(error_.message, error_, this);
 		}
 
+		// Publish error event
+		publishError({
+			requestId: this._requestId,
+			url: this.options?.url?.toString() ?? '',
+			error,
+			timings: this.timings,
+		});
+
 		this.destroy(error);
 
 		// Manually emit error for Promise API to ensure it receives it.
diff --git a/source/index.ts b/source/index.ts
@@ -21,6 +21,7 @@ export * from './core/response.js';
 export type {default as Request} from './core/index.js';
 export * from './core/index.js';
 export * from './core/errors.js';
+export * from './core/diagnostics-channel.js';
 export type {Delays} from './core/timed-out.js';
 export {default as calculateRetryDelay} from './core/calculate-retry-delay.js';
 export * from './as-promise/types.js';
diff --git a/test/diagnostics-channel.ts b/test/diagnostics-channel.ts
