`instrumentation.md`

376 строк · 18.4 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.7/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```4243CPython must then be configured `--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), поиск следует вести внутри этой разделяемой библиотеки. Например: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* маркеры содержатся внутри разделяемой библиотеки 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(предполагается отладочная сборка 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()`](https://python-all.ru/3.7/howto/instrumentation.html#c.function__entry) и указывает, что выполнение функции Python завершилось (либо через `return`, либо через исключение). Он срабатывает только для чистых Python-функций (байткод).270271Аргументы такие же, как для [`function__entry()`](https://python-all.ru/3.7/howto/instrumentation.html#c.function__entry)272273#### `line(str filename, str funcname, int lineno)`274275Этот маркер указывает, что строка Python скоро будет выполнена. Это эквивалент построчной трассировки с помощью профилировщика Python. Он не срабатывает внутри C-функций.276277Аргументы такие же, как для [`function__entry()`](https://python-all.ru/3.7/howto/instrumentation.html#c.function__entry).278279#### `gc__start(int generation)`280281Срабатывает, когда интерпретатор Python запускает цикл сборки мусора. `arg0` – поколение для сканирования, например [`gc.collect()`](https://python-all.ru/3.7/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.7/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.7/library/importlib.html#module-importlib). `arg0` – имя модуля, `arg1` указывает, был ли модуль успешно загружен.296297Добавлено в версии 3.7.298299## Тэпсеты SystemTap300301Более высокоуровневый способ использования интеграции SystemTap – это использование «тэпсета»: аналога библиотеки в SystemTap, который скрывает некоторые низкоуровневые детали статических маркеров.302303Вот файл тэпсета, основанный на неразделяемой сборке CPython:304305```text306/*307   Provide a higher-level wrapping around the function__entry and308   function__return markers:309 \*/310probe python.function.entry = process("python").mark("function__entry")311{312    filename = user_string($arg1);313    funcname = user_string($arg2);314    lineno = $arg3;315    frameptr = $arg4316}317probe python.function.return = process("python").mark("function__return")318{319    filename = user_string($arg1);320    funcname = user_string($arg2);321    lineno = $arg3;322    frameptr = $arg4323}324```325326Если этот файл установлен в каталог тэпсетов SystemTap (например, `/usr/share/systemtap/tapset`), то становятся доступны следующие дополнительные точки зондирования:327328#### `python.function.entry(str filename, str funcname, int lineno, frameptr)`329330Эта точка зондирования указывает, что выполнение функции Python началось. Она срабатывает только для чистых Python-функций (байт-код).331332#### `python.function.return(str filename, str funcname, int lineno, frameptr)`333334Эта точка зондирования является обратной к [`python.function.return()`](https://python-all.ru/3.7/howto/instrumentation.html#c.python.function.return) и указывает, что выполнение функции Python завершено (либо через `return`, либо через исключение). Она срабатывает только для чистых Python (байт-код) функций.335336## Примеры337338Этот скрипт SystemTap использует приведённый выше тэпсет для более чистой реализации примера трассировки иерархии вызовов функций Python, без необходимости называть статические маркеры напрямую:339340```text341probe python.function.entry342{343  printf("%s => %s in %s:%d\n",344         thread_indent(1), funcname, filename, lineno);345}346347probe python.function.return348{349  printf("%s <= %s in %s:%d\n",350         thread_indent(-1), funcname, filename, lineno);351}352```353354Следующий скрипт использует указанный выше tapset для отображения представления в стиле top для всего выполняющегося кода CPython, показывая каждую секунду 20 наиболее часто встречающихся фреймов байт-кода во всей системе:355356```text357global fn_calls;358359probe python.function.entry360{361    fn_calls[pid(), filename, funcname, lineno] += 1;362}363364probe timer.ms(1000) {365    printf("\033[2J\033[1;1H") /* clear screen \*/366    printf("%6s %80s %6s %30s %6s\n",367           "PID", "FILENAME", "LINE", "FUNCTION", "CALLS")368    foreach ([pid, filename, funcname, lineno] in fn_calls- limit 20) {369        printf("%6d %80s %6d %30s %6d\n",370            pid, filename, lineno, funcname,371            fn_calls[pid, filename, funcname, lineno]);372    }373    delete fn_calls;374}375```376