> **Источник:** https://python-all.ru/3.11/howto/instrumentation.html > > «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor. --- # Инструментирование CPython с помощью DTrace и SystemTap **автор:** David Malcolm **автор:** Łukasz Langa DTrace и SystemTap – это инструменты мониторинга, каждый из которых предоставляет способ проверки того, что делают процессы в компьютерной системе. Оба используют предметно-ориентированные языки, позволяющие пользователю писать сценарии, которые: - фильтровать, какие процессы наблюдать - собирать данные из интересующих процессов - создавать отчёты по данным Начиная с Python 3.6, CPython можно собрать со встроенными «маркерами», также известными как «зонды», которые могут наблюдаться скриптом DTrace или SystemTap, что упрощает мониторинг того, что делают процессы CPython в системе. **Особенность реализации CPython:** Маркеры DTrace являются деталями реализации интерпретатора CPython. Никаких гарантий совместимости зондов между версиями CPython не даётся. Скрипты DTrace могут перестать работать или работать некорректно без предупреждения при смене версий CPython. ## Включение статических маркеров macOS имеет встроенную поддержку DTrace. В Linux для сборки CPython со встроенными маркерами для SystemTap необходимо установить средства разработки SystemTap. На машине с Linux это можно сделать с помощью: ```console $ yum install systemtap-sdt-devel ``` или: ```console $ sudo apt-get install systemtap-sdt-dev ``` Затем CPython должен быть [`configured with the --with-dtrace option`](https://python-all.ru/3.11/using/configure.html#cmdoption-with-dtrace): ```text checking for --with-dtrace... yes ``` В macOS можно вывести список доступных зондов DTrace, запустив процесс Python в фоне и перечислив все зонды, предоставляемые провайдером Python: ```console $ python3.6 -q & $ sudo dtrace -l -P python$! # или: dtrace -l -m python3.6 ID PROVIDER MODULE FUNCTION NAME 29564 python18035 python3.6 _PyEval_EvalFrameDefault function-entry 29565 python18035 python3.6 dtrace_function_entry function-entry 29566 python18035 python3.6 _PyEval_EvalFrameDefault function-return 29567 python18035 python3.6 dtrace_function_return function-return 29568 python18035 python3.6 collect gc-done 29569 python18035 python3.6 collect gc-start 29570 python18035 python3.6 _PyEval_EvalFrameDefault line 29571 python18035 python3.6 maybe_dtrace_line line ``` В Linux можно проверить, присутствуют ли статические маркеры SystemTap в собранном бинарном файле, посмотрев, содержит ли он секцию «.note.stapsdt». ```console $ readelf -S ./python | grep .note.stapsdt [30] .note.stapsdt NOTE 0000000000000000 00308d78 ``` Если Python собран как разделяемая библиотека (с опцией конфигурации [`--enable-shared`](https://python-all.ru/3.11/using/configure.html#cmdoption-enable-shared)), то искать нужно в разделяемой библиотеке. Например: ```console $ readelf -S libpython3.3dm.so.1.0 | grep .note.stapsdt [29] .note.stapsdt NOTE 0000000000000000 00365b68 ``` Достаточно современный readelf может вывести метаданные: ```console $ readelf -n ./python Displaying notes found at file offset 0x00000254 with length 0x00000020: Owner Data size Description GNU 0x00000010 NT_GNU_ABI_TAG (ABI version tag) OS: Linux, ABI: 2.6.32 Displaying notes found at file offset 0x00000274 with length 0x00000024: Owner Data size Description GNU 0x00000014 NT_GNU_BUILD_ID (unique build ID bitstring) Build ID: df924a2b08a7e89f6e11251d4602022977af2670 Displaying notes found at file offset 0x002d6c30 with length 0x00000144: Owner Data size Description stapsdt 0x00000031 NT_STAPSDT (SystemTap probe descriptors) Provider: python Name: gc__start Location: 0x00000000004371c3, Base: 0x0000000000630ce2, Semaphore: 0x00000000008d6bf6 Arguments: -4@%ebx stapsdt 0x00000030 NT_STAPSDT (SystemTap probe descriptors) Provider: python Name: gc__done Location: 0x00000000004374e1, Base: 0x0000000000630ce2, Semaphore: 0x00000000008d6bf8 Arguments: -8@%rax stapsdt 0x00000045 NT_STAPSDT (SystemTap probe descriptors) Provider: python Name: function__entry Location: 0x000000000053db6c, Base: 0x0000000000630ce2, Semaphore: 0x00000000008d6be8 Arguments: 8@%rbp 8@%r12 -4@%eax stapsdt 0x00000046 NT_STAPSDT (SystemTap probe descriptors) Provider: python Name: function__return Location: 0x000000000053dba8, Base: 0x0000000000630ce2, Semaphore: 0x00000000008d6bea Arguments: 8@%rbp 8@%r12 -4@%eax ``` Приведённые выше метаданные содержат информацию для SystemTap, описывающую, как он может модифицировать стратегически размещённые инструкции машинного кода, чтобы включить хуки трассировки, используемые скриптом SystemTap. ## Статические зонды DTrace Следующий пример скрипта DTrace можно использовать для отображения иерархии вызовов/возвратов скрипта Python, трассируя только внутри вызова функции с именем «start». Иными словами, вызовы функций во время импорта отображаться не будут: ```text self int indent; python$target:::function-entry /copyinstr(arg1) == "start"/ { self->trace = 1; } python$target:::function-entry /self->trace/ { printf("%d\t%*s:", timestamp, 15, probename); printf("%*s", self->indent, ""); printf("%s:%s:%d\n", basename(copyinstr(arg0)), copyinstr(arg1), arg2); self->indent++; } python$target:::function-return /self->trace/ { self->indent--; printf("%d\t%*s:", timestamp, 15, probename); printf("%*s", self->indent, ""); printf("%s:%s:%d\n", basename(copyinstr(arg0)), copyinstr(arg1), arg2); } python$target:::function-return /copyinstr(arg1) == "start"/ { self->trace = 0; } ``` Его можно вызвать так: ```console $ sudo dtrace -q -s call_stack.d -c "python3.6 script.py" ``` Вывод выглядит так: ```text 156641360502280 function-entry:call_stack.py:start:23 156641360518804 function-entry: call_stack.py:function_1:1 156641360532797 function-entry: call_stack.py:function_3:9 156641360546807 function-return: call_stack.py:function_3:10 156641360563367 function-return: call_stack.py:function_1:2 156641360578365 function-entry: call_stack.py:function_2:5 156641360591757 function-entry: call_stack.py:function_1:1 156641360605556 function-entry: call_stack.py:function_3:9 156641360617482 function-return: call_stack.py:function_3:10 156641360629814 function-return: call_stack.py:function_1:2 156641360642285 function-return: call_stack.py:function_2:6 156641360656770 function-entry: call_stack.py:function_3:9 156641360669707 function-return: call_stack.py:function_3:10 156641360687853 function-entry: call_stack.py:function_4:13 156641360700719 function-return: call_stack.py:function_4:14 156641360719640 function-entry: call_stack.py:function_5:18 156641360732567 function-return: call_stack.py:function_5:21 156641360747370 function-return:call_stack.py:start:28 ``` ## Статические маркеры SystemTap Низкоуровневый способ использования интеграции с SystemTap заключается в прямом использовании статических маркеров. Для этого необходимо явно указать бинарный файл, содержащий их. Например, следующий скрипт SystemTap можно использовать для отображения иерархии вызовов/возвратов скрипта Python: ```text probe process("python").mark("function__entry") { filename = user_string($arg1); funcname = user_string($arg2); lineno = $arg3; printf("%s => %s in %s:%d\\n", thread_indent(1), funcname, filename, lineno); } probe process("python").mark("function__return") { filename = user_string($arg1); funcname = user_string($arg2); lineno = $arg3; printf("%s <= %s in %s:%d\\n", thread_indent(-1), funcname, filename, lineno); } ``` Его можно вызвать так: ```console $ stap \ show-call-hierarchy.stp \ -c "./python test.py" ``` Вывод выглядит так: ```text 11408 python(8274): => __contains__ in Lib/_abcoll.py:362 11414 python(8274): => __getitem__ in Lib/os.py:425 11418 python(8274): => encode in Lib/os.py:490 11424 python(8274): <= encode in Lib/os.py:493 11428 python(8274): <= __getitem__ in Lib/os.py:426 11433 python(8274): <= __contains__ in Lib/_abcoll.py:366 ``` где столбцы означают: - время в микросекундах с момента запуска скрипта - имя исполняемого файла - PID процесса а остальная часть показывает иерархию вызовов/возвратов по мере выполнения скрипта. Для сборки CPython [`--enable-shared`](https://python-all.ru/3.11/using/configure.html#cmdoption-enable-shared) маркеры находятся внутри разделяемой библиотеки libpython, и точечный путь зонда должен это отражать. Например, следующая строка из приведённого выше примера: ```text probe process("python").mark("function__entry") { ``` должна выглядеть так: ```text probe process("python").library("libpython3.6dm.so.1.0").mark("function__entry") { ``` (предполагается [отладочная сборка](https://python-all.ru/3.11/using/configure.html#debug-build) CPython 3.6) ## Доступные статические маркеры **function\_\_entry(str filename, str funcname, int lineno)** Этот маркер указывает, что началось выполнение функции Python. Он срабатывает только для чистых Python-функций (байткод). Имя файла, имя функции и номер строки передаются обратно скрипту трассировки в качестве позиционных аргументов, к которым необходимо обращаться через `$arg1`, `$arg2`, `$arg3`: > - `$arg1` : `(const char *)` filename, доступно через `user_string($arg1)` > - `$arg2` : `(const char *)` имя функции, доступно через `user_string($arg2)` > - `$arg3` : `int` номер строки **function\_\_return(str filename, str funcname, int lineno)** Этот маркер противоположен `function__entry()` и указывает, что выполнение функции Python завершилось (либо через `return`, либо через исключение). Он срабатывает только для чистых Python-функций (байткод). Аргументы такие же, как для `function__entry()` **line(str filename, str funcname, int lineno)** Этот маркер указывает, что строка Python скоро будет выполнена. Это эквивалент построчной трассировки с помощью профилировщика Python. Он не срабатывает внутри C-функций. Аргументы такие же, как для `function__entry()`. **gc\_\_start(int generation)** Срабатывает, когда интерпретатор Python запускает цикл сборки мусора. `arg0` – поколение для сканирования, например [`gc.collect()`](https://python-all.ru/3.11/library/gc.html#gc.collect). **gc\_\_done(long collected)** Срабатывает, когда интерпретатор Python завершает цикл сборки мусора. `arg0` – количество собранных объектов. **import\_\_find\_\_load\_\_start(str modulename)** Срабатывает до того, как [`importlib`](https://python-all.ru/3.11/library/importlib.html#module-importlib) попытается найти и загрузить модуль. `arg0` – имя модуля. Добавлено в версии 3.7. **import\_\_find\_\_load\_\_done(str modulename, int found)** Срабатывает после вызова функции find\_and\_load объекта [`importlib`](https://python-all.ru/3.11/library/importlib.html#module-importlib). `arg0` – имя модуля, `arg1` указывает, был ли модуль успешно загружен. Добавлено в версии 3.7. **audit(str event, void \*tuple)** Срабатывает при вызове [`sys.audit()`](https://python-all.ru/3.11/library/sys.html#sys.audit) или [`PySys_Audit()`](https://python-all.ru/3.11/c-api/sys.html#c.PySys_Audit). `arg0` – имя события в виде строки C, `arg1` – указатель [`PyObject`](https://python-all.ru/3.11/c-api/structures.html#c.PyObject) на объект кортежа. Новое в версии 3.8. ## Тэпсеты SystemTap Более высокоуровневый способ использования интеграции SystemTap – это использование «тэпсета»: аналога библиотеки в SystemTap, который скрывает некоторые низкоуровневые детали статических маркеров. Вот файл тэпсета, основанный на неразделяемой сборке CPython: ```text /* Provide a higher-level wrapping around the function__entry and function__return markers: \*/ probe python.function.entry = process("python").mark("function__entry") { filename = user_string($arg1); funcname = user_string($arg2); lineno = $arg3; frameptr = $arg4 } probe python.function.return = process("python").mark("function__return") { filename = user_string($arg1); funcname = user_string($arg2); lineno = $arg3; frameptr = $arg4 } ``` Если этот файл установлен в каталог тэпсетов SystemTap (например, `/usr/share/systemtap/tapset`), то становятся доступны следующие дополнительные точки зондирования: **python.function.entry(str filename, str funcname, int lineno, frameptr)** Эта точка зондирования указывает, что выполнение функции Python началось. Она срабатывает только для чистых Python-функций (байт-код). **python.function.return(str filename, str funcname, int lineno, frameptr)** Эта точка зондирования является обратной к `python.function.return` и указывает, что выполнение функции Python завершено (либо через `return`, либо через исключение). Она срабатывает только для чистых Python (байт-код) функций. ## Примеры Этот скрипт SystemTap использует приведённый выше тэпсет для более чистой реализации примера трассировки иерархии вызовов функций Python, без необходимости называть статические маркеры напрямую: ```text probe python.function.entry { printf("%s => %s in %s:%d\n", thread_indent(1), funcname, filename, lineno); } probe python.function.return { printf("%s <= %s in %s:%d\n", thread_indent(-1), funcname, filename, lineno); } ``` Следующий скрипт использует тэпсет выше, чтобы предоставить представление типа top для всего выполняющегося кода CPython, показывая 20 наиболее часто входящих байт-код фреймов каждую секунду во всей системе: ```text global fn_calls; probe python.function.entry { fn_calls[pid(), filename, funcname, lineno] += 1; } probe timer.ms(1000) { printf("\033[2J\033[1;1H") /* clear screen \*/ printf("%6s %80s %6s %30s %6s\n", "PID", "FILENAME", "LINE", "FUNCTION", "CALLS") foreach ([pid, filename, funcname, lineno] in fn_calls- limit 20) { printf("%6d %80s %6d %30s %6d\n", pid, filename, lineno, funcname, fn_calls[pid, filename, funcname, lineno]); } delete fn_calls; } ```