From 68b9206ef82643ab7ed177e3e90f08adef337a84 Mon Sep 17 00:00:00 2001
From: lacatoire <la.catoire@gmail.com>
Date: Tue, 9 Jun 2026 10:27:46 +0200
Subject: [PATCH] [Sync EN] Add new bpftrace section for DTrace document
 (#5500)

Refs: php/doc-en@939350f9b52be4b91e04ec1a5d41995e63aa5150
Closes: #320
---
 features/dtrace.xml | 197 +++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 196 insertions(+), 1 deletion(-)

diff --git a/features/dtrace.xml b/features/dtrace.xml
index 83d2219bd..5beb4d065 100644
--- a/features/dtrace.xml
+++ b/features/dtrace.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- EN-Revision: d35d7d811ccf7662eefe4f23ff1cabc727a917ca Maintainer: samesch Status: ready -->
+<!-- EN-Revision: 939350f9b52be4b91e04ec1a5d41995e63aa5150 Maintainer: samesch Status: ready -->
 <!-- Reviewed: no -->
 <chapter xml:id="features.dtrace" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <title>DTrace Dynamic Tracing (Anwendungsanalyse in Echtzeit)</title>
@@ -573,6 +573,201 @@ probe process("sapi/cli/php").provider("php").mark("request__startup") {
    </para>
   </sect2>
  </sect1>
+ <sect1 xml:id="features.dtrace.bpftrace">
+  <title>Verwendung von bpftrace mit statischen PHP-DTrace-Sonden</title>
+  <simpara>
+   Auf Linux-Distributionen mit einem Kernel, der eBPF unterstützt, kann sich
+   das Tool bpftrace direkt an die USDT-Sonden von PHP für DTrace anhängen,
+   ohne dass SystemTap erforderlich ist.
+  </simpara>
+  <sect2 xml:id="features.dtrace.bpftrace-install">
+   <title>Installation von bpftrace</title>
+   <para>
+    bpftrace wird über den Paketmanager der Distribution installiert. Zum
+    Beispiel unter Oracle Linux, RHEL oder Fedora:
+    <informalexample>
+     <programlisting role="shell">
+<![CDATA[
+# dnf install bpftrace
+]]>
+     </programlisting>
+    </informalexample>
+    Oder unter Debian oder Ubuntu:
+    <informalexample>
+     <programlisting role="shell">
+<![CDATA[
+# apt install bpftrace
+]]>
+     </programlisting>
+    </informalexample>
+   </para>
+   <simpara>
+    Die folgenden Beispiele gehen davon aus, dass die Ziel-PHP-Binärdatei unter
+    <filename>/usr/bin/php</filename> installiert ist.
+   </simpara>
+   <simpara>
+    Dieselben USDT-Sonden werden auch von anderen SAPIs bereitgestellt, die aus
+    demselben Quellbaum erstellt wurden, sodass das Sondenziel stattdessen das
+    Apache-Modul (<filename>libphp.so</filename>) oder die Binärdatei des
+    FastCGI-Prozessmanagers (<filename>php-fpm</filename>) sein kann; bei Bedarf
+    ist der entsprechende Pfad einzusetzen oder mit <literal>-p</literal> über
+    die PID anzuhängen.
+   </simpara>
+   <simpara>
+    Es ist sicherzustellen, dass die Ziel-Binärdatei mit DTrace erstellt wurde
+    und dass die Umgebung korrekt konfiguriert ist. Weitere Einzelheiten sind
+    unter <link linkend="features.dtrace.install">PHP für statische DTrace-Sonden
+    konfigurieren</link> zu finden.
+   </simpara>
+   <para>
+    Die statischen Sonden in PHP können mittels <command>bpftrace</command>
+    aufgelistet werden:
+    <informalexample>
+     <programlisting>
+<![CDATA[
+# bpftrace -l 'usdt:/usr/bin/php:php:*'
+]]>
+     </programlisting>
+    </informalexample>
+   </para>
+
+   <para>
+    Dies gibt aus:
+    <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> - Verfolgung aller statischen PHP-Sonden mit 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>
+    Das obige Skript verfolgt während der gesamten Dauer eines laufenden
+    PHP-Skripts alle statischen Sondenpunkte des PHP-Kerns. bpftrace benötigt
+    root-Rechte:
+    <informalexample>
+     <programlisting>
+<![CDATA[
+# USE_ZEND_DTRACE=1 bpftrace -c '/usr/bin/php test.php' all_probes.bt
+]]>
+     </programlisting>
+    </informalexample>
+   </para>
+
+   <para>
+    Um einen bereits laufenden PHP-Prozess zu verfolgen (beispielsweise einen
+    <filename>php-fpm</filename>-Worker oder einen Apache-Prozess, der
+    <filename>libphp.so</filename> lädt), erfolgt das Anhängen über die PID:
+    <informalexample>
+     <programlisting>
+<![CDATA[
+# bpftrace -p $PID all_probes.bt
+]]>
+     </programlisting>
+    </informalexample>
+    Der <literal>usdt:</literal>-Zielpfad im Skript muss mit der Binärdatei des
+    laufenden Prozesses übereinstimmen; <literal>usdt:/usr/bin/php</literal> ist
+    entsprechend auf die <filename>php-fpm</filename>-Binärdatei oder
+    <filename>libphp.so</filename> anzupassen.
+  </para>
+  </sect2>
+ </sect1>
 </chapter>
 
 <!-- Keep this comment at the end of the file