Add dtrace/ with example SystemTap trace scripts

Introduces a top-level dtrace/ directory for user-contributed trace
scripts that consume the USDT probes exported by libdns, libns, and
libisc.  Ships with delegdb-trace.stp, which streams every insertion,
eviction, and rndc flush-delegation removal in the delegation cache,
and a README pointing at the provider files and explaining how to list
and run the probes on Linux (SystemTap) and on FreeBSD/macOS (DTrace).

diff --git a/REUSE.toml b/REUSE.toml
index 8c62b217dd4ad5a3de64043a0a3ba7e44a9b740c..d5a87fd483e1bf13321d6a96205d465779cfb3b1 100644 (file)
--- a/REUSE.toml
+++ b/REUSE.toml
@@ -177,7 +177,8 @@ path = [
        "doc/misc/options",
        "doc/misc/rndc.grammar",
        "sonar-project.properties",
-       "tests/bench/names.csv"
+       "tests/bench/names.csv",
+       "dtrace/*"
 ]
 precedence = "aggregate"
 SPDX-FileCopyrightText = "Internet Systems Consortium, Inc. (\"ISC\")"

diff --git a/dtrace/README.md b/dtrace/README.md
new file mode 100644 (file)
index 0000000..5af7151
--- /dev/null
+++ b/dtrace/README.md
@@ -0,0 +1,43 @@
+# dtrace/
+
+Example trace scripts for BIND 9's static user-space (USDT) probes.
+
+## What's instrumented
+
+BIND 9 ships USDT probes declared in three providers:
+
+- `lib/dns/probes-dns.d` — provider `libdns` (`xfrin_*`, `delegdb_*`)
+- `lib/ns/probes-ns.d`   — provider `libns`  (`rrl_*`)
+- `lib/isc/probes-isc.d` — provider `libisc` (`rwlock_*`, `job_*`)
+
+The probes compile to zero-cost nops when no consumer is attached, and
+are only wired up when the build finds `dtrace` and `sys/sdt.h` (meson
+option `-Dtracing=auto|enabled`, default `auto`).  With
+`-Dtracing=disabled` the probe macros are stripped entirely.
+
+## Listing available probes
+
+On Linux (SystemTap / USDT):
+
+    stap -l 'process("/path/to/named").mark("*")' | sort
+
+On FreeBSD or macOS (DTrace):
+
+    dtrace -l -n 'libdns*:::*'
+
+## Scripts
+
+| Script | Purpose |
+|---|---|
+| [`delegdb-trace.stp`](delegdb-trace.stp) | Streams every insertion, eviction, and `rndc flush-delegation` removal in the delegation cache. |
+
+## Running a script
+
+The scripts take the `named` binary path as their first positional
+argument, so they work with either an installed or a freshly-built
+named:
+
+    sudo stap dtrace/delegdb-trace.stp /usr/sbin/named -x $(pidof named)
+    sudo stap dtrace/delegdb-trace.stp build/named -c "build/named -g -f"
+
+The `-c` form runs `named` under stap's supervision and exits with it.

diff --git a/dtrace/delegdb-trace.stp b/dtrace/delegdb-trace.stp
new file mode 100755 (executable)
index 0000000..5827461
--- /dev/null
+++ b/dtrace/delegdb-trace.stp
@@ -0,0 +1,46 @@
+#!/usr/bin/env stap
+#
+# delegdb-trace.stp - trace delegation cache mutations
+#
+# Prints every insertion and every removal (both explicit deletes via
+# rndc flush-delegation and implicit SIEVE-LRU evictions under memory
+# pressure) from the delegdb.
+#
+# Usage:
+#   sudo stap delegdb-trace.stp /path/to/named
+#   sudo stap delegdb-trace.stp /path/to/named -x <pid>
+#
+# Output columns: elapsed milliseconds, operation, isc_result_t code (or
+# "-" for evict), and the zonecut name.  Trees deleted via
+# rndc flush-delegation -tree are labelled DELTREE.
+
+global start_time
+
+probe begin {
+       start_time = gettimeofday_ms()
+       printf("%-10s %-8s %-7s %s\n", "ms", "op", "result", "zonecut")
+}
+
+probe process(@1).mark("delegdb_insert_done") {
+       printf("%-10d %-8s %-7d %s\n",
+              gettimeofday_ms() - start_time,
+              "INSERT",
+              $arg3,
+              user_string($arg2))
+}
+
+probe process(@1).mark("delegdb_delete") {
+       printf("%-10d %-8s %-7d %s\n",
+              gettimeofday_ms() - start_time,
+              $arg3 ? "DELTREE" : "DELETE",
+              $arg4,
+              user_string($arg2))
+}
+
+probe process(@1).mark("delegdb_evict") {
+       printf("%-10d %-8s %-7s %s\n",
+              gettimeofday_ms() - start_time,
+              "EVICT",
+              "-",
+              user_string($arg3))
+}