build: pre-generate USDT probe header and add bpftrace CI

Implements the approach from the #62118 review discussion to remove
the build-time 'dtrace' dependency on Linux:

* Commit the SystemTap-generated probe header
  (src/node_provider_linux.h, regenerate with
  tools/usdt/generate_headers.py).  USDT support is now on by
  default on Linux whenever <sys/sdt.h> is available
  (systemtap-sdt-dev on Debian/Ubuntu, systemtap-sdt-devel on
  Fedora/RHEL) and never needs a 'dtrace' tool at build time.  A
  committed-header drift check runs in CI.
* Make native DTrace opt-in on macOS via the new
  ./configure --with-dtrace; FreeBSD/illumos remain unsupported
  pending a 'dtrace -G' link step.  --without-dtrace still disables
  probes everywhere.  The always-on <sys/sdt.h> fallback tier is
  gone.
* Add a path-gated test-usdt job to the Linux CI workflow with a
  default leg that runs the end-to-end bpftrace probe test as
  root, and a --without-dtrace leg that pins the no-op tier.

The generated header is excluded from cpplint like
src/node_root_certs.h.

Signed-off-by: Bryan English <bryan@bryanenglish.com>

Author: bengl

.github/workflows/test-linux.yml

@@ -87,3 +87,66 @@ jobs:
           ./tools/test.py --flaky-tests keep_retrying -p actions -j 4
         env:
           DIR: dir%20with $unusual"chars?'åß∂ƒ©∆¬…`
+
+  # End-to-end coverage for the diagnostics_channel USDT probes:
+  # a real bpftrace attach against a default (USDT-enabled) build, plus
+  # a --without-dtrace build that pins the no-op tier.  Only runs when
+  # USDT-related paths change, so ordinary PRs do not pay for it.
+  test-usdt:
+    name: USDT probes (${{ matrix.cfg }})
+    runs-on: ubuntu-24.04
+    strategy:
+      fail-fast: false
+      matrix:
+        cfg: ['default', 'without-dtrace']
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+        with:
+          persist-credentials: false
+          path: node
+      - name: Detect USDT-related changes
+        id: changes
+        run: |
+          cd node
+          if [ "${{ github.event_name }}" != "pull_request" ]; then
+            echo "usdt=true" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          git fetch --no-tags origin "+${{ github.base_ref }}:refs/remotes/origin/${{ github.base_ref }}"
+          FILES=$(git diff --name-only "refs/remotes/origin/${{ github.base_ref }}...HEAD")
+          echo "$FILES"
+          if echo "$FILES" | grep -qE '^(src/node_(usdt|provider|diagnostics_channel)\.(h|cc|d)|src/node_provider_linux\.h|lib/diagnostics_channel\.js|tools/usdt/|test/parallel/test-diagnostics-channel-usdt.*\.js|\.github/workflows/test-linux\.yml|configure\.py|node\.gyp|doc/api/diagnostics_channel\.md)'; then
+            echo "usdt=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "usdt=false" >> "$GITHUB_OUTPUT"
+          fi
+      - name: Install bpftrace and systemtap-sdt-dev
+        if: steps.changes.outputs.usdt == 'true'
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends bpftrace systemtap-sdt-dev
+      - name: Check committed probe header is in sync
+        if: steps.changes.outputs.usdt == 'true'
+        run: |
+          cd node
+          python3 tools/usdt/generate_headers.py --check
+      - name: Configure
+        if: steps.changes.outputs.usdt == 'true'
+        run: |
+          cd node
+          ./configure ${{ matrix.cfg == 'without-dtrace' && '--without-dtrace' || '' }}
+      - name: Build
+        if: steps.changes.outputs.usdt == 'true'
+        run: make -C node -j4
+      - name: USDT binding tests
+        if: steps.changes.outputs.usdt == 'true'
+        run: |
+          cd node
+          python3 tools/test.py test/parallel/test-diagnostics-channel-usdt.js
+      - name: bpftrace end-to-end test
+        if: steps.changes.outputs.usdt == 'true' && matrix.cfg == 'default'
+        # Run as root: the test skips itself when not root, and bpftrace
+        # needs root to attach (BTF is available on GH-hosted images).
+        run: |
+          cd node
+          sudo -E python3 tools/test.py test/parallel/test-diagnostics-channel-usdt-bpftrace.js

Makefile

@@ -1471,6 +1471,9 @@ LINT_CPP_ADDON_DOC_FILES_GLOB = test/addons/??_*/*.cc test/addons/??_*/*.h
 LINT_CPP_ADDON_DOC_FILES = $(wildcard $(LINT_CPP_ADDON_DOC_FILES_GLOB))
 LINT_CPP_EXCLUDE ?=
 LINT_CPP_EXCLUDE += src/node_root_certs.h
+# Generated output of the SystemTap dtrace wrapper, committed verbatim
+# (regenerate with tools/usdt/generate_headers.py).
+LINT_CPP_EXCLUDE += src/node_provider_linux.h
 LINT_CPP_EXCLUDE += $(LINT_CPP_ADDON_DOC_FILES)
 # These files were copied more or less verbatim from V8.
 LINT_CPP_EXCLUDE += src/tracing/trace_event.h src/tracing/trace_event_common.h

