From 654febbd8510d3bc712033495a45f51b5dab4b95 Mon Sep 17 00:00:00 2001
From: egmc <waltz4debby@eg2mix.com>
Date: Mon, 20 Apr 2026 09:15:28 +0900
Subject: [PATCH 1/5] Add new bpftrace for DTrace document

 - add bpftrace example section like SystemTap as an easier sample
---
 features/dtrace.xml | 188 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 188 insertions(+)

diff --git a/features/dtrace.xml b/features/dtrace.xml
index 2b92e15b6ab2..82d01de61658 100644
--- a/features/dtrace.xml
+++ b/features/dtrace.xml
@@ -546,6 +546,194 @@ probe process("sapi/cli/php").provider("php").mark("request__startup") {
      <programlisting>
 <![CDATA[
 # stap -c 'sapi/cli/php test.php' all_probes.stp
+]]>
+     </programlisting>
+    </informalexample>
+   </para>
+  </sect2>
+ </sect1>
+ <sect1 xml:id="features.dtrace.bpftrace">
+  <title>Using bpftrace with PHP DTrace Static Probes</title>
+    <para>
+     On Linux distributions with a kernel that supports eBPF, the
+     bpftrace utility can attach to PHP's DTrace USDT probes directly,
+     without requiring SystemTap.
+    </para>
+  <sect2 xml:id="features.dtrace.bpftrace-install">
+   <title>Installing bpftrace</title>
+   <para>
+    Install bpftrace using the distribution's package manager. For
+    example, on Oracle Linux, RHEL, or Fedora:
+    <informalexample>
+     <programlisting role="shell">
+<![CDATA[
+# dnf install bpftrace
+]]>
+     </programlisting>
+    </informalexample>
+    Or, on Debian or Ubuntu:
+    <informalexample>
+     <programlisting role="shell">
+<![CDATA[
+# apt install bpftrace
+]]>
+     </programlisting>
+    </informalexample>
+   </para>
+   <para>
+    The examples below assume the target PHP binary is installed at
+    <filename>/usr/bin/php</filename>.
+   </para>
+   <para>The same USDT probes are also
+    exposed by other SAPIs built from the same source tree, so the
+    probe target may instead be the Apache module
+    (<filename>libphp.so</filename>) or the FastCGI Process Manager
+    binary (<filename>php-fpm</filename>); substitute the appropriate
+    path or attach by PID with <literal>-p</literal> as needed.
+   </para>
+   <para>
+    Make sure target binary is built with DTrace and configured environment properly.
+    <link linkend="features.dtrace.install">Configuring PHP for DTrace Static Probes</link> for details.
+    </para>
+   <para>
+    The static probes in PHP can be listed using
+    <filename>bpftrace</filename>:
+    <informalexample>
+     <programlisting>
+<![CDATA[
+# bpftrace -l 'usdt:/usr/bin/php:php:*'
+]]>
+     </programlisting>
+    </informalexample>
+   </para>
+
+   <para>
+    This outputs:
+    <informalexample>
+     <programlisting>
+<![CDATA[
+usdt:/usr/bin/php:php:compile__file__entry
+usdt:/usr/bin/php:php:compile__file__return
+usdt:/usr/bin/php:php:error
+usdt:/usr/bin/php:php:exception__caught
+usdt:/usr/bin/php:php:exception__thrown
+usdt:/usr/bin/php:php:execute__entry
+usdt:/usr/bin/php:php:execute__return
+usdt:/usr/bin/php:php:function__entry
+usdt:/usr/bin/php:php:function__return
+usdt:/usr/bin/php:php:request__shutdown
+usdt:/usr/bin/php:php:request__startup
+]]>
+     </programlisting>
+    </informalexample>
+   </para>
+
+   <para>
+    <example>
+     <title><filename>all_probes.bt</filename> for tracing all PHP Static Probes with bpftrace</title>
+     <programlisting role="shell">
+<![CDATA[
+#!/usr/bin/env bpftrace
+
+usdt:/usr/bin/php:php:compile__file__entry
+{
+    printf("Probe compile__file__entry\n");
+    printf("  compile_file %s\n", str(arg0));
+    printf("  compile_file_translated %s\n", str(arg1));
+}
+usdt:/usr/bin/php:php:compile__file__return
+{
+    printf("Probe compile__file__return\n");
+    printf("  compile_file %s\n", str(arg0));
+    printf("  compile_file_translated %s\n", str(arg1));
+}
+usdt:/usr/bin/php:php:error
+{
+    printf("Probe error\n");
+    printf("  errormsg %s\n", str(arg0));
+    printf("  request_file %s\n", str(arg1));
+    printf("  lineno %d\n", (int32)arg2);
+}
+usdt:/usr/bin/php:php:exception__caught
+{
+    printf("Probe exception__caught\n");
+    printf("  classname %s\n", str(arg0));
+}
+usdt:/usr/bin/php:php:exception__thrown
+{
+    printf("Probe exception__thrown\n");
+    printf("  classname %s\n", str(arg0));
+}
+usdt:/usr/bin/php:php:execute__entry
+{
+    printf("Probe execute__entry\n");
+    printf("  request_file %s\n", str(arg0));
+    printf("  lineno %d\n", (int32)arg1);
+}
+usdt:/usr/bin/php:php:execute__return
+{
+    printf("Probe execute__return\n");
+    printf("  request_file %s\n", str(arg0));
+    printf("  lineno %d\n", (int32)arg1);
+}
+usdt:/usr/bin/php:php:function__entry
+{
+    printf("Probe function__entry\n");
+    printf("  function_name %s\n", str(arg0));
+    printf("  request_file %s\n", str(arg1));
+    printf("  lineno %d\n", (int32)arg2);
+    printf("  classname %s\n", str(arg3));
+    printf("  scope %s\n", str(arg4));
+}
+usdt:/usr/bin/php:php:function__return
+{
+    printf("Probe function__return\n");
+    printf("  function_name %s\n", str(arg0));
+    printf("  request_file %s\n", str(arg1));
+    printf("  lineno %d\n", (int32)arg2);
+    printf("  classname %s\n", str(arg3));
+    printf("  scope %s\n", str(arg4));
+}
+usdt:/usr/bin/php:php:request__shutdown
+{
+    printf("Probe request__shutdown\n");
+    printf("  file %s\n", str(arg0));
+    printf("  request_uri %s\n", str(arg1));
+    printf("  request_method %s\n", str(arg2));
+}
+usdt:/usr/bin/php:php:request__startup
+{
+    printf("Probe request__startup\n");
+    printf("  file %s\n", str(arg0));
+    printf("  request_uri %s\n", str(arg1));
+    printf("  request_method %s\n", str(arg2));
+}
+]]>
+     </programlisting>
+    </example>
+   </para>
+
+   <para>
+    The above script will trace all core PHP static probe points
+    throughout the duration of a running PHP script. bpftrace requires
+    root privileges:
+    <informalexample>
+     <programlisting>
+<![CDATA[
+# USE_ZEND_DTRACE=1 bpftrace -c '/usr/bin/php test.php' all_probes.bt
+]]>
+     </programlisting>
+    </informalexample>
+   </para>
+
+   <para>
+    To trace an already-running PHP process (for instance, a
+    <filename>php-fpm</filename> worker or an Apache process loading
+    <filename>libphp.so</filename>), attach by PID:
+    <informalexample>
+     <programlisting>
+<![CDATA[
+# bpftrace -p $PID all_probes.bt
 ]]>
      </programlisting>
     </informalexample>

From 24b906868b7691f1cec5c668263470c3c5ce4838 Mon Sep 17 00:00:00 2001
From: sohei iwahori <waltz4debby@eg2mix.com>
Date: Tue, 21 Apr 2026 21:26:18 +0900
Subject: [PATCH 2/5] Apply suggestions from code review

Co-authored-by: Louis-Arnaud <la.catoire@gmail.com>
---
 features/dtrace.xml | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/features/dtrace.xml b/features/dtrace.xml
index 82d01de61658..181c87e04f1c 100644
--- a/features/dtrace.xml
+++ b/features/dtrace.xml
@@ -554,11 +554,11 @@ probe process("sapi/cli/php").provider("php").mark("request__startup") {
  </sect1>
  <sect1 xml:id="features.dtrace.bpftrace">
   <title>Using bpftrace with PHP DTrace Static Probes</title>
-    <para>
+    <simpara>
      On Linux distributions with a kernel that supports eBPF, the
      bpftrace utility can attach to PHP's DTrace USDT probes directly,
      without requiring SystemTap.
-    </para>
+    </simpara>
   <sect2 xml:id="features.dtrace.bpftrace-install">
    <title>Installing bpftrace</title>
    <para>
@@ -591,10 +591,10 @@ probe process("sapi/cli/php").provider("php").mark("request__startup") {
     binary (<filename>php-fpm</filename>); substitute the appropriate
     path or attach by PID with <literal>-p</literal> as needed.
    </para>
-   <para>
-    Make sure target binary is built with DTrace and configured environment properly.
+   <simpara>
+    Make sure the target binary is built with DTrace and that the environment is configured properly. See 
     <link linkend="features.dtrace.install">Configuring PHP for DTrace Static Probes</link> for details.
-    </para>
+   </simpara>
    <para>
     The static probes in PHP can be listed using
     <filename>bpftrace</filename>:

From d3feef233827437ebc48acbc94348abce2382095 Mon Sep 17 00:00:00 2001
From: egmc <waltz4debby@eg2mix.com>
Date: Tue, 21 Apr 2026 21:37:50 +0900
Subject: [PATCH 3/5] fix indent level with 1 space to match other sections

---
 features/dtrace.xml | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/features/dtrace.xml b/features/dtrace.xml
index 181c87e04f1c..58d87f313edd 100644
--- a/features/dtrace.xml
+++ b/features/dtrace.xml
@@ -554,11 +554,11 @@ probe process("sapi/cli/php").provider("php").mark("request__startup") {
  </sect1>
  <sect1 xml:id="features.dtrace.bpftrace">
   <title>Using bpftrace with PHP DTrace Static Probes</title>
-    <simpara>
-     On Linux distributions with a kernel that supports eBPF, the
-     bpftrace utility can attach to PHP's DTrace USDT probes directly,
-     without requiring SystemTap.
-    </simpara>
+  <simpara>
+   On Linux distributions with a kernel that supports eBPF, the
+   bpftrace utility can attach to PHP's DTrace USDT probes directly,
+   without requiring SystemTap.
+  </simpara>
   <sect2 xml:id="features.dtrace.bpftrace-install">
    <title>Installing bpftrace</title>
    <para>

From 199a53150cc0837f4198177421ae7317d4898e22 Mon Sep 17 00:00:00 2001
From: egmc <waltz4debby@eg2mix.com>
Date: Tue, 21 Apr 2026 21:52:56 +0900
Subject: [PATCH 4/5] fix indent inside <para>

---
 features/dtrace.xml | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/features/dtrace.xml b/features/dtrace.xml
index 58d87f313edd..28f600321199 100644
--- a/features/dtrace.xml
+++ b/features/dtrace.xml
@@ -584,16 +584,16 @@ probe process("sapi/cli/php").provider("php").mark("request__startup") {
     The examples below assume the target PHP binary is installed at
     <filename>/usr/bin/php</filename>.
    </para>
-   <para>The same USDT probes are also
-    exposed by other SAPIs built from the same source tree, so the
+   <para>
+    The same USDT probes are also exposed by other SAPIs built from the same source tree, so the
     probe target may instead be the Apache module
     (<filename>libphp.so</filename>) or the FastCGI Process Manager
     binary (<filename>php-fpm</filename>); substitute the appropriate
     path or attach by PID with <literal>-p</literal> as needed.
    </para>
    <simpara>
-    Make sure the target binary is built with DTrace and that the environment is configured properly. See 
-    <link linkend="features.dtrace.install">Configuring PHP for DTrace Static Probes</link> for details.
+    Make sure the target binary is built with DTrace and that the environment is configured properly.
+    See <link linkend="features.dtrace.install">Configuring PHP for DTrace Static Probes</link> for details.
    </simpara>
    <para>
     The static probes in PHP can be listed using

From c10d08077917afd251c709b18868fe64ea4b8c02 Mon Sep 17 00:00:00 2001
From: sohei iwahori <waltz4debby@eg2mix.com>
Date: Sun, 26 Apr 2026 22:23:05 +0900
Subject: [PATCH 5/5] Apply suggestions from code review

Changes that should be changed to simpara

Co-authored-by: Jordi Kroon <jordi@jordikroon.nl>
---
 features/dtrace.xml | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/features/dtrace.xml b/features/dtrace.xml
index 28f600321199..c221ac62248f 100644
--- a/features/dtrace.xml
+++ b/features/dtrace.xml
@@ -580,17 +580,17 @@ probe process("sapi/cli/php").provider("php").mark("request__startup") {
      </programlisting>
     </informalexample>
    </para>
-   <para>
+   <simpara>
     The examples below assume the target PHP binary is installed at
     <filename>/usr/bin/php</filename>.
-   </para>
-   <para>
+   </simpara>
+   <simpara>
     The same USDT probes are also exposed by other SAPIs built from the same source tree, so the
     probe target may instead be the Apache module
     (<filename>libphp.so</filename>) or the FastCGI Process Manager
     binary (<filename>php-fpm</filename>); substitute the appropriate
     path or attach by PID with <literal>-p</literal> as needed.
-   </para>
+   </simpara>
    <simpara>
     Make sure the target binary is built with DTrace and that the environment is configured properly.
     See <link linkend="features.dtrace.install">Configuring PHP for DTrace Static Probes</link> for details.