From 4d0bd0b4ceaadf8ab9b6c4e367eccd92dd3cb0f4 Mon Sep 17 00:00:00 2001
From: lacatoire <la.catoire@gmail.com>
Date: Mon, 15 Jun 2026 11:03:24 +0200
Subject: [PATCH] [Sync EN] Fix bpftrace note about environment variable
 (#5602)

---
 features/dtrace.xml | 200 +++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 199 insertions(+), 1 deletion(-)

diff --git a/features/dtrace.xml b/features/dtrace.xml
index 83d2219bd..890fc0e02 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: 7c966c94fde8a9bb4e52975b559dc0bb0cb2ef72 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,204 @@ 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 Werkzeug bpftrace direkt an die statischen USDT-DTrace-Sonden
+   von PHP 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 PHP-Zielbinä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; der passende Pfad ist
+    entsprechend zu ersetzen oder mittels <literal>-p</literal> über die
+    PID anzuhängen.
+   </simpara>
+   <simpara>
+    Es ist sicherzustellen, dass die Zielbinärdatei mit DTrace erstellt
+    wurde und die Umgebungsvariable richtig konfiguriert ist.
+    Weitere Einzelheiten finden sich unter <link linkend="features.dtrace.install">PHP für statische DTrace-Sonden konfigurieren</link>.
+   </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> für die 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
+    erfordert 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 (zum Beispiel
+    einen <filename>php-fpm</filename>-Worker oder einen Apache-Prozess,
+    der <filename>libphp.so</filename> lädt), wird über die PID
+    angehängt:
+    <informalexample>
+     <programlisting>
+<![CDATA[
+# bpftrace -p $PID all_probes.bt
+]]>
+     </programlisting>
+    </informalexample>
+    Der Zielpfad <literal>usdt:</literal> im Skript muss mit der
+    Binärdatei des laufenden Prozesses übereinstimmen; dazu ist
+    <literal>usdt:/usr/bin/php</literal> entsprechend an 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