`instrumentation.md`

433 строк · 21.7 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3/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/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/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/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/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/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/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/library/importlib.html#module-importlib). `arg0` – имя модуля, `arg1` указывает, был ли модуль успешно загружен.296297Добавлено в версии 3.7.298299**audit(str event, void \*tuple)**300301Срабатывает при вызове [`sys.audit()`](https://python-all.ru/3/library/sys.html#sys.audit) или [`PySys_Audit()`](https://python-all.ru/3/c-api/sys.html#c.PySys_Audit). `arg0` – имя события в виде строки C, `arg1` – указатель [`PyObject`](https://python-all.ru/3/c-api/structures.html#c.PyObject) на объект кортежа.302303Добавлено в версии 3.8.304305### Точки входа в C306307Чтобы упростить запуск маркеров DTrace, C API Python содержит ряд вспомогательных функций, повторяющих каждый статический маркер. В сборках Python без поддержки DTrace эти функции ничего не делают.308309В общем случае вызывать их вручную не требуется – Python сделает это сам.310311| Функция C API | Статический маркер | Примечания |312| --- | --- | --- |313| void PyDTrace\_LINE(const char \*arg0, const char \*arg1, int arg2) | `line()` |  |314| void PyDTrace\_FUNCTION\_ENTRY(const char \*arg0, const char \*arg1, int arg2) | `function__entry()` |  |315| void PyDTrace\_FUNCTION\_RETURN(const char \*arg0, const char \*arg1, int arg2) | `function__return()` |  |316| void PyDTrace\_GC\_START(int arg0) | `gc__start()` |  |317| void PyDTrace\_GC\_DONE([Py\_ssize\_t](https://python-all.ru/3/c-api/intro.html#c.Py_ssize_t) arg0) | `gc__done()` |  |318| void PyDTrace\_INSTANCE\_NEW\_START(int arg0) | `instance__new__start()` | Не используется в Python |319| void PyDTrace\_INSTANCE\_NEW\_DONE(int arg0) | `instance__new__done()` | Не используется в Python |320| void PyDTrace\_INSTANCE\_DELETE\_START(int arg0) | `instance__delete__start()` | Не используется в Python |321| void PyDTrace\_INSTANCE\_DELETE\_DONE(int arg0) | `instance__delete__done()` | Не используется в Python |322| void PyDTrace\_IMPORT\_FIND\_LOAD\_START(const char \*arg0) | `import__find__load__start()` |  |323| void PyDTrace\_IMPORT\_FIND\_LOAD\_DONE(const char \*arg0, int arg1) | `import__find__load__done()` |  |324| void PyDTrace\_AUDIT(const char \*arg0, void \*arg1) | `audit()` |  |325326### C-проверки зондов327328#### `int PyDTrace_LINE_ENABLED(void)`329330#### `int PyDTrace_FUNCTION_ENTRY_ENABLED(void)`331332#### `int PyDTrace_FUNCTION_RETURN_ENABLED(void)`333334#### `int PyDTrace_GC_START_ENABLED(void)`335336#### `int PyDTrace_GC_DONE_ENABLED(void)`337338#### `int PyDTrace_INSTANCE_NEW_START_ENABLED(void)`339340#### `int PyDTrace_INSTANCE_NEW_DONE_ENABLED(void)`341342#### `int PyDTrace_INSTANCE_DELETE_START_ENABLED(void)`343344#### `int PyDTrace_INSTANCE_DELETE_DONE_ENABLED(void)`345346#### `int PyDTrace_IMPORT_FIND_LOAD_START_ENABLED(void)`347348#### `int PyDTrace_IMPORT_FIND_LOAD_DONE_ENABLED(void)`349350#### `int PyDTrace_AUDIT_ENABLED(void)`351352Все вызовы функций `PyDTrace` должны быть защищены вызовом одной из этих функций. Это позволяет Python минимизировать влияние на производительность, когда зондирование отключено.353354В сборках без включённого DTrace эти функции ничего не делают и возвращают `0`.355356## Тэпсеты SystemTap357358Более высокоуровневый способ использования интеграции SystemTap – это использование «тэпсета»: аналога библиотеки в SystemTap, который скрывает некоторые низкоуровневые детали статических маркеров.359360Вот файл тэпсета, основанный на неразделяемой сборке CPython:361362```text363/*364   Provide a higher-level wrapping around the function__entry and365   function__return markers:366 \*/367probe python.function.entry = process("python").mark("function__entry")368{369    filename = user_string($arg1);370    funcname = user_string($arg2);371    lineno = $arg3;372    frameptr = $arg4373}374probe python.function.return = process("python").mark("function__return")375{376    filename = user_string($arg1);377    funcname = user_string($arg2);378    lineno = $arg3;379    frameptr = $arg4380}381```382383Если этот файл установлен в каталог тэпсетов SystemTap (например, `/usr/share/systemtap/tapset`), то становятся доступны следующие дополнительные точки зондирования:384385**python.function.entry(str filename, str funcname, int lineno, frameptr)**386387Эта точка зондирования указывает, что выполнение функции Python началось. Она срабатывает только для чистых Python-функций (байт-код).388389**python.function.return(str filename, str funcname, int lineno, frameptr)**390391Эта точка зондирования является обратной к `python.function.return` и указывает, что выполнение функции Python завершено (либо через `return`, либо через исключение). Она срабатывает только для чистых Python (байт-код) функций.392393## Примеры394395Этот скрипт SystemTap использует приведённый выше тэпсет для более чистой реализации примера трассировки иерархии вызовов функций Python, без необходимости называть статические маркеры напрямую:396397```text398probe python.function.entry399{400  printf("%s => %s in %s:%d\n",401         thread_indent(1), funcname, filename, lineno);402}403404probe python.function.return405{406  printf("%s <= %s in %s:%d\n",407         thread_indent(-1), funcname, filename, lineno);408}409```410411Следующий скрипт использует тэпсет выше, чтобы предоставить представление типа top для всего выполняющегося кода CPython, показывая 20 наиболее часто входящих байт-код фреймов каждую секунду во всей системе:412413```text414global fn_calls;415416probe python.function.entry417{418    fn_calls[pid(), filename, funcname, lineno] += 1;419}420421probe timer.ms(1000) {422    printf("\033[2J\033[1;1H") /* clear screen \*/423    printf("%6s %80s %6s %30s %6s\n",424           "PID", "FILENAME", "LINE", "FUNCTION", "CALLS")425    foreach ([pid, filename, funcname, lineno] in fn_calls- limit 20) {426        printf("%6d %80s %6d %30s %6d\n",427            pid, filename, lineno, funcname,428            fn_calls[pid, filename, funcname, lineno]);429    }430    delete fn_calls;431}432```433