1{ 2 "type": "module", 3 "source": "doc/api/diagnostics_channel.md", 4 "modules": [ 5 { 6 "textRaw": "Diagnostics Channel", 7 "name": "diagnostics_channel", 8 "meta": { 9 "added": [ 10 "v15.1.0", 11 "v14.17.0" 12 ], 13 "changes": [ 14 { 15 "version": "v18.13.0", 16 "pr-url": "https://github.com/nodejs/node/pull/45290", 17 "description": "diagnostics_channel is now Stable." 18 } 19 ] 20 }, 21 "introduced_in": "v15.1.0", 22 "stability": 2, 23 "stabilityText": "Stable", 24 "desc": "<p><strong>Source Code:</strong> <a href=\"https://github.com/nodejs/node/blob/v18.20.1/lib/diagnostics_channel.js\">lib/diagnostics_channel.js</a></p>\n<p>The <code>node:diagnostics_channel</code> module provides an API to create named channels\nto report arbitrary message data for diagnostics purposes.</p>\n<p>It can be accessed using:</p>\n<pre><code class=\"language-mjs\">import diagnostics_channel from 'node:diagnostics_channel';\n</code></pre>\n<pre><code class=\"language-cjs\">const diagnostics_channel = require('node:diagnostics_channel');\n</code></pre>\n<p>It is intended that a module writer wanting to report diagnostics messages\nwill create one or many top-level channels to report messages through.\nChannels may also be acquired at runtime but it is not encouraged\ndue to the additional overhead of doing so. Channels may be exported for\nconvenience, but as long as the name is known it can be acquired anywhere.</p>\n<p>If you intend for your module to produce diagnostics data for others to\nconsume it is recommended that you include documentation of what named\nchannels are used along with the shape of the message data. Channel names\nshould generally include the module name to avoid collisions with data from\nother modules.</p>", 25 "modules": [ 26 { 27 "textRaw": "Public API", 28 "name": "public_api", 29 "modules": [ 30 { 31 "textRaw": "Overview", 32 "name": "overview", 33 "desc": "<p>Following is a simple overview of the public API.</p>\n<pre><code class=\"language-mjs\">import diagnostics_channel from 'node:diagnostics_channel';\n\n// Get a reusable channel object\nconst channel = diagnostics_channel.channel('my-channel');\n\nfunction onMessage(message, name) {\n // Received data\n}\n\n// Subscribe to the channel\ndiagnostics_channel.subscribe('my-channel', onMessage);\n\n// Check if the channel has an active subscriber\nif (channel.hasSubscribers) {\n // Publish data to the channel\n channel.publish({\n some: 'data',\n });\n}\n\n// Unsubscribe from the channel\ndiagnostics_channel.unsubscribe('my-channel', onMessage);\n</code></pre>\n<pre><code class=\"language-cjs\">const diagnostics_channel = require('node:diagnostics_channel');\n\n// Get a reusable channel object\nconst channel = diagnostics_channel.channel('my-channel');\n\nfunction onMessage(message, name) {\n // Received data\n}\n\n// Subscribe to the channel\ndiagnostics_channel.subscribe('my-channel', onMessage);\n\n// Check if the channel has an active subscriber\nif (channel.hasSubscribers) {\n // Publish data to the channel\n channel.publish({\n some: 'data',\n });\n}\n\n// Unsubscribe from the channel\ndiagnostics_channel.unsubscribe('my-channel', onMessage);\n</code></pre>", 34 "methods": [ 35 { 36 "textRaw": "`diagnostics_channel.hasSubscribers(name)`", 37 "type": "method", 38 "name": "hasSubscribers", 39 "meta": { 40 "added": [ 41 "v15.1.0", 42 "v14.17.0" 43 ], 44 "changes": [] 45 }, 46 "signatures": [ 47 { 48 "return": { 49 "textRaw": "Returns: {boolean} If there are active subscribers", 50 "name": "return", 51 "type": "boolean", 52 "desc": "If there are active subscribers" 53 }, 54 "params": [ 55 { 56 "textRaw": "`name` {string|symbol} The channel name", 57 "name": "name", 58 "type": "string|symbol", 59 "desc": "The channel name" 60 } 61 ] 62 } 63 ], 64 "desc": "<p>Check if there are active subscribers to the named channel. This is helpful if\nthe message you want to send might be expensive to prepare.</p>\n<p>This API is optional but helpful when trying to publish messages from very\nperformance-sensitive code.</p>\n<pre><code class=\"language-mjs\">import diagnostics_channel from 'node:diagnostics_channel';\n\nif (diagnostics_channel.hasSubscribers('my-channel')) {\n // There are subscribers, prepare and publish message\n}\n</code></pre>\n<pre><code class=\"language-cjs\">const diagnostics_channel = require('node:diagnostics_channel');\n\nif (diagnostics_channel.hasSubscribers('my-channel')) {\n // There are subscribers, prepare and publish message\n}\n</code></pre>" 65 }, 66 { 67 "textRaw": "`diagnostics_channel.channel(name)`", 68 "type": "method", 69 "name": "channel", 70 "meta": { 71 "added": [ 72 "v15.1.0", 73 "v14.17.0" 74 ], 75 "changes": [] 76 }, 77 "signatures": [ 78 { 79 "return": { 80 "textRaw": "Returns: {Channel} The named channel object", 81 "name": "return", 82 "type": "Channel", 83 "desc": "The named channel object" 84 }, 85 "params": [ 86 { 87 "textRaw": "`name` {string|symbol} The channel name", 88 "name": "name", 89 "type": "string|symbol", 90 "desc": "The channel name" 91 } 92 ] 93 } 94 ], 95 "desc": "<p>This is the primary entry-point for anyone wanting to publish to a named\nchannel. It produces a channel object which is optimized to reduce overhead at\npublish time as much as possible.</p>\n<pre><code class=\"language-mjs\">import diagnostics_channel from 'node:diagnostics_channel';\n\nconst channel = diagnostics_channel.channel('my-channel');\n</code></pre>\n<pre><code class=\"language-cjs\">const diagnostics_channel = require('node:diagnostics_channel');\n\nconst channel = diagnostics_channel.channel('my-channel');\n</code></pre>" 96 }, 97 { 98 "textRaw": "`diagnostics_channel.subscribe(name, onMessage)`", 99 "type": "method", 100 "name": "subscribe", 101 "meta": { 102 "added": [ 103 "v18.7.0" 104 ], 105 "changes": [] 106 }, 107 "signatures": [ 108 { 109 "params": [ 110 { 111 "textRaw": "`name` {string|symbol} The channel name", 112 "name": "name", 113 "type": "string|symbol", 114 "desc": "The channel name" 115 }, 116 { 117 "textRaw": "`onMessage` {Function} The handler to receive channel messages", 118 "name": "onMessage", 119 "type": "Function", 120 "desc": "The handler to receive channel messages", 121 "options": [ 122 { 123 "textRaw": "`message` {any} The message data", 124 "name": "message", 125 "type": "any", 126 "desc": "The message data" 127 }, 128 { 129 "textRaw": "`name` {string|symbol} The name of the channel", 130 "name": "name", 131 "type": "string|symbol", 132 "desc": "The name of the channel" 133 } 134 ] 135 } 136 ] 137 } 138 ], 139 "desc": "<p>Register a message handler to subscribe to this channel. This message handler\nwill be run synchronously whenever a message is published to the channel. Any\nerrors thrown in the message handler will trigger an <a href=\"process.html#event-uncaughtexception\"><code>'uncaughtException'</code></a>.</p>\n<pre><code class=\"language-mjs\">import diagnostics_channel from 'node:diagnostics_channel';\n\ndiagnostics_channel.subscribe('my-channel', (message, name) => {\n // Received data\n});\n</code></pre>\n<pre><code class=\"language-cjs\">const diagnostics_channel = require('node:diagnostics_channel');\n\ndiagnostics_channel.subscribe('my-channel', (message, name) => {\n // Received data\n});\n</code></pre>" 140 }, 141 { 142 "textRaw": "`diagnostics_channel.unsubscribe(name, onMessage)`", 143 "type": "method", 144 "name": "unsubscribe", 145 "meta": { 146 "added": [ 147 "v18.7.0" 148 ], 149 "changes": [] 150 }, 151 "signatures": [ 152 { 153 "return": { 154 "textRaw": "Returns: {boolean} `true` if the handler was found, `false` otherwise.", 155 "name": "return", 156 "type": "boolean", 157 "desc": "`true` if the handler was found, `false` otherwise." 158 }, 159 "params": [ 160 { 161 "textRaw": "`name` {string|symbol} The channel name", 162 "name": "name", 163 "type": "string|symbol", 164 "desc": "The channel name" 165 }, 166 { 167 "textRaw": "`onMessage` {Function} The previous subscribed handler to remove", 168 "name": "onMessage", 169 "type": "Function", 170 "desc": "The previous subscribed handler to remove" 171 } 172 ] 173 } 174 ], 175 "desc": "<p>Remove a message handler previously registered to this channel with\n<a href=\"#diagnostics_channelsubscribename-onmessage\"><code>diagnostics_channel.subscribe(name, onMessage)</code></a>.</p>\n<pre><code class=\"language-mjs\">import diagnostics_channel from 'node:diagnostics_channel';\n\nfunction onMessage(message, name) {\n // Received data\n}\n\ndiagnostics_channel.subscribe('my-channel', onMessage);\n\ndiagnostics_channel.unsubscribe('my-channel', onMessage);\n</code></pre>\n<pre><code class=\"language-cjs\">const diagnostics_channel = require('node:diagnostics_channel');\n\nfunction onMessage(message, name) {\n // Received data\n}\n\ndiagnostics_channel.subscribe('my-channel', onMessage);\n\ndiagnostics_channel.unsubscribe('my-channel', onMessage);\n</code></pre>" 176 }, 177 { 178 "textRaw": "`diagnostics_channel.tracingChannel(nameOrChannels)`", 179 "type": "method", 180 "name": "tracingChannel", 181 "meta": { 182 "added": [ 183 "v18.19.0" 184 ], 185 "changes": [] 186 }, 187 "stability": 1, 188 "stabilityText": "Experimental", 189 "signatures": [ 190 { 191 "return": { 192 "textRaw": "Returns: {TracingChannel} Collection of channels to trace with", 193 "name": "return", 194 "type": "TracingChannel", 195 "desc": "Collection of channels to trace with" 196 }, 197 "params": [ 198 { 199 "textRaw": "`nameOrChannels` {string|TracingChannel} Channel name or object containing all the [TracingChannel Channels][]", 200 "name": "nameOrChannels", 201 "type": "string|TracingChannel", 202 "desc": "Channel name or object containing all the [TracingChannel Channels][]" 203 } 204 ] 205 } 206 ], 207 "desc": "<p>Creates a <a href=\"#class-tracingchannel\"><code>TracingChannel</code></a> wrapper for the given\n<a href=\"#tracingchannel-channels\">TracingChannel Channels</a>. If a name is given, the corresponding tracing\nchannels will be created in the form of <code>tracing:${name}:${eventType}</code> where\n<code>eventType</code> corresponds to the types of <a href=\"#tracingchannel-channels\">TracingChannel Channels</a>.</p>\n<pre><code class=\"language-mjs\">import diagnostics_channel from 'node:diagnostics_channel';\n\nconst channelsByName = diagnostics_channel.tracingChannel('my-channel');\n\n// or...\n\nconst channelsByCollection = diagnostics_channel.tracingChannel({\n start: diagnostics_channel.channel('tracing:my-channel:start'),\n end: diagnostics_channel.channel('tracing:my-channel:end'),\n asyncStart: diagnostics_channel.channel('tracing:my-channel:asyncStart'),\n asyncEnd: diagnostics_channel.channel('tracing:my-channel:asyncEnd'),\n error: diagnostics_channel.channel('tracing:my-channel:error'),\n});\n</code></pre>\n<pre><code class=\"language-cjs\">const diagnostics_channel = require('node:diagnostics_channel');\n\nconst channelsByName = diagnostics_channel.tracingChannel('my-channel');\n\n// or...\n\nconst channelsByCollection = diagnostics_channel.tracingChannel({\n start: diagnostics_channel.channel('tracing:my-channel:start'),\n end: diagnostics_channel.channel('tracing:my-channel:end'),\n asyncStart: diagnostics_channel.channel('tracing:my-channel:asyncStart'),\n asyncEnd: diagnostics_channel.channel('tracing:my-channel:asyncEnd'),\n error: diagnostics_channel.channel('tracing:my-channel:error'),\n});\n</code></pre>" 208 } 209 ], 210 "type": "module", 211 "displayName": "Overview" 212 }, 213 { 214 "textRaw": "TracingChannel Channels", 215 "name": "tracingchannel_channels", 216 "desc": "<p>A TracingChannel is a collection of several diagnostics_channels representing\nspecific points in the execution lifecycle of a single traceable action. The\nbehaviour is split into five diagnostics_channels consisting of <code>start</code>,\n<code>end</code>, <code>asyncStart</code>, <code>asyncEnd</code>, and <code>error</code>. A single traceable action will\nshare the same event object between all events, this can be helpful for\nmanaging correlation through a weakmap.</p>\n<p>These event objects will be extended with <code>result</code> or <code>error</code> values when\nthe task \"completes\". In the case of a synchronous task the <code>result</code> will be\nthe return value and the <code>error</code> will be anything thrown from the function.\nWith callback-based async functions the <code>result</code> will be the second argument\nof the callback while the <code>error</code> will either be a thrown error visible in the\n<code>end</code> event or the first callback argument in either of the <code>asyncStart</code> or\n<code>asyncEnd</code> events.</p>\n<p>Tracing channels should follow a naming pattern of:</p>\n<ul>\n<li><code>tracing:module.class.method:start</code> or <code>tracing:module.function:start</code></li>\n<li><code>tracing:module.class.method:end</code> or <code>tracing:module.function:end</code></li>\n<li><code>tracing:module.class.method:asyncStart</code> or <code>tracing:module.function:asyncStart</code></li>\n<li><code>tracing:module.class.method:asyncEnd</code> or <code>tracing:module.function:asyncEnd</code></li>\n<li><code>tracing:module.class.method:error</code> or <code>tracing:module.function:error</code></li>\n</ul>", 217 "methods": [ 218 { 219 "textRaw": "`start(event)`", 220 "type": "method", 221 "name": "start", 222 "signatures": [ 223 { 224 "params": [ 225 { 226 "textRaw": "Name: `tracing:${name}:start`", 227 "name": "Name", 228 "desc": "`tracing:${name}:start`" 229 } 230 ] 231 } 232 ], 233 "desc": "<p>The <code>start</code> event represents the point at which a function is called. At this\npoint the event data may contain function arguments or anything else available\nat the very start of the execution of the function.</p>" 234 }, 235 { 236 "textRaw": "`end(event)`", 237 "type": "method", 238 "name": "end", 239 "signatures": [ 240 { 241 "params": [ 242 { 243 "textRaw": "Name: `tracing:${name}:end`", 244 "name": "Name", 245 "desc": "`tracing:${name}:end`" 246 } 247 ] 248 } 249 ], 250 "desc": "<p>The <code>end</code> event represents the point at which a function call returns a value.\nIn the case of an async function this is when the promise returned not when the\nfunction itself makes a return statement internally. At this point, if the\ntraced function was synchronous the <code>result</code> field will be set to the return\nvalue of the function. Alternatively, the <code>error</code> field may be present to\nrepresent any thrown errors.</p>\n<p>It is recommended to listen specifically to the <code>error</code> event to track errors\nas it may be possible for a traceable action to produce multiple errors. For\nexample, an async task which fails may be started internally before the sync\npart of the task then throws an error.</p>" 251 }, 252 { 253 "textRaw": "`asyncStart(event)`", 254 "type": "method", 255 "name": "asyncStart", 256 "signatures": [ 257 { 258 "params": [ 259 { 260 "textRaw": "Name: `tracing:${name}:asyncStart`", 261 "name": "Name", 262 "desc": "`tracing:${name}:asyncStart`" 263 } 264 ] 265 } 266 ], 267 "desc": "<p>The <code>asyncStart</code> event represents the callback or continuation of a traceable\nfunction being reached. At this point things like callback arguments may be\navailable, or anything else expressing the \"result\" of the action.</p>\n<p>For callbacks-based functions, the first argument of the callback will be\nassigned to the <code>error</code> field, if not <code>undefined</code> or <code>null</code>, and the second\nargument will be assigned to the <code>result</code> field.</p>\n<p>For promises, the argument to the <code>resolve</code> path will be assigned to <code>result</code>\nor the argument to the <code>reject</code> path will be assign to <code>error</code>.</p>\n<p>It is recommended to listen specifically to the <code>error</code> event to track errors\nas it may be possible for a traceable action to produce multiple errors. For\nexample, an async task which fails may be started internally before the sync\npart of the task then throws an error.</p>" 268 }, 269 { 270 "textRaw": "`asyncEnd(event)`", 271 "type": "method", 272 "name": "asyncEnd", 273 "signatures": [ 274 { 275 "params": [ 276 { 277 "textRaw": "Name: `tracing:${name}:asyncEnd`", 278 "name": "Name", 279 "desc": "`tracing:${name}:asyncEnd`" 280 } 281 ] 282 } 283 ], 284 "desc": "<p>The <code>asyncEnd</code> event represents the callback of an asynchronous function\nreturning. It's not likely event data will change after the <code>asyncStart</code> event,\nhowever it may be useful to see the point where the callback completes.</p>" 285 }, 286 { 287 "textRaw": "`error(event)`", 288 "type": "method", 289 "name": "error", 290 "signatures": [ 291 { 292 "params": [ 293 { 294 "textRaw": "Name: `tracing:${name}:error`", 295 "name": "Name", 296 "desc": "`tracing:${name}:error`" 297 } 298 ] 299 } 300 ], 301 "desc": "<p>The <code>error</code> event represents any error produced by the traceable function\neither synchronously or asynchronously. If an error is thrown in the\nsynchronous portion of the traced function the error will be assigned to the\n<code>error</code> field of the event and the <code>error</code> event will be triggered. If an error\nis received asynchronously through a callback or promise rejection it will also\nbe assigned to the <code>error</code> field of the event and trigger the <code>error</code> event.</p>\n<p>It is possible for a single traceable function call to produce errors multiple\ntimes so this should be considered when consuming this event. For example, if\nanother async task is triggered internally which fails and then the sync part\nof the function then throws and error two <code>error</code> events will be emitted, one\nfor the sync error and one for the async error.</p>" 302 } 303 ], 304 "type": "module", 305 "displayName": "TracingChannel Channels" 306 }, 307 { 308 "textRaw": "Built-in Channels", 309 "name": "built-in_channels", 310 "stability": 1, 311 "stabilityText": "Experimental", 312 "desc": "<p>While the diagnostics_channel API is now considered stable, the built-in\nchannels currently available are not. Each channel must be declared stable\nindependently.</p>", 313 "modules": [ 314 { 315 "textRaw": "HTTP", 316 "name": "http", 317 "desc": "<p><code>http.client.request.start</code></p>\n<ul>\n<li><code>request</code> <a href=\"http.html#class-httpclientrequest\" class=\"type\"><http.ClientRequest></a></li>\n</ul>\n<p>Emitted when client starts a request.</p>\n<p><code>http.client.response.finish</code></p>\n<ul>\n<li><code>request</code> <a href=\"http.html#class-httpclientrequest\" class=\"type\"><http.ClientRequest></a></li>\n<li><code>response</code> <a href=\"http.html#class-httpincomingmessage\" class=\"type\"><http.IncomingMessage></a></li>\n</ul>\n<p>Emitted when client receives a response.</p>\n<p><code>http.server.request.start</code></p>\n<ul>\n<li><code>request</code> <a href=\"http.html#class-httpincomingmessage\" class=\"type\"><http.IncomingMessage></a></li>\n<li><code>response</code> <a href=\"http.html#class-httpserverresponse\" class=\"type\"><http.ServerResponse></a></li>\n<li><code>socket</code> <a href=\"net.html#class-netsocket\" class=\"type\"><net.Socket></a></li>\n<li><code>server</code> <a href=\"http.html#class-httpserver\" class=\"type\"><http.Server></a></li>\n</ul>\n<p>Emitted when server receives a request.</p>\n<p><code>http.server.response.finish</code></p>\n<ul>\n<li><code>request</code> <a href=\"http.html#class-httpincomingmessage\" class=\"type\"><http.IncomingMessage></a></li>\n<li><code>response</code> <a href=\"http.html#class-httpserverresponse\" class=\"type\"><http.ServerResponse></a></li>\n<li><code>socket</code> <a href=\"net.html#class-netsocket\" class=\"type\"><net.Socket></a></li>\n<li><code>server</code> <a href=\"http.html#class-httpserver\" class=\"type\"><http.Server></a></li>\n</ul>\n<p>Emitted when server sends a response.</p>\n<p><code>net.client.socket</code></p>\n<ul>\n<li><code>socket</code> <a href=\"net.html#class-netsocket\" class=\"type\"><net.Socket></a></li>\n</ul>\n<p>Emitted when a new TCP or pipe client socket is created.</p>\n<p><code>net.server.socket</code></p>\n<ul>\n<li><code>socket</code> <a href=\"net.html#class-netsocket\" class=\"type\"><net.Socket></a></li>\n</ul>\n<p>Emitted when a new TCP or pipe connection is received.</p>\n<p><code>udp.socket</code></p>\n<ul>\n<li><code>socket</code> <a href=\"dgram.html#class-dgramsocket\" class=\"type\"><dgram.Socket></a></li>\n</ul>\n<p>Emitted when a new UDP socket is created.</p>", 318 "type": "module", 319 "displayName": "HTTP" 320 } 321 ], 322 "type": "module", 323 "displayName": "Built-in Channels" 324 } 325 ], 326 "classes": [ 327 { 328 "textRaw": "Class: `Channel`", 329 "type": "class", 330 "name": "Channel", 331 "meta": { 332 "added": [ 333 "v15.1.0", 334 "v14.17.0" 335 ], 336 "changes": [] 337 }, 338 "desc": "<p>The class <code>Channel</code> represents an individual named channel within the data\npipeline. It is used to track subscribers and to publish messages when there\nare subscribers present. It exists as a separate object to avoid channel\nlookups at publish time, enabling very fast publish speeds and allowing\nfor heavy use while incurring very minimal cost. Channels are created with\n<a href=\"#diagnostics_channelchannelname\"><code>diagnostics_channel.channel(name)</code></a>, constructing a channel directly\nwith <code>new Channel(name)</code> is not supported.</p>", 339 "properties": [ 340 { 341 "textRaw": "`hasSubscribers` Returns: {boolean} If there are active subscribers", 342 "type": "boolean", 343 "name": "return", 344 "meta": { 345 "added": [ 346 "v15.1.0", 347 "v14.17.0" 348 ], 349 "changes": [] 350 }, 351 "desc": "<p>Check if there are active subscribers to this channel. This is helpful if\nthe message you want to send might be expensive to prepare.</p>\n<p>This API is optional but helpful when trying to publish messages from very\nperformance-sensitive code.</p>\n<pre><code class=\"language-mjs\">import diagnostics_channel from 'node:diagnostics_channel';\n\nconst channel = diagnostics_channel.channel('my-channel');\n\nif (channel.hasSubscribers) {\n // There are subscribers, prepare and publish message\n}\n</code></pre>\n<pre><code class=\"language-cjs\">const diagnostics_channel = require('node:diagnostics_channel');\n\nconst channel = diagnostics_channel.channel('my-channel');\n\nif (channel.hasSubscribers) {\n // There are subscribers, prepare and publish message\n}\n</code></pre>", 352 "shortDesc": "If there are active subscribers" 353 } 354 ], 355 "methods": [ 356 { 357 "textRaw": "`channel.publish(message)`", 358 "type": "method", 359 "name": "publish", 360 "meta": { 361 "added": [ 362 "v15.1.0", 363 "v14.17.0" 364 ], 365 "changes": [] 366 }, 367 "signatures": [ 368 { 369 "params": [ 370 { 371 "textRaw": "`message` {any} The message to send to the channel subscribers", 372 "name": "message", 373 "type": "any", 374 "desc": "The message to send to the channel subscribers" 375 } 376 ] 377 } 378 ], 379 "desc": "<p>Publish a message to any subscribers to the channel. This will trigger\nmessage handlers synchronously so they will execute within the same context.</p>\n<pre><code class=\"language-mjs\">import diagnostics_channel from 'node:diagnostics_channel';\n\nconst channel = diagnostics_channel.channel('my-channel');\n\nchannel.publish({\n some: 'message',\n});\n</code></pre>\n<pre><code class=\"language-cjs\">const diagnostics_channel = require('node:diagnostics_channel');\n\nconst channel = diagnostics_channel.channel('my-channel');\n\nchannel.publish({\n some: 'message',\n});\n</code></pre>" 380 }, 381 { 382 "textRaw": "`channel.subscribe(onMessage)`", 383 "type": "method", 384 "name": "subscribe", 385 "meta": { 386 "added": [ 387 "v15.1.0", 388 "v14.17.0" 389 ], 390 "deprecated": [ 391 "v18.7.0" 392 ], 393 "changes": [] 394 }, 395 "stability": 0, 396 "stabilityText": "Deprecated: Use [`diagnostics_channel.subscribe(name, onMessage)`][]", 397 "signatures": [ 398 { 399 "params": [ 400 { 401 "textRaw": "`onMessage` {Function} The handler to receive channel messages", 402 "name": "onMessage", 403 "type": "Function", 404 "desc": "The handler to receive channel messages", 405 "options": [ 406 { 407 "textRaw": "`message` {any} The message data", 408 "name": "message", 409 "type": "any", 410 "desc": "The message data" 411 }, 412 { 413 "textRaw": "`name` {string|symbol} The name of the channel", 414 "name": "name", 415 "type": "string|symbol", 416 "desc": "The name of the channel" 417 } 418 ] 419 } 420 ] 421 } 422 ], 423 "desc": "<p>Register a message handler to subscribe to this channel. This message handler\nwill be run synchronously whenever a message is published to the channel. Any\nerrors thrown in the message handler will trigger an <a href=\"process.html#event-uncaughtexception\"><code>'uncaughtException'</code></a>.</p>\n<pre><code class=\"language-mjs\">import diagnostics_channel from 'node:diagnostics_channel';\n\nconst channel = diagnostics_channel.channel('my-channel');\n\nchannel.subscribe((message, name) => {\n // Received data\n});\n</code></pre>\n<pre><code class=\"language-cjs\">const diagnostics_channel = require('node:diagnostics_channel');\n\nconst channel = diagnostics_channel.channel('my-channel');\n\nchannel.subscribe((message, name) => {\n // Received data\n});\n</code></pre>" 424 }, 425 { 426 "textRaw": "`channel.unsubscribe(onMessage)`", 427 "type": "method", 428 "name": "unsubscribe", 429 "meta": { 430 "added": [ 431 "v15.1.0", 432 "v14.17.0" 433 ], 434 "deprecated": [ 435 "v18.7.0" 436 ], 437 "changes": [ 438 { 439 "version": [ 440 "v17.1.0", 441 "v16.14.0", 442 "v14.19.0" 443 ], 444 "pr-url": "https://github.com/nodejs/node/pull/40433", 445 "description": "Added return value. Added to channels without subscribers." 446 } 447 ] 448 }, 449 "stability": 0, 450 "stabilityText": "Deprecated: Use [`diagnostics_channel.unsubscribe(name, onMessage)`][]", 451 "signatures": [ 452 { 453 "return": { 454 "textRaw": "Returns: {boolean} `true` if the handler was found, `false` otherwise.", 455 "name": "return", 456 "type": "boolean", 457 "desc": "`true` if the handler was found, `false` otherwise." 458 }, 459 "params": [ 460 { 461 "textRaw": "`onMessage` {Function} The previous subscribed handler to remove", 462 "name": "onMessage", 463 "type": "Function", 464 "desc": "The previous subscribed handler to remove" 465 } 466 ] 467 } 468 ], 469 "desc": "<p>Remove a message handler previously registered to this channel with\n<a href=\"#channelsubscribeonmessage\"><code>channel.subscribe(onMessage)</code></a>.</p>\n<pre><code class=\"language-mjs\">import diagnostics_channel from 'node:diagnostics_channel';\n\nconst channel = diagnostics_channel.channel('my-channel');\n\nfunction onMessage(message, name) {\n // Received data\n}\n\nchannel.subscribe(onMessage);\n\nchannel.unsubscribe(onMessage);\n</code></pre>\n<pre><code class=\"language-cjs\">const diagnostics_channel = require('node:diagnostics_channel');\n\nconst channel = diagnostics_channel.channel('my-channel');\n\nfunction onMessage(message, name) {\n // Received data\n}\n\nchannel.subscribe(onMessage);\n\nchannel.unsubscribe(onMessage);\n</code></pre>" 470 }, 471 { 472 "textRaw": "`channel.bindStore(store[, transform])`", 473 "type": "method", 474 "name": "bindStore", 475 "meta": { 476 "added": [ 477 "v18.19.0" 478 ], 479 "changes": [] 480 }, 481 "stability": 1, 482 "stabilityText": "Experimental", 483 "signatures": [ 484 { 485 "params": [ 486 { 487 "textRaw": "`store` {AsyncLocalStorage} The store to which to bind the context data", 488 "name": "store", 489 "type": "AsyncLocalStorage", 490 "desc": "The store to which to bind the context data" 491 }, 492 { 493 "textRaw": "`transform` {Function} Transform context data before setting the store context", 494 "name": "transform", 495 "type": "Function", 496 "desc": "Transform context data before setting the store context" 497 } 498 ] 499 } 500 ], 501 "desc": "<p>When <a href=\"#channelrunstorescontext-fn-thisarg-args\"><code>channel.runStores(context, ...)</code></a> is called, the given context data\nwill be applied to any store bound to the channel. If the store has already been\nbound the previous <code>transform</code> function will be replaced with the new one.\nThe <code>transform</code> function may be omitted to set the given context data as the\ncontext directly.</p>\n<pre><code class=\"language-mjs\">import diagnostics_channel from 'node:diagnostics_channel';\nimport { AsyncLocalStorage } from 'node:async_hooks';\n\nconst store = new AsyncLocalStorage();\n\nconst channel = diagnostics_channel.channel('my-channel');\n\nchannel.bindStore(store, (data) => {\n return { data };\n});\n</code></pre>\n<pre><code class=\"language-cjs\">const diagnostics_channel = require('node:diagnostics_channel');\nconst { AsyncLocalStorage } = require('node:async_hooks');\n\nconst store = new AsyncLocalStorage();\n\nconst channel = diagnostics_channel.channel('my-channel');\n\nchannel.bindStore(store, (data) => {\n return { data };\n});\n</code></pre>" 502 }, 503 { 504 "textRaw": "`channel.unbindStore(store)`", 505 "type": "method", 506 "name": "unbindStore", 507 "meta": { 508 "added": [ 509 "v18.19.0" 510 ], 511 "changes": [] 512 }, 513 "stability": 1, 514 "stabilityText": "Experimental", 515 "signatures": [ 516 { 517 "return": { 518 "textRaw": "Returns: {boolean} `true` if the store was found, `false` otherwise.", 519 "name": "return", 520 "type": "boolean", 521 "desc": "`true` if the store was found, `false` otherwise." 522 }, 523 "params": [ 524 { 525 "textRaw": "`store` {AsyncLocalStorage} The store to unbind from the channel.", 526 "name": "store", 527 "type": "AsyncLocalStorage", 528 "desc": "The store to unbind from the channel." 529 } 530 ] 531 } 532 ], 533 "desc": "<p>Remove a message handler previously registered to this channel with\n<a href=\"#channelbindstorestore-transform\"><code>channel.bindStore(store)</code></a>.</p>\n<pre><code class=\"language-mjs\">import diagnostics_channel from 'node:diagnostics_channel';\nimport { AsyncLocalStorage } from 'node:async_hooks';\n\nconst store = new AsyncLocalStorage();\n\nconst channel = diagnostics_channel.channel('my-channel');\n\nchannel.bindStore(store);\nchannel.unbindStore(store);\n</code></pre>\n<pre><code class=\"language-cjs\">const diagnostics_channel = require('node:diagnostics_channel');\nconst { AsyncLocalStorage } = require('node:async_hooks');\n\nconst store = new AsyncLocalStorage();\n\nconst channel = diagnostics_channel.channel('my-channel');\n\nchannel.bindStore(store);\nchannel.unbindStore(store);\n</code></pre>" 534 }, 535 { 536 "textRaw": "`channel.runStores(context, fn[, thisArg[, ...args]])`", 537 "type": "method", 538 "name": "runStores", 539 "meta": { 540 "added": [ 541 "v18.19.0" 542 ], 543 "changes": [] 544 }, 545 "stability": 1, 546 "stabilityText": "Experimental", 547 "signatures": [ 548 { 549 "params": [ 550 { 551 "textRaw": "`context` {any} Message to send to subscribers and bind to stores", 552 "name": "context", 553 "type": "any", 554 "desc": "Message to send to subscribers and bind to stores" 555 }, 556 { 557 "textRaw": "`fn` {Function} Handler to run within the entered storage context", 558 "name": "fn", 559 "type": "Function", 560 "desc": "Handler to run within the entered storage context" 561 }, 562 { 563 "textRaw": "`thisArg` {any} The receiver to be used for the function call.", 564 "name": "thisArg", 565 "type": "any", 566 "desc": "The receiver to be used for the function call." 567 }, 568 { 569 "textRaw": "`...args` {any} Optional arguments to pass to the function.", 570 "name": "...args", 571 "type": "any", 572 "desc": "Optional arguments to pass to the function." 573 } 574 ] 575 } 576 ], 577 "desc": "<p>Applies the given data to any AsyncLocalStorage instances bound to the channel\nfor the duration of the given function, then publishes to the channel within\nthe scope of that data is applied to the stores.</p>\n<p>If a transform function was given to <a href=\"#channelbindstorestore-transform\"><code>channel.bindStore(store)</code></a> it will be\napplied to transform the message data before it becomes the context value for\nthe store. The prior storage context is accessible from within the transform\nfunction in cases where context linking is required.</p>\n<p>The context applied to the store should be accesible in any async code which\ncontinues from execution which began during the given function, however\nthere are some situations in which <a href=\"async_context.html#troubleshooting-context-loss\">context loss</a> may occur.</p>\n<pre><code class=\"language-mjs\">import diagnostics_channel from 'node:diagnostics_channel';\nimport { AsyncLocalStorage } from 'node:async_hooks';\n\nconst store = new AsyncLocalStorage();\n\nconst channel = diagnostics_channel.channel('my-channel');\n\nchannel.bindStore(store, (message) => {\n const parent = store.getStore();\n return new Span(message, parent);\n});\nchannel.runStores({ some: 'message' }, () => {\n store.getStore(); // Span({ some: 'message' })\n});\n</code></pre>\n<pre><code class=\"language-cjs\">const diagnostics_channel = require('node:diagnostics_channel');\nconst { AsyncLocalStorage } = require('node:async_hooks');\n\nconst store = new AsyncLocalStorage();\n\nconst channel = diagnostics_channel.channel('my-channel');\n\nchannel.bindStore(store, (message) => {\n const parent = store.getStore();\n return new Span(message, parent);\n});\nchannel.runStores({ some: 'message' }, () => {\n store.getStore(); // Span({ some: 'message' })\n});\n</code></pre>" 578 } 579 ] 580 }, 581 { 582 "textRaw": "Class: `TracingChannel`", 583 "type": "class", 584 "name": "TracingChannel", 585 "meta": { 586 "added": [ 587 "v18.19.0" 588 ], 589 "changes": [] 590 }, 591 "stability": 1, 592 "stabilityText": "Experimental", 593 "desc": "<p>The class <code>TracingChannel</code> is a collection of <a href=\"#tracingchannel-channels\">TracingChannel Channels</a> which\ntogether express a single traceable action. It is used to formalize and\nsimplify the process of producing events for tracing application flow.\n<a href=\"#diagnostics_channeltracingchannelnameorchannels\"><code>diagnostics_channel.tracingChannel()</code></a> is used to construct a\n<code>TracingChannel</code>. As with <code>Channel</code> it is recommended to create and reuse a\nsingle <code>TracingChannel</code> at the top-level of the file rather than creating them\ndynamically.</p>", 594 "methods": [ 595 { 596 "textRaw": "`tracingChannel.subscribe(subscribers)`", 597 "type": "method", 598 "name": "subscribe", 599 "meta": { 600 "added": [ 601 "v18.19.0" 602 ], 603 "changes": [] 604 }, 605 "stability": 1, 606 "stabilityText": "Experimental", 607 "signatures": [ 608 { 609 "params": [ 610 { 611 "textRaw": "`subscribers` {Object} Set of [TracingChannel Channels][] subscribers", 612 "name": "subscribers", 613 "type": "Object", 614 "desc": "Set of [TracingChannel Channels][] subscribers", 615 "options": [ 616 { 617 "textRaw": "`start` {Function} The [`start` event][] subscriber", 618 "name": "start", 619 "type": "Function", 620 "desc": "The [`start` event][] subscriber" 621 }, 622 { 623 "textRaw": "`end` {Function} The [`end` event][] subscriber", 624 "name": "end", 625 "type": "Function", 626 "desc": "The [`end` event][] subscriber" 627 }, 628 { 629 "textRaw": "`asyncStart` {Function} The [`asyncStart` event][] subscriber", 630 "name": "asyncStart", 631 "type": "Function", 632 "desc": "The [`asyncStart` event][] subscriber" 633 }, 634 { 635 "textRaw": "`asyncEnd` {Function} The [`asyncEnd` event][] subscriber", 636 "name": "asyncEnd", 637 "type": "Function", 638 "desc": "The [`asyncEnd` event][] subscriber" 639 }, 640 { 641 "textRaw": "`error` {Function} The [`error` event][] subscriber", 642 "name": "error", 643 "type": "Function", 644 "desc": "The [`error` event][] subscriber" 645 } 646 ] 647 } 648 ] 649 } 650 ], 651 "desc": "<p>Helper to subscribe a collection of functions to the corresponding channels.\nThis is the same as calling <a href=\"#channelsubscribeonmessage\"><code>channel.subscribe(onMessage)</code></a> on each channel\nindividually.</p>\n<pre><code class=\"language-mjs\">import diagnostics_channel from 'node:diagnostics_channel';\n\nconst channels = diagnostics_channel.tracingChannel('my-channel');\n\nchannels.subscribe({\n start(message) {\n // Handle start message\n },\n end(message) {\n // Handle end message\n },\n asyncStart(message) {\n // Handle asyncStart message\n },\n asyncEnd(message) {\n // Handle asyncEnd message\n },\n error(message) {\n // Handle error message\n },\n});\n</code></pre>\n<pre><code class=\"language-cjs\">const diagnostics_channel = require('node:diagnostics_channel');\n\nconst channels = diagnostics_channel.tracingChannel('my-channel');\n\nchannels.subscribe({\n start(message) {\n // Handle start message\n },\n end(message) {\n // Handle end message\n },\n asyncStart(message) {\n // Handle asyncStart message\n },\n asyncEnd(message) {\n // Handle asyncEnd message\n },\n error(message) {\n // Handle error message\n },\n});\n</code></pre>" 652 }, 653 { 654 "textRaw": "`tracingChannel.unsubscribe(subscribers)`", 655 "type": "method", 656 "name": "unsubscribe", 657 "meta": { 658 "added": [ 659 "v18.19.0" 660 ], 661 "changes": [] 662 }, 663 "stability": 1, 664 "stabilityText": "Experimental", 665 "signatures": [ 666 { 667 "return": { 668 "textRaw": "Returns: {boolean} `true` if all handlers were successfully unsubscribed, and `false` otherwise.", 669 "name": "return", 670 "type": "boolean", 671 "desc": "`true` if all handlers were successfully unsubscribed, and `false` otherwise." 672 }, 673 "params": [ 674 { 675 "textRaw": "`subscribers` {Object} Set of [TracingChannel Channels][] subscribers", 676 "name": "subscribers", 677 "type": "Object", 678 "desc": "Set of [TracingChannel Channels][] subscribers", 679 "options": [ 680 { 681 "textRaw": "`start` {Function} The [`start` event][] subscriber", 682 "name": "start", 683 "type": "Function", 684 "desc": "The [`start` event][] subscriber" 685 }, 686 { 687 "textRaw": "`end` {Function} The [`end` event][] subscriber", 688 "name": "end", 689 "type": "Function", 690 "desc": "The [`end` event][] subscriber" 691 }, 692 { 693 "textRaw": "`asyncStart` {Function} The [`asyncStart` event][] subscriber", 694 "name": "asyncStart", 695 "type": "Function", 696 "desc": "The [`asyncStart` event][] subscriber" 697 }, 698 { 699 "textRaw": "`asyncEnd` {Function} The [`asyncEnd` event][] subscriber", 700 "name": "asyncEnd", 701 "type": "Function", 702 "desc": "The [`asyncEnd` event][] subscriber" 703 }, 704 { 705 "textRaw": "`error` {Function} The [`error` event][] subscriber", 706 "name": "error", 707 "type": "Function", 708 "desc": "The [`error` event][] subscriber" 709 } 710 ] 711 } 712 ] 713 } 714 ], 715 "desc": "<p>Helper to unsubscribe a collection of functions from the corresponding channels.\nThis is the same as calling <a href=\"#channelunsubscribeonmessage\"><code>channel.unsubscribe(onMessage)</code></a> on each channel\nindividually.</p>\n<pre><code class=\"language-mjs\">import diagnostics_channel from 'node:diagnostics_channel';\n\nconst channels = diagnostics_channel.tracingChannel('my-channel');\n\nchannels.unsubscribe({\n start(message) {\n // Handle start message\n },\n end(message) {\n // Handle end message\n },\n asyncStart(message) {\n // Handle asyncStart message\n },\n asyncEnd(message) {\n // Handle asyncEnd message\n },\n error(message) {\n // Handle error message\n },\n});\n</code></pre>\n<pre><code class=\"language-cjs\">const diagnostics_channel = require('node:diagnostics_channel');\n\nconst channels = diagnostics_channel.tracingChannel('my-channel');\n\nchannels.unsubscribe({\n start(message) {\n // Handle start message\n },\n end(message) {\n // Handle end message\n },\n asyncStart(message) {\n // Handle asyncStart message\n },\n asyncEnd(message) {\n // Handle asyncEnd message\n },\n error(message) {\n // Handle error message\n },\n});\n</code></pre>" 716 }, 717 { 718 "textRaw": "`tracingChannel.traceSync(fn[, context[, thisArg[, ...args]]])`", 719 "type": "method", 720 "name": "traceSync", 721 "meta": { 722 "added": [ 723 "v18.19.0" 724 ], 725 "changes": [] 726 }, 727 "stability": 1, 728 "stabilityText": "Experimental", 729 "signatures": [ 730 { 731 "return": { 732 "textRaw": "Returns: {any} The return value of the given function", 733 "name": "return", 734 "type": "any", 735 "desc": "The return value of the given function" 736 }, 737 "params": [ 738 { 739 "textRaw": "`fn` {Function} Function to wrap a trace around", 740 "name": "fn", 741 "type": "Function", 742 "desc": "Function to wrap a trace around" 743 }, 744 { 745 "textRaw": "`context` {Object} Shared object to correlate events through", 746 "name": "context", 747 "type": "Object", 748 "desc": "Shared object to correlate events through" 749 }, 750 { 751 "textRaw": "`thisArg` {any} The receiver to be used for the function call", 752 "name": "thisArg", 753 "type": "any", 754 "desc": "The receiver to be used for the function call" 755 }, 756 { 757 "textRaw": "`...args` {any} Optional arguments to pass to the function", 758 "name": "...args", 759 "type": "any", 760 "desc": "Optional arguments to pass to the function" 761 } 762 ] 763 } 764 ], 765 "desc": "<p>Trace a synchronous function call. This will always produce a <a href=\"#startevent\"><code>start</code> event</a>\nand <a href=\"#endevent\"><code>end</code> event</a> around the execution and may produce an <a href=\"#errorevent\"><code>error</code> event</a>\nif the given function throws an error. This will run the given function using\n<a href=\"#channelrunstorescontext-fn-thisarg-args\"><code>channel.runStores(context, ...)</code></a> on the <code>start</code> channel which ensures all\nevents should have any bound stores set to match this trace context.</p>\n<pre><code class=\"language-mjs\">import diagnostics_channel from 'node:diagnostics_channel';\n\nconst channels = diagnostics_channel.tracingChannel('my-channel');\n\nchannels.traceSync(() => {\n // Do something\n}, {\n some: 'thing',\n});\n</code></pre>\n<pre><code class=\"language-cjs\">const diagnostics_channel = require('node:diagnostics_channel');\n\nconst channels = diagnostics_channel.tracingChannel('my-channel');\n\nchannels.traceSync(() => {\n // Do something\n}, {\n some: 'thing',\n});\n</code></pre>" 766 }, 767 { 768 "textRaw": "`tracingChannel.tracePromise(fn[, context[, thisArg[, ...args]]])`", 769 "type": "method", 770 "name": "tracePromise", 771 "meta": { 772 "added": [ 773 "v18.19.0" 774 ], 775 "changes": [] 776 }, 777 "stability": 1, 778 "stabilityText": "Experimental", 779 "signatures": [ 780 { 781 "return": { 782 "textRaw": "Returns: {Promise} Chained from promise returned by the given function", 783 "name": "return", 784 "type": "Promise", 785 "desc": "Chained from promise returned by the given function" 786 }, 787 "params": [ 788 { 789 "textRaw": "`fn` {Function} Promise-returning function to wrap a trace around", 790 "name": "fn", 791 "type": "Function", 792 "desc": "Promise-returning function to wrap a trace around" 793 }, 794 { 795 "textRaw": "`context` {Object} Shared object to correlate trace events through", 796 "name": "context", 797 "type": "Object", 798 "desc": "Shared object to correlate trace events through" 799 }, 800 { 801 "textRaw": "`thisArg` {any} The receiver to be used for the function call", 802 "name": "thisArg", 803 "type": "any", 804 "desc": "The receiver to be used for the function call" 805 }, 806 { 807 "textRaw": "`...args` {any} Optional arguments to pass to the function", 808 "name": "...args", 809 "type": "any", 810 "desc": "Optional arguments to pass to the function" 811 } 812 ] 813 } 814 ], 815 "desc": "<p>Trace a promise-returning function call. This will always produce a\n<a href=\"#startevent\"><code>start</code> event</a> and <a href=\"#endevent\"><code>end</code> event</a> around the synchronous portion of the\nfunction execution, and will produce an <a href=\"#asyncstartevent\"><code>asyncStart</code> event</a> and\n<a href=\"#asyncendevent\"><code>asyncEnd</code> event</a> when a promise continuation is reached. It may also\nproduce an <a href=\"#errorevent\"><code>error</code> event</a> if the given function throws an error or the\nreturned promise rejects. This will run the given function using\n<a href=\"#channelrunstorescontext-fn-thisarg-args\"><code>channel.runStores(context, ...)</code></a> on the <code>start</code> channel which ensures all\nevents should have any bound stores set to match this trace context.</p>\n<pre><code class=\"language-mjs\">import diagnostics_channel from 'node:diagnostics_channel';\n\nconst channels = diagnostics_channel.tracingChannel('my-channel');\n\nchannels.tracePromise(async () => {\n // Do something\n}, {\n some: 'thing',\n});\n</code></pre>\n<pre><code class=\"language-cjs\">const diagnostics_channel = require('node:diagnostics_channel');\n\nconst channels = diagnostics_channel.tracingChannel('my-channel');\n\nchannels.tracePromise(async () => {\n // Do something\n}, {\n some: 'thing',\n});\n</code></pre>" 816 }, 817 { 818 "textRaw": "`tracingChannel.traceCallback(fn[, position[, context[, thisArg[, ...args]]]])`", 819 "type": "method", 820 "name": "traceCallback", 821 "meta": { 822 "added": [ 823 "v18.19.0" 824 ], 825 "changes": [] 826 }, 827 "stability": 1, 828 "stabilityText": "Experimental", 829 "signatures": [ 830 { 831 "return": { 832 "textRaw": "Returns: {any} The return value of the given function", 833 "name": "return", 834 "type": "any", 835 "desc": "The return value of the given function" 836 }, 837 "params": [ 838 { 839 "textRaw": "`fn` {Function} callback using function to wrap a trace around", 840 "name": "fn", 841 "type": "Function", 842 "desc": "callback using function to wrap a trace around" 843 }, 844 { 845 "textRaw": "`position` {number} Zero-indexed argument position of expected callback", 846 "name": "position", 847 "type": "number", 848 "desc": "Zero-indexed argument position of expected callback" 849 }, 850 { 851 "textRaw": "`context` {Object} Shared object to correlate trace events through", 852 "name": "context", 853 "type": "Object", 854 "desc": "Shared object to correlate trace events through" 855 }, 856 { 857 "textRaw": "`thisArg` {any} The receiver to be used for the function call", 858 "name": "thisArg", 859 "type": "any", 860 "desc": "The receiver to be used for the function call" 861 }, 862 { 863 "textRaw": "`...args` {any} Optional arguments to pass to the function", 864 "name": "...args", 865 "type": "any", 866 "desc": "Optional arguments to pass to the function" 867 } 868 ] 869 } 870 ], 871 "desc": "<p>Trace a callback-receiving function call. This will always produce a\n<a href=\"#startevent\"><code>start</code> event</a> and <a href=\"#endevent\"><code>end</code> event</a> around the synchronous portion of the\nfunction execution, and will produce a <a href=\"#asyncstartevent\"><code>asyncStart</code> event</a> and\n<a href=\"#asyncendevent\"><code>asyncEnd</code> event</a> around the callback execution. It may also produce an\n<a href=\"#errorevent\"><code>error</code> event</a> if the given function throws an error or the returned\npromise rejects. This will run the given function using\n<a href=\"#channelrunstorescontext-fn-thisarg-args\"><code>channel.runStores(context, ...)</code></a> on the <code>start</code> channel which ensures all\nevents should have any bound stores set to match this trace context.</p>\n<p>The <code>position</code> will be -1 by default to indicate the final argument should\nbe used as the callback.</p>\n<pre><code class=\"language-mjs\">import diagnostics_channel from 'node:diagnostics_channel';\n\nconst channels = diagnostics_channel.tracingChannel('my-channel');\n\nchannels.traceCallback((arg1, callback) => {\n // Do something\n callback(null, 'result');\n}, 1, {\n some: 'thing',\n}, thisArg, arg1, callback);\n</code></pre>\n<pre><code class=\"language-cjs\">const diagnostics_channel = require('node:diagnostics_channel');\n\nconst channels = diagnostics_channel.tracingChannel('my-channel');\n\nchannels.traceCallback((arg1, callback) => {\n // Do something\n callback(null, 'result');\n}, {\n some: 'thing',\n}, thisArg, arg1, callback);\n</code></pre>\n<p>The callback will also be run with <a href=\"#channelrunstorescontext-fn-thisarg-args\"><code>channel.runStores(context, ...)</code></a> which\nenables context loss recovery in some cases.</p>\n<pre><code class=\"language-mjs\">import diagnostics_channel from 'node:diagnostics_channel';\nimport { AsyncLocalStorage } from 'node:async_hooks';\n\nconst channels = diagnostics_channel.tracingChannel('my-channel');\nconst myStore = new AsyncLocalStorage();\n\n// The start channel sets the initial store data to something\n// and stores that store data value on the trace context object\nchannels.start.bindStore(myStore, (data) => {\n const span = new Span(data);\n data.span = span;\n return span;\n});\n\n// Then asyncStart can restore from that data it stored previously\nchannels.asyncStart.bindStore(myStore, (data) => {\n return data.span;\n});\n</code></pre>\n<pre><code class=\"language-cjs\">const diagnostics_channel = require('node:diagnostics_channel');\nconst { AsyncLocalStorage } = require('node:async_hooks');\n\nconst channels = diagnostics_channel.tracingChannel('my-channel');\nconst myStore = new AsyncLocalStorage();\n\n// The start channel sets the initial store data to something\n// and stores that store data value on the trace context object\nchannels.start.bindStore(myStore, (data) => {\n const span = new Span(data);\n data.span = span;\n return span;\n});\n\n// Then asyncStart can restore from that data it stored previously\nchannels.asyncStart.bindStore(myStore, (data) => {\n return data.span;\n});\n</code></pre>" 872 } 873 ] 874 } 875 ], 876 "type": "module", 877 "displayName": "Public API" 878 } 879 ], 880 "type": "module", 881 "displayName": "Diagnostics Channel" 882 } 883 ] 884}