Skip to content

Commit 276fd58

Browse files
lacatoirelacatoire
committed
[Sync EN] Add bpftrace section to DTrace document
Refs: php/doc-en@939350f
1 parent 8a673ae commit 276fd58

1 file changed

Lines changed: 192 additions & 1 deletion

File tree

‎features/dtrace.xml‎

Lines changed: 192 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<?xml version="1.0" encoding="utf-8"?>
2-
<!-- EN-Revision: d35d7d811ccf7662eefe4f23ff1cabc727a917ca Maintainer: leonardolara Status: ready --><!-- CREDITS: leonardolara -->
2+
<!-- EN-Revision: 939350f9b52be4b91e04ec1a5d41995e63aa5150 Maintainer: leonardolara Status: ready --><!-- CREDITS: leonardolara -->
33
<chapter xml:id="features.dtrace" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
44
<title>Instrumentação dinâmica DTrace</title>
55

@@ -552,6 +552,197 @@ probe process("sapi/cli/php").provider("php").mark("request__startup") {
552552
</para>
553553
</sect2>
554554
</sect1>
555+
<sect1 xml:id="features.dtrace.bpftrace">
556+
<title>Usando bpftrace com Sondas Estáticas DTrace do PHP</title>
557+
<simpara>
558+
Em distribuições Linux com um kernel que suporta eBPF, o
559+
utilitário bpftrace pode se conectar diretamente às sondas USDT DTrace do PHP,
560+
sem precisar do SystemTap.
561+
</simpara>
562+
<sect2 xml:id="features.dtrace.bpftrace-install">
563+
<title>Instalando o bpftrace</title>
564+
<para>
565+
Instale o bpftrace usando o gerenciador de pacotes da distribuição. Por
566+
exemplo, no Oracle Linux, RHEL ou Fedora:
567+
<informalexample>
568+
<programlisting role="shell">
569+
<![CDATA[
570+
# dnf install bpftrace
571+
]]>
572+
</programlisting>
573+
</informalexample>
574+
Ou, no Debian ou Ubuntu:
575+
<informalexample>
576+
<programlisting role="shell">
577+
<![CDATA[
578+
# apt install bpftrace
579+
]]>
580+
</programlisting>
581+
</informalexample>
582+
</para>
583+
<simpara>
584+
Os exemplos abaixo assumem que o binário PHP alvo está instalado em
585+
<filename>/usr/bin/php</filename>.
586+
</simpara>
587+
<simpara>
588+
As mesmas sondas USDT também são expostas por outras SAPIs construídas a partir da mesma árvore de fontes, então o
589+
alvo da sonda pode ser, ao invés disso, o módulo do Apache
590+
(<filename>libphp.so</filename>) ou o binário do FastCGI Process Manager
591+
(<filename>php-fpm</filename>); substitua o caminho
592+
apropriado ou conecte-se pelo PID com <literal>-p</literal> conforme necessário.
593+
</simpara>
594+
<simpara>
595+
Certifique-se de que o binário alvo foi construído com o DTrace e que o ambiente está configurado corretamente.
596+
Veja <link linkend="features.dtrace.install">Configurando o PHP para Sondas Estáticas DTrace</link> para detalhes.
597+
</simpara>
598+
<para>
599+
As sondas estáticas do PHP podem ser listadas usando
600+
<command>bpftrace</command>:
601+
<informalexample>
602+
<programlisting>
603+
<![CDATA[
604+
# bpftrace -l 'usdt:/usr/bin/php:php:*'
605+
]]>
606+
</programlisting>
607+
</informalexample>
608+
</para>
609+
610+
<para>
611+
A saída é:
612+
<informalexample>
613+
<programlisting>
614+
<![CDATA[
615+
usdt:/usr/bin/php:php:compile__file__entry
616+
usdt:/usr/bin/php:php:compile__file__return
617+
usdt:/usr/bin/php:php:error
618+
usdt:/usr/bin/php:php:exception__caught
619+
usdt:/usr/bin/php:php:exception__thrown
620+
usdt:/usr/bin/php:php:execute__entry
621+
usdt:/usr/bin/php:php:execute__return
622+
usdt:/usr/bin/php:php:function__entry
623+
usdt:/usr/bin/php:php:function__return
624+
usdt:/usr/bin/php:php:request__shutdown
625+
usdt:/usr/bin/php:php:request__startup
626+
]]>
627+
</programlisting>
628+
</informalexample>
629+
</para>
630+
631+
<para>
632+
<example>
633+
<title><filename>all_probes.bt</filename> para instrumentação de todas as Sondas Estáticas do PHP com bpftrace</title>
634+
<programlisting role="shell">
635+
<![CDATA[
636+
#!/usr/bin/env bpftrace
637+
638+
usdt:/usr/bin/php:php:compile__file__entry
639+
{
640+
printf("Probe compile__file__entry\n");
641+
printf(" compile_file %s\n", str(arg0));
642+
printf(" compile_file_translated %s\n", str(arg1));
643+
}
644+
usdt:/usr/bin/php:php:compile__file__return
645+
{
646+
printf("Probe compile__file__return\n");
647+
printf(" compile_file %s\n", str(arg0));
648+
printf(" compile_file_translated %s\n", str(arg1));
649+
}
650+
usdt:/usr/bin/php:php:error
651+
{
652+
printf("Probe error\n");
653+
printf(" errormsg %s\n", str(arg0));
654+
printf(" request_file %s\n", str(arg1));
655+
printf(" lineno %d\n", (int32)arg2);
656+
}
657+
usdt:/usr/bin/php:php:exception__caught
658+
{
659+
printf("Probe exception__caught\n");
660+
printf(" classname %s\n", str(arg0));
661+
}
662+
usdt:/usr/bin/php:php:exception__thrown
663+
{
664+
printf("Probe exception__thrown\n");
665+
printf(" classname %s\n", str(arg0));
666+
}
667+
usdt:/usr/bin/php:php:execute__entry
668+
{
669+
printf("Probe execute__entry\n");
670+
printf(" request_file %s\n", str(arg0));
671+
printf(" lineno %d\n", (int32)arg1);
672+
}
673+
usdt:/usr/bin/php:php:execute__return
674+
{
675+
printf("Probe execute__return\n");
676+
printf(" request_file %s\n", str(arg0));
677+
printf(" lineno %d\n", (int32)arg1);
678+
}
679+
usdt:/usr/bin/php:php:function__entry
680+
{
681+
printf("Probe function__entry\n");
682+
printf(" function_name %s\n", str(arg0));
683+
printf(" request_file %s\n", str(arg1));
684+
printf(" lineno %d\n", (int32)arg2);
685+
printf(" classname %s\n", str(arg3));
686+
printf(" scope %s\n", str(arg4));
687+
}
688+
usdt:/usr/bin/php:php:function__return
689+
{
690+
printf("Probe function__return\n");
691+
printf(" function_name %s\n", str(arg0));
692+
printf(" request_file %s\n", str(arg1));
693+
printf(" lineno %d\n", (int32)arg2);
694+
printf(" classname %s\n", str(arg3));
695+
printf(" scope %s\n", str(arg4));
696+
}
697+
usdt:/usr/bin/php:php:request__shutdown
698+
{
699+
printf("Probe request__shutdown\n");
700+
printf(" file %s\n", str(arg0));
701+
printf(" request_uri %s\n", str(arg1));
702+
printf(" request_method %s\n", str(arg2));
703+
}
704+
usdt:/usr/bin/php:php:request__startup
705+
{
706+
printf("Probe request__startup\n");
707+
printf(" file %s\n", str(arg0));
708+
printf(" request_uri %s\n", str(arg1));
709+
printf(" request_method %s\n", str(arg2));
710+
}
711+
]]>
712+
</programlisting>
713+
</example>
714+
</para>
715+
716+
<para>
717+
O script acima irá instrumentar todos os pontos de sondas estáticas do núcleo do PHP
718+
durante toda a duração de um script PHP em execução. O bpftrace requer
719+
privilégios de root:
720+
<informalexample>
721+
<programlisting>
722+
<![CDATA[
723+
# USE_ZEND_DTRACE=1 bpftrace -c '/usr/bin/php test.php' all_probes.bt
724+
]]>
725+
</programlisting>
726+
</informalexample>
727+
</para>
728+
729+
<para>
730+
Para instrumentar um processo PHP já em execução (por exemplo, um
731+
worker do <filename>php-fpm</filename> ou um processo Apache carregando
732+
<filename>libphp.so</filename>), conecte-se pelo PID:
733+
<informalexample>
734+
<programlisting>
735+
<![CDATA[
736+
# bpftrace -p $PID all_probes.bt
737+
]]>
738+
</programlisting>
739+
</informalexample>
740+
O caminho alvo <literal>usdt:</literal> no script deve corresponder ao binário do
741+
processo em execução; ajuste <literal>usdt:/usr/bin/php</literal> para o
742+
binário do <filename>php-fpm</filename> ou para <filename>libphp.so</filename> conforme apropriado.
743+
</para>
744+
</sect2>
745+
</sect1>
555746
</chapter>
556747

557748
<!-- Keep this comment at the end of the file

0 commit comments

Comments
 (0)