configure.py

@@ -948,6 +948,13 @@
     default=None,
     help='do not install the bundled Amaro (TypeScript utils)')
 
+parser.add_argument('--with-dtrace',
+    action='store_true',
+    dest='with_dtrace',
+    default=None,
+    help='build with native DTrace/USDT probe support '
+         '(opt-in on macOS; Linux probes need no dtrace tool)')
+
 parser.add_argument('--without-dtrace',
     action='store_true',
     dest='without_dtrace',
@@ -1249,9 +1256,10 @@ def to_utf8(s):
 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."""
+  Supported on macOS (native DTrace).  Non-Linux platforms require
+  -xnolibs to avoid loading standard D libraries during header generation.
+  Linux never needs this check: the probe header is pre-generated and
+  committed (see tools/usdt/generate_headers.py)."""
   dtrace = shutil.which('dtrace')
   if dtrace is None:
     return False
@@ -2008,14 +2016,39 @@ def configure_node(o):
     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()
+  # USDT probe support for diagnostics_channel:
+  #
+  # * Linux: on by default whenever <sys/sdt.h> is available.  The probe
+  #   header is pre-generated and committed (src/node_provider_linux.h),
+  #   so no dtrace tool is needed at build time.
+  # * macOS: opt-in via --with-dtrace; needs a working `dtrace -h` at
+  #   build time (always present with Xcode/CLT).
+  # * FreeBSD/illumos: not supported yet; native DTrace there requires
+  #   a `dtrace -G` link step that is not implemented.
+  if options.without_dtrace:
+    use_dtrace = False
+  elif options.with_dtrace:
+    if flavor == 'mac':
+      if not has_working_dtrace_h():
+        raise Exception('dtrace -h is not working; cannot use --with-dtrace')
+      use_dtrace = True
+    else:
+      use_dtrace = False
+      warn('--with-dtrace is only supported on macOS. On Linux, USDT '
+           'probes are enabled automatically whenever <sys/sdt.h> is '
+           'available.')
+  else:
+    use_dtrace = False
   o['variables']['node_use_dtrace'] = b(use_dtrace)
   if options.without_dtrace:
     print('USDT probes: disabled (--without-dtrace)')
+  elif flavor == 'linux':
+    print('USDT probes: enabled when <sys/sdt.h> is available '
+          '(systemtap-sdt-dev on Debian/Ubuntu)')
   elif use_dtrace:
-    print('USDT probes: enabled (dtrace -h, semaphore support)')
+    print('USDT probes: enabled (--with-dtrace, dtrace -h)')
   else:
-    print('USDT probes: fallback (sys/sdt.h) or disabled')
+    print('USDT probes: disabled (enable with --with-dtrace)')
 
 def configure_napi(output):
   version = getnapibuildversion.get_napi_version()

doc/api/diagnostics_channel.md

@@ -1143,26 +1143,32 @@ probe fires only if the channel has active subscribers.
 
 #### 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.
+USDT support is platform-gated and, on Linux, does not require a
+`dtrace` tool at build time.  Pass `--without-dtrace` to `./configure`
+to disable probe support entirely.
+
+* **Linux** (on by default): the probe header is pre-generated and
+  committed (`src/node_provider_linux.h`, regenerated with
+  `tools/usdt/generate_headers.py`), so only `<sys/sdt.h>` is required
+  at build time — install the `systemtap-sdt-dev` package
+  (Debian/Ubuntu) or `systemtap-sdt-devel` (Fedora/RHEL).  The SystemTap
+  semaphore gives the probe effectively zero overhead when no tracer is
+  attached.  When `<sys/sdt.h>` is absent, the probe silently compiles
+  to a no-op.  A dedicated CI job runs an end-to-end bpftrace test on
+  Linux and verifies the committed header is in sync with
+  `src/node_provider.d`.
+* **macOS** (opt-in): pass `--with-dtrace` to `./configure` to enable.
+  Requires a working `dtrace -h` at build time (always present with
+  Xcode/CLT).  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, which is why this tier is
+  opt-in.
+* **FreeBSD/illumos**: not supported yet.  Native DTrace there requires
+  a `dtrace -G` link step that is not implemented.
+
+On platforms where probes are not available, they compile to no-ops
+with zero runtime overhead.
 
 #### Example: bpftrace (Linux)
 
@@ -1174,7 +1180,7 @@ sudo bpftrace -e '
 ' -c './out/Release/node app.js'
 ```
 
-#### Example: DTrace (macOS/FreeBSD)
+#### Example: DTrace (macOS)
 
 ```bash
 sudo dtrace -n '

node.gyp

@@ -276,6 +276,7 @@
       'src/node_diagnostics_channel.h',
       'src/node_usdt.h',
       'src/node_provider.d',
+      'src/node_provider_linux.h',
       'src/node_modules.h',
       'src/node_object_wrap.h',
       'src/node_options.h',
@@ -956,37 +957,8 @@
         }],
         [ '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',
-                  ],
-                },
-              ],
-            }],
-          ],
+          'dependencies': [ 'node_dtrace_header' ],
+          'include_dirs': [ '<(SHARED_INTERMEDIATE_DIR)' ],
         }],
         [ 'node_builtin_modules_path!=""', {
           'defines': [ 'NODE_BUILTIN_MODULES_PATH="<(node_builtin_modules_path)"' ]
@@ -1566,6 +1538,33 @@
         }],
       ]
     }, # overlapped-checker
