instrumentation.md
1> **Источник:** https://python-all.ru/3.12/howto/instrumentation.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# Инструментирование CPython с помощью DTrace и SystemTap89**автор:**1011David Malcolm1213**автор:**1415Łukasz Langa1617DTrace и SystemTap – это инструменты мониторинга, каждый из которых предоставляет способ проверки того, что делают процессы в компьютерной системе. Оба используют предметно-ориентированные языки, позволяющие пользователю писать сценарии, которые:1819- фильтровать, какие процессы наблюдать20- собирать данные из интересующих процессов21- создавать отчёты по данным2223Начиная с Python 3.6, CPython можно собрать со встроенными «маркерами», также известными как «зонды», которые могут наблюдаться скриптом DTrace или SystemTap, что упрощает мониторинг того, что делают процессы CPython в системе.2425**Особенность реализации CPython:** Маркеры DTrace являются деталями реализации интерпретатора CPython. Никаких гарантий совместимости зондов между версиями CPython не даётся. Скрипты DTrace могут перестать работать или работать некорректно без предупреждения при смене версий CPython.2627## Включение статических маркеров2829macOS имеет встроенную поддержку DTrace. В Linux для сборки CPython со встроенными маркерами для SystemTap необходимо установить средства разработки SystemTap.3031На машине с Linux это можно сделать с помощью:3233```console34$ yum install systemtap-sdt-devel35```3637или:3839```console40$ sudo apt-get install systemtap-sdt-dev41```4243Затем CPython должен быть [`configured with the --with-dtrace option`](https://python-all.ru/3.12/using/configure.html#cmdoption-with-dtrace):4445```text46checking for --with-dtrace... yes47```4849В macOS можно вывести список доступных зондов DTrace, запустив процесс Python в фоне и перечислив все зонды, предоставляемые провайдером Python:5051```console52$ python3.6 -q &53$ sudo dtrace -l -P python$! # или: dtrace -l -m python3.65455 ID PROVIDER MODULE FUNCTION NAME5629564 python18035 python3.6 _PyEval_EvalFrameDefault function-entry5729565 python18035 python3.6 dtrace_function_entry function-entry5829566 python18035 python3.6 _PyEval_EvalFrameDefault function-return5929567 python18035 python3.6 dtrace_function_return function-return6029568 python18035 python3.6 collect gc-done6129569 python18035 python3.6 collect gc-start6229570 python18035 python3.6 _PyEval_EvalFrameDefault line6329571 python18035 python3.6 maybe_dtrace_line line64```6566В Linux можно проверить, присутствуют ли статические маркеры SystemTap в собранном бинарном файле, посмотрев, содержит ли он секцию «.note.stapsdt».6768```console69$ readelf -S ./python | grep .note.stapsdt70[30] .note.stapsdt NOTE 0000000000000000 00308d7871```7273Если Python собран как разделяемая библиотека (с опцией конфигурации [`--enable-shared`](https://python-all.ru/3.12/using/configure.html#cmdoption-enable-shared)), то искать нужно в разделяемой библиотеке. Например:7475```console76$ readelf -S libpython3.3dm.so.1.0 | grep .note.stapsdt77[29] .note.stapsdt NOTE 0000000000000000 00365b6878```7980Достаточно современный readelf может вывести метаданные:8182```console83$ readelf -n ./python8485Displaying notes found at file offset 0x00000254 with length 0x00000020:86 Owner Data size Description87 GNU 0x00000010 NT_GNU_ABI_TAG (ABI version tag)88 OS: Linux, ABI: 2.6.328990Displaying notes found at file offset 0x00000274 with length 0x00000024:91 Owner Data size Description92 GNU 0x00000014 NT_GNU_BUILD_ID (unique build ID bitstring)93 Build ID: df924a2b08a7e89f6e11251d4602022977af26709495Displaying notes found at file offset 0x002d6c30 with length 0x00000144:96 Owner Data size Description97 stapsdt 0x00000031 NT_STAPSDT (SystemTap probe descriptors)98 Provider: python99 Name: gc__start100 Location: 0x00000000004371c3, Base: 0x0000000000630ce2, Semaphore: 0x00000000008d6bf6101 Arguments: -4@%ebx102 stapsdt 0x00000030 NT_STAPSDT (SystemTap probe descriptors)103 Provider: python104 Name: gc__done105 Location: 0x00000000004374e1, Base: 0x0000000000630ce2, Semaphore: 0x00000000008d6bf8106 Arguments: -8@%rax107 stapsdt 0x00000045 NT_STAPSDT (SystemTap probe descriptors)108 Provider: python109 Name: function__entry110 Location: 0x000000000053db6c, Base: 0x0000000000630ce2, Semaphore: 0x00000000008d6be8111 Arguments: 8@%rbp 8@%r12 -4@%eax112 stapsdt 0x00000046 NT_STAPSDT (SystemTap probe descriptors)113 Provider: python114 Name: function__return115 Location: 0x000000000053dba8, Base: 0x0000000000630ce2, Semaphore: 0x00000000008d6bea116 Arguments: 8@%rbp 8@%r12 -4@%eax117```118119Приведённые выше метаданные содержат информацию для SystemTap, описывающую, как он может модифицировать стратегически размещённые инструкции машинного кода, чтобы включить хуки трассировки, используемые скриптом SystemTap.120121## Статические зонды DTrace122123Следующий пример скрипта DTrace можно использовать для отображения иерархии вызовов/возвратов скрипта Python, трассируя только внутри вызова функции с именем «start». Иными словами, вызовы функций во время импорта отображаться не будут:124125```text126self int indent;127128python$target:::function-entry129/copyinstr(arg1) == "start"/130{131 self->trace = 1;132}133134python$target:::function-entry135/self->trace/136{137 printf("%d\t%*s:", timestamp, 15, probename);138 printf("%*s", self->indent, "");139 printf("%s:%s:%d\n", basename(copyinstr(arg0)), copyinstr(arg1), arg2);140 self->indent++;141}142143python$target:::function-return144/self->trace/145{146 self->indent--;147 printf("%d\t%*s:", timestamp, 15, probename);148 printf("%*s", self->indent, "");149 printf("%s:%s:%d\n", basename(copyinstr(arg0)), copyinstr(arg1), arg2);150}151152python$target:::function-return153/copyinstr(arg1) == "start"/154{155 self->trace = 0;156}157```158159Его можно вызвать так:160161```console162$ sudo dtrace -q -s call_stack.d -c "python3.6 script.py"163```164165Вывод выглядит так:166167```text168156641360502280 function-entry:call_stack.py:start:23169156641360518804 function-entry: call_stack.py:function_1:1170156641360532797 function-entry: call_stack.py:function_3:9171156641360546807 function-return: call_stack.py:function_3:10172156641360563367 function-return: call_stack.py:function_1:2173156641360578365 function-entry: call_stack.py:function_2:5174156641360591757 function-entry: call_stack.py:function_1:1175156641360605556 function-entry: call_stack.py:function_3:9176156641360617482 function-return: call_stack.py:function_3:10177156641360629814 function-return: call_stack.py:function_1:2178156641360642285 function-return: call_stack.py:function_2:6179156641360656770 function-entry: call_stack.py:function_3:9180156641360669707 function-return: call_stack.py:function_3:10181156641360687853 function-entry: call_stack.py:function_4:13182156641360700719 function-return: call_stack.py:function_4:14183156641360719640 function-entry: call_stack.py:function_5:18184156641360732567 function-return: call_stack.py:function_5:21185156641360747370 function-return:call_stack.py:start:28186```187188## Статические маркеры SystemTap189190Низкоуровневый способ использования интеграции с SystemTap заключается в прямом использовании статических маркеров. Для этого необходимо явно указать бинарный файл, содержащий их.191192Например, следующий скрипт SystemTap можно использовать для отображения иерархии вызовов/возвратов скрипта Python:193194```text195probe process("python").mark("function__entry") {196 filename = user_string($arg1);197 funcname = user_string($arg2);198 lineno = $arg3;199200 printf("%s => %s in %s:%d\\n",201 thread_indent(1), funcname, filename, lineno);202}203204probe process("python").mark("function__return") {205 filename = user_string($arg1);206 funcname = user_string($arg2);207 lineno = $arg3;208209 printf("%s <= %s in %s:%d\\n",210 thread_indent(-1), funcname, filename, lineno);211}212```213214Его можно вызвать так:215216```console217$ stap \218 show-call-hierarchy.stp \219 -c "./python test.py"220```221222Вывод выглядит так:223224```text22511408 python(8274): => __contains__ in Lib/_abcoll.py:36222611414 python(8274): => __getitem__ in Lib/os.py:42522711418 python(8274): => encode in Lib/os.py:49022811424 python(8274): <= encode in Lib/os.py:49322911428 python(8274): <= __getitem__ in Lib/os.py:42623011433 python(8274): <= __contains__ in Lib/_abcoll.py:366231```232233где столбцы означают:234235- время в микросекундах с момента запуска скрипта236- имя исполняемого файла237- PID процесса238239а остальная часть показывает иерархию вызовов/возвратов по мере выполнения скрипта.240241Для сборки CPython [`--enable-shared`](https://python-all.ru/3.12/using/configure.html#cmdoption-enable-shared) маркеры находятся внутри разделяемой библиотеки libpython, и точечный путь зонда должен это отражать. Например, следующая строка из приведённого выше примера:242243```text244probe process("python").mark("function__entry") {245```246247должна выглядеть так:248249```text250probe process("python").library("libpython3.6dm.so.1.0").mark("function__entry") {251```252253(предполагается [отладочная сборка](https://python-all.ru/3.12/using/configure.html#debug-build) CPython 3.6)254255## Доступные статические маркеры256257**function\_\_entry(str filename, str funcname, int lineno)**258259Этот маркер указывает, что началось выполнение функции Python. Он срабатывает только для чистых Python-функций (байткод).260261Имя файла, имя функции и номер строки передаются обратно скрипту трассировки в качестве позиционных аргументов, к которым необходимо обращаться через `$arg1`, `$arg2`, `$arg3`:262263> - `$arg1` : `(const char *)` filename, доступно через `user_string($arg1)`264> - `$arg2` : `(const char *)` имя функции, доступно через `user_string($arg2)`265> - `$arg3` : `int` номер строки266267**function\_\_return(str filename, str funcname, int lineno)**268269Этот маркер противоположен `function__entry()` и указывает, что выполнение функции Python завершилось (либо через `return`, либо через исключение). Он срабатывает только для чистых Python-функций (байткод).270271Аргументы такие же, как для `function__entry()`272273**line(str filename, str funcname, int lineno)**274275Этот маркер указывает, что строка Python скоро будет выполнена. Это эквивалент построчной трассировки с помощью профилировщика Python. Он не срабатывает внутри C-функций.276277Аргументы такие же, как для `function__entry()`.278279**gc\_\_start(int generation)**280281Срабатывает, когда интерпретатор Python запускает цикл сборки мусора. `arg0` – поколение для сканирования, например [`gc.collect()`](https://python-all.ru/3.12/library/gc.html#gc.collect).282283**gc\_\_done(long collected)**284285Срабатывает, когда интерпретатор Python завершает цикл сборки мусора. `arg0` – количество собранных объектов.286287**import\_\_find\_\_load\_\_start(str modulename)**288289Срабатывает до того, как [`importlib`](https://python-all.ru/3.12/library/importlib.html#module-importlib) попытается найти и загрузить модуль. `arg0` – имя модуля.290291Добавлено в версии 3.7.292293**import\_\_find\_\_load\_\_done(str modulename, int found)**294295Срабатывает после вызова функции find\_and\_load объекта [`importlib`](https://python-all.ru/3.12/library/importlib.html#module-importlib). `arg0` – имя модуля, `arg1` указывает, был ли модуль успешно загружен.296297Добавлено в версии 3.7.298299**audit(str event, void \*tuple)**300301Срабатывает при вызове [`sys.audit()`](https://python-all.ru/3.12/library/sys.html#sys.audit) или [`PySys_Audit()`](https://python-all.ru/3.12/c-api/sys.html#c.PySys_Audit). `arg0` – имя события в виде строки C, `arg1` – указатель [`PyObject`](https://python-all.ru/3.12/c-api/structures.html#c.PyObject) на объект кортежа.302303Добавлено в версии 3.8.304305## Тэпсеты SystemTap306307Более высокоуровневый способ использования интеграции SystemTap – это использование «тэпсета»: аналога библиотеки в SystemTap, который скрывает некоторые низкоуровневые детали статических маркеров.308309Вот файл тэпсета, основанный на неразделяемой сборке CPython:310311```text312/*313 Provide a higher-level wrapping around the function__entry and314 function__return markers:315 \*/316probe python.function.entry = process("python").mark("function__entry")317{318 filename = user_string($arg1);319 funcname = user_string($arg2);320 lineno = $arg3;321 frameptr = $arg4322}323probe python.function.return = process("python").mark("function__return")324{325 filename = user_string($arg1);326 funcname = user_string($arg2);327 lineno = $arg3;328 frameptr = $arg4329}330```331332Если этот файл установлен в каталог тэпсетов SystemTap (например, `/usr/share/systemtap/tapset`), то становятся доступны следующие дополнительные точки зондирования:333334**python.function.entry(str filename, str funcname, int lineno, frameptr)**335336Эта точка зондирования указывает, что выполнение функции Python началось. Она срабатывает только для чистых Python-функций (байт-код).337338**python.function.return(str filename, str funcname, int lineno, frameptr)**339340Эта точка зондирования является обратной к `python.function.return` и указывает, что выполнение функции Python завершено (либо через `return`, либо через исключение). Она срабатывает только для чистых Python (байт-код) функций.341342## Примеры343344Этот скрипт SystemTap использует приведённый выше тэпсет для более чистой реализации примера трассировки иерархии вызовов функций Python, без необходимости называть статические маркеры напрямую:345346```text347probe python.function.entry348{349 printf("%s => %s in %s:%d\n",350 thread_indent(1), funcname, filename, lineno);351}352353probe python.function.return354{355 printf("%s <= %s in %s:%d\n",356 thread_indent(-1), funcname, filename, lineno);357}358```359360Следующий скрипт использует тэпсет выше, чтобы предоставить представление типа top для всего выполняющегося кода CPython, показывая 20 наиболее часто входящих байт-код фреймов каждую секунду во всей системе:361362```text363global fn_calls;364365probe python.function.entry366{367 fn_calls[pid(), filename, funcname, lineno] += 1;368}369370probe timer.ms(1000) {371 printf("\033[2J\033[1;1H") /* clear screen \*/372 printf("%6s %80s %6s %30s %6s\n",373 "PID", "FILENAME", "LINE", "FUNCTION", "CALLS")374 foreach ([pid, filename, funcname, lineno] in fn_calls- limit 20) {375 printf("%6d %80s %6d %30s %6d\n",376 pid, filename, lineno, funcname,377 fn_calls[pid, filename, funcname, lineno]);378 }379 delete fn_calls;380}381```382