1# Diagnostics Channel 2 3<!--introduced_in=v14.17.0--> 4 5> Stability: 1 - Experimental 6 7<!-- source_link=lib/diagnostics_channel.js --> 8 9The `diagnostics_channel` module provides an API to create named channels 10to report arbitrary message data for diagnostics purposes. 11 12It can be accessed using: 13 14```js 15const diagnostics_channel = require('diagnostics_channel'); 16``` 17 18It is intended that a module writer wanting to report diagnostics messages 19will create one or many top-level channels to report messages through. 20Channels may also be acquired at runtime but it is not encouraged 21due to the additional overhead of doing so. Channels may be exported for 22convenience, but as long as the name is known it can be acquired anywhere. 23 24If you intend for your module to produce diagnostics data for others to 25consume it is recommended that you include documentation of what named 26channels are used along with the shape of the message data. Channel names 27should generally include the module name to avoid collisions with data from 28other modules. 29 30## Public API 31 32### Overview 33 34Following is a simple overview of the public API. 35 36```js 37const diagnostics_channel = require('diagnostics_channel'); 38 39// Get a reusable channel object 40const channel = diagnostics_channel.channel('my-channel'); 41 42// Subscribe to the channel 43channel.subscribe((message, name) => { 44 // Received data 45}); 46 47// Check if the channel has an active subscriber 48if (channel.hasSubscribers) { 49 // Publish data to the channel 50 channel.publish({ 51 some: 'data' 52 }); 53} 54``` 55 56#### `diagnostics_channel.hasSubscribers(name)` 57 58* `name` {string|symbol} The channel name 59* Returns: {boolean} If there are active subscribers 60 61Check if there are active subscribers to the named channel. This is helpful if 62the message you want to send might be expensive to prepare. 63 64This API is optional but helpful when trying to publish messages from very 65performance-sensitive code. 66 67```js 68const diagnostics_channel = require('diagnostics_channel'); 69 70if (diagnostics_channel.hasSubscribers('my-channel')) { 71 // There are subscribers, prepare and publish message 72} 73``` 74 75#### `diagnostics_channel.channel(name)` 76 77* `name` {string|symbol} The channel name 78* Returns: {Channel} The named channel object 79 80This is the primary entry-point for anyone wanting to interact with a named 81channel. It produces a channel object which is optimized to reduce overhead at 82publish time as much as possible. 83 84```js 85const diagnostics_channel = require('diagnostics_channel'); 86 87const channel = diagnostics_channel.channel('my-channel'); 88``` 89 90### Class: `Channel` 91 92The class `Channel` represents an individual named channel within the data 93pipeline. It is use to track subscribers and to publish messages when there 94are subscribers present. It exists as a separate object to avoid channel 95lookups at publish time, enabling very fast publish speeds and allowing 96for heavy use while incurring very minimal cost. Channels are created with 97[`diagnostics_channel.channel(name)`][], constructing a channel directly 98with `new Channel(name)` is not supported. 99 100#### `channel.hasSubscribers` 101 102* Returns: {boolean} If there are active subscribers 103 104Check if there are active subscribers to this channel. This is helpful if 105the message you want to send might be expensive to prepare. 106 107This API is optional but helpful when trying to publish messages from very 108performance-sensitive code. 109 110```js 111const diagnostics_channel = require('diagnostics_channel'); 112 113const channel = diagnostics_channel.channel('my-channel'); 114 115if (channel.hasSubscribers) { 116 // There are subscribers, prepare and publish message 117} 118``` 119 120#### `channel.publish(message)` 121 122* `message` {any} The message to send to the channel subscribers 123 124Publish a message to any subscribers to the channel. This will trigger 125message handlers synchronously so they will execute within the same context. 126 127```js 128const diagnostics_channel = require('diagnostics_channel'); 129 130const channel = diagnostics_channel.channel('my-channel'); 131 132channel.publish({ 133 some: 'message' 134}); 135``` 136 137#### `channel.subscribe(onMessage)` 138 139* `onMessage` {Function} The handler to receive channel messages 140 * `message` {any} The message data 141 * `name` {string|symbol} The name of the channel 142 143Register a message handler to subscribe to this channel. This message handler 144will be run synchronously whenever a message is published to the channel. Any 145errors thrown in the message handler will trigger an [`'uncaughtException'`][]. 146 147```js 148const diagnostics_channel = require('diagnostics_channel'); 149 150const channel = diagnostics_channel.channel('my-channel'); 151 152channel.subscribe((message, name) => { 153 // Received data 154}); 155``` 156 157#### `channel.unsubscribe(onMessage)` 158 159<!-- YAML 160added: 161 - v14.17.0 162changes: 163 - version: v14.19.0 164 pr-url: https://github.com/nodejs/node/pull/40433 165 description: Added return value. Added to channels without subscribers. 166--> 167 168* `onMessage` {Function} The previous subscribed handler to remove 169* Returns: {boolean} `true` if the handler was found, `false` otherwise. 170 171Remove a message handler previously registered to this channel with 172[`channel.subscribe(onMessage)`][]. 173 174```js 175const diagnostics_channel = require('diagnostics_channel'); 176 177const channel = diagnostics_channel.channel('my-channel'); 178 179function onMessage(message, name) { 180 // Received data 181} 182 183channel.subscribe(onMessage); 184 185channel.unsubscribe(onMessage); 186``` 187 188[`'uncaughtException'`]: process.md#process_event_uncaughtexception 189[`channel.subscribe(onMessage)`]: #diagnostics_channel_channel_subscribe_onmessage 190[`diagnostics_channel.channel(name)`]: #diagnostics_channel_diagnostics_channel_channel_name 191