Профилирование и трассировка

Интерпретатор Python предоставляет низкоуровневые средства для подключения профилировщиков и средств трассировки выполнения. Они используются для профилирования, отладки и анализа покрытия кода.

Этот интерфейс C позволяет коду профилирования или трассировки избежать накладных расходов на вызов вызываемых объектов на уровне Python, выполняя вместо этого прямой вызов функции C. Основные свойства этих средств не изменились; интерфейс позволяет устанавливать функции трассировки для каждого потока, а базовые события, передаваемые функции трассировки, совпадают с теми, которые передавались функциям трассировки уровня Python в предыдущих версиях.

typedef int (*Py_tracefunc)(PyObject *obj, PyFrameObject *frame, int what, PyObject *arg)

Тип функции трассировки, зарегистрированной с помощью PyEval_SetProfile() и PyEval_SetTrace(). Первый параметр — объект, переданный функции регистрации как obj, frame — объект кадра, к которому относится событие, what — одна из констант PyTrace_CALL, PyTrace_EXCEPTION, PyTrace_LINE, PyTrace_RETURN, PyTrace_C_CALL, PyTrace_C_EXCEPTION, PyTrace_C_RETURN или PyTrace_OPCODE, а значение arg зависит от значения what:

Значение what	Значение arg
PyTrace_CALL	Всегда Py_None.
PyTrace_EXCEPTION	Информация об исключении, возвращаемая функцией sys.exc_info().
PyTrace_LINE	Всегда Py_None.
PyTrace_RETURN	Значение, возвращаемое вызывающей стороне, или NULL, если возврат вызван исключением.
PyTrace_C_CALL	Вызываемый объект-функция.
PyTrace_C_EXCEPTION	Вызываемый объект-функция.
PyTrace_C_RETURN	Вызываемый объект-функция.
PyTrace_OPCODE	Всегда Py_None.

int PyTrace_CALL

Значение параметра what функции Py_tracefunc, когда регистрируется новый вызов функции или метода либо новый вход в генератор. Обратите внимание: создание итератора для функции-генератора не регистрируется, поскольку в соответствующем кадре не происходит передачи управления байт-коду Python.

int PyTrace_EXCEPTION

Значение параметра what функции Py_tracefunc, когда возникает исключение. Функция обратного вызова вызывается с этим значением параметра what после обработки любого байт-кода, в результате которой в выполняемом кадре устанавливается исключение. Поэтому, когда распространение исключения приводит к раскрутке стека Python, функция обратного вызова вызывается при возврате в каждый кадр по мере распространения исключения. Эти события получают только функции трассировки; профилировщику они не нужны.

int PyTrace_LINE

Значение параметра what функции Py_tracefunc (но не функции профилирования), когда регистрируется событие номера строки. Его можно отключить для кадра, установив для f_trace_lines этого кадра значение 0.

int PyTrace_RETURN

Значение параметра what функций Py_tracefunc, когда вызов собирается завершиться возвратом.

int PyTrace_C_CALL

Значение параметра what функций Py_tracefunc, когда собираются вызвать функцию C.

int PyTrace_C_EXCEPTION

Значение параметра what функций Py_tracefunc, когда функция C вызвала исключение.

int PyTrace_C_RETURN

Значение параметра what функций Py_tracefunc, когда функция C завершила работу.

int PyTrace_OPCODE

Значение параметра what функций Py_tracefunc (но не функций профилирования), когда собираются выполнить новую инструкцию. По умолчанию это событие не создаётся: его необходимо явно запросить, установив для f_trace_opcodes кадра значение 1.

void PyEval_SetProfile(Py_tracefunc func, PyObject *obj)

Устанавливает функцию профилирования func. Параметр obj передаётся функции как её первый параметр и может быть любым объектом Python или NULL. Если функции профилирования необходимо сохранять состояние, использование отдельного значения obj для каждого потока обеспечивает удобное и потокобезопасное место для его хранения. Функция профилирования вызывается для всех отслеживаемых событий, кроме PyTrace_LINE, PyTrace_OPCODE и PyTrace_EXCEPTION.

См. также функцию sys.setprofile().

У вызывающего кода должно быть присоединённое состояние потока.

void PyEval_SetProfileAllThreads(Py_tracefunc func, PyObject *obj)

Подобно PyEval_SetProfile(), но устанавливает функцию профилирования во всех работающих потоках текущего интерпретатора, а не только в текущем потоке.

У вызывающего кода должно быть присоединённое состояние потока.

Как и PyEval_SetProfile(), эта функция игнорирует исключения, возникающие при установке функций профилирования во всех потоках.

void PyEval_SetTrace(Py_tracefunc func, PyObject *obj)

Устанавливает функцию трассировки func. Она похожа на PyEval_SetProfile(), но функция трассировки получает события номеров строк и события для каждой инструкции, не получая при этом событий, связанных с вызовом объектов-функций C. Функция трассировки, зарегистрированная с помощью PyEval_SetTrace(), не будет получать PyTrace_C_CALL, PyTrace_C_EXCEPTION или PyTrace_C_RETURN в качестве значения параметра what.

См. также функцию sys.settrace().

У вызывающего кода должно быть присоединённое состояние потока.

void PyEval_SetTraceAllThreads(Py_tracefunc func, PyObject *obj)

Подобно PyEval_SetTrace(), но устанавливает функцию трассировки во всех работающих потоках текущего интерпретатора, а не только в текущем потоке.

У вызывающего кода должно быть присоединённое состояние потока.

Как и PyEval_SetTrace(), эта функция игнорирует исключения, возникающие при установке функций трассировки во всех потоках.