+    {
+      'target_name': 'node_dtrace_header',
+      'type': 'none',
+      'conditions': [
+        [ 'node_use_dtrace=="true"', {
+          'actions': [
+            {
+              # Native DTrace (macOS, opt-in via ./configure
+              # --with-dtrace): generate the probe header at build time.
+              # On Linux the probe header is pre-generated and committed
+              # at src/node_provider_linux.h, so no dtrace tool is
+              # needed there (see tools/usdt/generate_headers.py).
+              # -xnolibs avoids loading standard D libraries during
+              # header generation.
+              'action_name': 'node_dtrace_header',
+              'inputs': [ 'src/node_provider.d' ],
+              'outputs': [ '<(SHARED_INTERMEDIATE_DIR)/node_provider.h' ],
+              'action': [
+                'dtrace', '-h', '-xnolibs',
+                '-s', '<@(_inputs)',
+                '-o', '<@(_outputs)',
+              ],
+            },
+          ],
+        } ],
+      ],
+    }, # node_dtrace_header
     {
       'target_name': 'nop',
       'type': 'executable',

src/node_diagnostics_channel.cc

@@ -9,16 +9,15 @@
 
 #include <cstdint>
 
-#if defined(NODE_HAVE_DTRACE) && defined(STAP_HAS_SEMAPHORES)
-// Definition of the USDT probe semaphore declared in the dtrace-generated
-// node_provider.h.  STAP_HAS_SEMAPHORES is only defined by the SystemTap
-// dtrace wrapper (Linux), where the .probes ELF section attribute is valid.
-// On macOS/FreeBSD/illumos (native DTrace) there is no semaphore variable;
-// the kernel handles probe enabling directly.  The generated header declares
-// The generated header declares this symbol with C++ linkage (no extern "C"
-// wrapper), so this definition must also use C++ linkage to ensure the
-// linker resolves the same mangled symbol.
-unsigned short node_dc__publish_semaphore
+#if NODE_HAVE_USDT && defined(NODE_USDT_HAVE_SEMAPHORE)
+// Definition of the USDT probe semaphore declared in the committed,
+// SystemTap-generated src/node_provider_linux.h (Linux Tier 1).  The
+// .probes ELF section attribute is only valid there.  On native DTrace
+// platforms there is no semaphore variable; the kernel handles probe
+// enabling directly.  The generated header declares this symbol with
+// C++ linkage (no extern "C" wrapper), so this definition must also use
+// C++ linkage to ensure the linker resolves the same mangled symbol.
+unsigned short node_dc__publish_semaphore  // NOLINT(runtime/int)
     __attribute__((section(".probes")));
 #endif
 
@@ -153,7 +152,7 @@ void BindingData::SetupProbeSemaphore(Isolate* isolate,
   // a tracer is attached without crossing the JS/C++ boundary.
   auto backing = ArrayBuffer::NewBackingStore(
       NodeDCPublishSemaphore(),
-      sizeof(unsigned short),
+      sizeof(unsigned short),  // NOLINT(runtime/int)
       [](void*, size_t, void*) {},  // no-op deleter — memory is static
       nullptr);
   Local<ArrayBuffer> ab = ArrayBuffer::New(isolate, std::move(backing));

src/node_provider_linux.h

@@ -0,0 +1,32 @@
+/*
+ * This file is generated by tools/usdt/generate_headers.py from
+ * src/node_provider.d using the SystemTap `dtrace` wrapper. Do not
+ * edit it by hand.
+ *
+ * Regenerate with: python3 tools/usdt/generate_headers.py
+ * The test-usdt CI job verifies that this file is in sync with
+ * src/node_provider.d.
+ */
+
+/* Generated by the Systemtap dtrace wrapper */
+
+
+#define _SDT_HAS_SEMAPHORES 1
+
+
+#define STAP_HAS_SEMAPHORES 1 /* deprecated */
+
+
+#include <sys/sdt.h>
+
+/* NODE_DC_PUBLISH ( const char *, const void * ) */
+#if defined STAP_SDT_V1
+#define NODE_DC_PUBLISH_ENABLED() __builtin_expect (dc__publish_semaphore, 0)
+#define node_dc__publish_semaphore dc__publish_semaphore
+#else
+#define NODE_DC_PUBLISH_ENABLED() __builtin_expect (node_dc__publish_semaphore, 0)
+#endif
+__extension__ extern unsigned short node_dc__publish_semaphore __attribute__ ((unused)) __attribute__ ((section (".probes")));
+#define NODE_DC_PUBLISH(arg1, arg2) \
+DTRACE_PROBE2 (node, dc__publish, arg1, arg2)
+