diagnostics_channel: add USDT probes

Fire a `dc__publish` USDT probe for every diagnostics_channel
publish, passing the channel name, so tracers such as bpftrace,
perf, or SystemTap can observe publish traffic with near-zero cost
when nothing is attached. Probes are enabled by default on Linux;
--without-dtrace disables them.

The probe semaphore is exposed to JS as a Uint16Array over the
native semaphore so the publish hot path can gate on one indexed
load instead of a binding call. The view is read through the
binding on every publish: it is created once per context, and any
cached reference (for example one captured while building a
startup snapshot) would be a stale copy after the snapshot is
deserialized, leaving probes disabled even while a tracer is
attached. On builds without USDT support the property is absent
and the hot path stays branch-only.

Signed-off-by: Bryan English <bryan@bryanenglish.com>
Assisted-by: Pi using GLM-5.3

Author: bengl

configure.py

@@ -1066,6 +1066,12 @@
     default=None,
     help='do not install the bundled Amaro (TypeScript utils)')
 
+parser.add_argument('--without-dtrace',
+    action='store_true',
+    dest='without_dtrace',
+    default=None,
+    help='build without DTrace/USDT probe support')
+
 parser.add_argument('--without-lief',
     action='store_true',
     dest='without_lief',
@@ -1360,6 +1366,31 @@ def B(value):
 def to_utf8(s):
   return s if isinstance(s, str) else s.decode("utf-8")
 
+def has_working_dtrace_h():
+  """Check whether a dtrace tool that supports -h is available.
+
+  Supported on Linux (SystemTap dtrace wrapper), macOS, FreeBSD, and
+  illumos/SmartOS (native DTrace).  Non-Linux platforms require -xnolibs
+  to avoid loading standard D libraries during header generation."""
+  dtrace = shutil.which('dtrace')
+  if dtrace is None:
+    return False
+  # -xnolibs is required on macOS/FreeBSD/illumos (native DTrace) to avoid
+  # loading standard D libraries.  Linux (SystemTap wrapper) does not
+  # recognise this flag, so only pass it on non-Linux platforms.
+  cmd = [dtrace, '-h', '-s', '/dev/stdin', '-o', '/dev/null']
+  if sys.platform != 'linux':
+    cmd.insert(2, '-xnolibs')
+  try:
+    proc = subprocess.run(
+        cmd,
+        input=b'provider _test { probe _test(); };',
+        capture_output=True, timeout=10)
+    return proc.returncode == 0
+  except (OSError, subprocess.TimeoutExpired) as e:
+    warn('dtrace probe check failed: %s' % e)
+    return False
+
 def pkg_config(pkg):
   """Run pkg-config on the specified package
   Returns ("-l flags", "-I flags", "-L flags", "version")
@@ -2180,6 +2211,16 @@ def configure_node(o):
     print('Warning! Loading builtin modules from disk is for development')
     o['variables']['node_builtin_modules_path'] = options.node_builtin_modules_path
 
+  o['variables']['node_no_usdt'] = b(options.without_dtrace)
+  use_dtrace = not options.without_dtrace and has_working_dtrace_h()
+  o['variables']['node_use_dtrace'] = b(use_dtrace)
+  if options.without_dtrace:
+    print('USDT probes: disabled (--without-dtrace)')
+  elif use_dtrace:
+    print('USDT probes: enabled (dtrace -h, semaphore support)')
+  else:
+    print('USDT probes: fallback (sys/sdt.h) or disabled')
+
 def configure_napi(output):
   version = getnapibuildversion.get_napi_version()
   output['variables']['napi_build_version'] = version

doc/api/diagnostics_channel.md

@@ -1529,6 +1529,82 @@ another async task is triggered internally which fails and then the sync part
 of the function then throws and error two `error` events will be emitted, one
 for the sync error and one for the async error.
 
+### USDT probes
+
+<!-- YAML
+added: REPLACEME
+-->
+
+> Stability: 1 - Experimental
+
+Node.js exposes a USDT (User-Level Statically Defined Tracing) probe for
+diagnostics channel publish events, enabling external observability tools
+such as `bpftrace`, DTrace, and `perf` to trace channel activity. Attaching a
+tracer does not activate inactive channels or bypass subscriber checks in
+publishers.
+
+#### Probe: `node:dc__publish`
+
+Fired when a message is published to a string-named diagnostics channel.
+When published from native (C++) code and a tracer is attached, the probe
+fires regardless of subscriber state.  When published from JavaScript, the
+probe fires only if the channel has active subscribers.  Some built-in
+modules publish from native code only when the channel has a JavaScript
+subscriber (for example the `sqlite.db.query` trace channel), so a tracer
+alone does not observe publishes from those modules.
+
+* `arg0` {const char\*} The channel name (UTF-8).
+* `arg1` {const void\*} An opaque pointer to the V8 message object, or `NULL`
+  if the published message is not a JavaScript object (e.g., a string, number,
+  or `null`).  **Warning:** This pointer is unstable and must NOT be
+  dereferenced by tracing scripts.  V8's garbage collector may move the
+  underlying object at any time.  The pointer is valid only for the
+  duration of the probe callback and must not be stored or compared
+  across separate probe firings.
+
+#### Platform support
+
+At `./configure` time, Node.js checks for a working `dtrace` tool and
+uses `dtrace -h` to generate a probe header.  Pass `--without-dtrace` to
+`./configure` to disable probe support entirely.
+
+* **Linux**: Install the `systemtap-sdt-dev` package (Debian/Ubuntu) or
+  `systemtap-sdt-devel` (Fedora/RHEL) before building Node.js.  The
+  SystemTap `dtrace` wrapper generates a header with semaphore support,
+  giving the probe zero overhead when no tracer is attached.
+* **macOS**: Supported natively via DTrace.  The probe instruction is
+  patched to a no-op by the kernel when no tracer is attached, but the
+  JS-to-C++ call for `emitPublishProbe` is still incurred on every
+  publish to a string-named channel with subscribers.
+* **FreeBSD**: Supported natively via DTrace, with the same
+  characteristics as macOS.
+* **illumos/SmartOS**: Supported natively via DTrace, with the same
+  characteristics as macOS.
+
+If `dtrace` is not found but `<sys/sdt.h>` is available, the probe falls
+back to always-enabled mode.  On platforms where neither is available,
+the probe compiles to a no-op with zero runtime overhead.
+
+#### Example: bpftrace (Linux)
+
+```bash
+sudo bpftrace -e '
+  usdt:./out/Release/node:node:dc__publish {
+    printf("channel: %s\n", str(arg0));
+  }
+' -c './out/Release/node app.js'
+```
+
+#### Example: DTrace (macOS/FreeBSD)
+
+```bash
+sudo dtrace -n '
+  node*:::dc-publish {
+    printf("channel: %s\n", copyinstr(arg0));
+  }
+' -c './out/Release/node app.js'
+```
+
 ### Built-in Channels
 
 #### Console

lib/diagnostics_channel.js

@@ -188,6 +188,17 @@ class ActiveChannel {
   }
 
   publish(data) {
+    // Read the semaphore through the binding on every publish. The view is
+    // created once per context and wraps static native memory, but a cached
+    // reference (for example one captured while building a startup snapshot)
+    // would be a stale copy after the snapshot is deserialized, keeping
+    // probes disabled even while a tracer is attached.
+    const probeSemaphore = dc_binding.probeSemaphore;
+    if (probeSemaphore !== undefined &&
+        probeSemaphore[0] > 0 &&
+        typeof this.name === 'string') {
+      dc_binding.emitPublishProbe(this.name, data);
+    }
     const subscribers = this._subscribers;
     for (let i = 0; i < (subscribers?.length || 0); i++) {
       try {

node.gyp

@@ -46,6 +46,8 @@
     'node_use_dtls%': 'false',
     'node_use_sqlite%': 'true',
     'node_use_ffi%': 'false',
+    'node_use_dtrace%': 'false',
+    'node_no_usdt%': 'false',
     'node_use_v8_platform%': 'true',
     'node_enable_v8_vtunejit%': 'false',
     'node_v8_options%': '',
@@ -276,6 +278,8 @@
       'src/node_metadata.h',
       'src/node_mutex.h',
       'src/node_diagnostics_channel.h',
+      'src/node_usdt.h',
+      'src/node_provider.d',
       'src/node_modules.h',
       'src/node_object_wrap.h',
       'src/node_options.h',
@@ -901,6 +905,43 @@
             'WARNING_CFLAGS': [ '-Werror' ],
           },
         }],
+        [ 'node_no_usdt=="true"', {
+          'defines': [ 'NODE_NO_USDT=1' ],
+        }],
+        [ 'node_use_dtrace=="true"', {
+          'defines': [ 'NODE_HAVE_DTRACE=1' ],
+          'conditions': [
+            [ 'OS=="linux"', {
+              'actions': [
+                {
+                  'action_name': 'node_dtrace_header',
+                  'inputs': [ 'src/node_provider.d' ],
+                  'outputs': [ '<(SHARED_INTERMEDIATE_DIR)/node_provider.h' ],
+                  'action': [
+                    'dtrace', '-h',
+                    '-s', 'src/node_provider.d',
+                    '-o', '<(SHARED_INTERMEDIATE_DIR)/node_provider.h',
+                  ],
+                },
+              ],
+            }, {
+              # macOS, FreeBSD, illumos: native DTrace requires -xnolibs
+              # to avoid loading kernel D libraries during header generation.
+              'actions': [
+                {
+                  'action_name': 'node_dtrace_header',
+                  'inputs': [ 'src/node_provider.d' ],
+                  'outputs': [ '<(SHARED_INTERMEDIATE_DIR)/node_provider.h' ],
+                  'action': [
+                    'dtrace', '-h', '-xnolibs',
+                    '-s', 'src/node_provider.d',
+                    '-o', '<(SHARED_INTERMEDIATE_DIR)/node_provider.h',
+                  ],
+                },
+              ],
+            }],
+          ],
+        }],
         [ 'node_builtin_modules_path!=""', {
           'defines': [ 'NODE_BUILTIN_MODULES_PATH="<(node_builtin_modules_path)"' ],
         }],