From a9a5bd64528e66cb17d75fa6b9d81a333f3a4c23 Mon Sep 17 00:00:00 2001
From: Thomas Hunter II <tlhunter@datadog.com>
Date: Wed, 8 May 2024 13:12:57 -0700
Subject: [PATCH] doc, test: tracing channel hasSubscribers getter

follow up work for https://github.com/nodejs/node/pull/51915
---
 doc/api/diagnostics_channel.md                | 37 +++++++++++++
 ...channel-tracing-channel-has-subscribers.js | 52 +++++++++++++++++++
 2 files changed, 89 insertions(+)
 create mode 100644 test/parallel/test-diagnostics-channel-tracing-channel-has-subscribers.js

diff --git a/doc/api/diagnostics_channel.md b/doc/api/diagnostics_channel.md
index e27c55eedf3a61..9d5732cc1539b6 100644
--- a/doc/api/diagnostics_channel.md
+++ b/doc/api/diagnostics_channel.md
@@ -977,6 +977,43 @@ channels.asyncStart.bindStore(myStore, (data) => {
 });
 ```
 
+#### `tracingChannel.hasSubscribers`
+
+<!-- YAML
+added:
+ - v22.0.0
+ - v20.13.0
+-->
+
+> Stability: 1 - Experimental
+
+* Returns: {boolean} `true` if any of the individual channels has a subscriber,
+  `false` if not.
+
+This is a helper method available on a [`TracingChannel`][] instance to check if
+any of the [TracingChannel Channels][] have subscribers. A `true` is returned if
+any of them have at least one subscriber, a `false` is returned otherwise.
+
+```mjs
+import diagnostics_channel from 'node:diagnostics_channel';
+
+const channels = diagnostics_channel.tracingChannel('my-channel');
+
+if (channels.hasSubscribers) {
+  // Do something
+}
+```
+
+```cjs
+const diagnostics_channel = require('node:diagnostics_channel');
+
+const channels = diagnostics_channel.tracingChannel('my-channel');
+
+if (channels.hasSubscribers) {
+  // Do something
+}
+```
+
 ### TracingChannel Channels
 
 A TracingChannel is a collection of several diagnostics\_channels representing
diff --git a/test/parallel/test-diagnostics-channel-tracing-channel-has-subscribers.js b/test/parallel/test-diagnostics-channel-tracing-channel-has-subscribers.js
new file mode 100644
index 00000000000000..672bc77aa9d2d2
--- /dev/null
+++ b/test/parallel/test-diagnostics-channel-tracing-channel-has-subscribers.js
@@ -0,0 +1,52 @@
+'use strict';
+
+const common = require('../common');
+const dc = require('diagnostics_channel');
+const assert = require('assert');
+
+const handler = common.mustNotCall();
+
+{
+  const handlers = {
+    start: common.mustNotCall()
+  };
+
+  const channel = dc.tracingChannel('test');
+
+  assert.strictEqual(channel.hasSubscribers, false);
+
+  channel.subscribe(handlers);
+  assert.strictEqual(channel.hasSubscribers, true);
+
+  channel.unsubscribe(handlers);
+  assert.strictEqual(channel.hasSubscribers, false);
+
+  channel.start.subscribe(handler);
+  assert.strictEqual(channel.hasSubscribers, true);
+
+  channel.start.unsubscribe(handler);
+  assert.strictEqual(channel.hasSubscribers, false);
+}
+
+{
+  const handlers = {
+    asyncEnd: common.mustNotCall()
+  };
+
+  const channel = dc.tracingChannel('test');
+
+  assert.strictEqual(channel.hasSubscribers, false);
+
+  channel.subscribe(handlers);
+  assert.strictEqual(channel.hasSubscribers, true);
+
+  channel.unsubscribe(handlers);
+  assert.strictEqual(channel.hasSubscribers, false);
+
+  channel.asyncEnd.subscribe(handler);
+  assert.strictEqual(channel.hasSubscribers, true);
+
+  channel.asyncEnd.unsubscribe(handler);
+  assert.strictEqual(channel.hasSubscribers, false);
+}
+