Профилирование и трассировка¶Profiling and tracing

Интерпретатор 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(), эта функция игнорирует любые исключения, возникшие при установке функций трассировки во всех потоках.

Трассировка ссылок¶Reference tracing

typedef int (*PyRefTracer)(PyObject*, int event, void *data)¶

Тип функции трассировки, регистрируемой с помощью PyRefTracer_SetTracer(). Первый параметр – это объект Python, который только что был создан (когда event установлен в PyRefTracer_CREATE) или собирается быть уничтожен (когда event установлен в PyRefTracer_DESTROY). Аргумент data – это непрозрачный указатель, который был предоставлен при вызове PyRefTracer_SetTracer().

Если регистрируется новая функция трассировки, заменяющая текущую, будет выполнен вызов функции трассировки с объектом, установленным в NULL, и event, установленным в PyRefTracer_TRACKER_REMOVED. Это произойдет непосредственно перед регистрацией новой функции.

int PyRefTracer_CREATE¶

Значение параметра event для функций PyRefTracer, когда объект Python был создан.

int PyRefTracer_DESTROY¶

Значение параметра event для функций PyRefTracer, когда объект Python был уничтожен.

int PyRefTracer_TRACKER_REMOVED¶

Значение параметра event для функций PyRefTracer, когда текущий трассировщик собирается быть заменён новым.

Добавлено в версии 3.14.

int PyRefTracer_SetTracer(PyRefTracer tracer, void *data)¶

Регистрирует функцию трассировки ссылок. Функция будет вызываться при создании нового объекта Python или при уничтожении объекта. Если указан data, это должен быть непрозрачный указатель, который будет предоставлен при вызове функции трассировки. Возвращает 0 в случае успеха. Устанавливает исключение и возвращает -1 при ошибке.

Обратите внимание, что функции трассировки не должны создавать объекты Python внутри, иначе вызов станет реентерабельным. Трассировщик также не должен очищать существующие исключения или устанавливать исключения. Состояние потока будет активно при каждом вызове функции трассировки.

При вызове этой функции должно быть присоединённое состояние потока.

Если другая функция трассировки уже была зарегистрирована, старая функция будет вызвана с event, установленным в PyRefTracer_TRACKER_REMOVED, непосредственно перед регистрацией новой функции.

PyRefTracer PyRefTracer_GetTracer(void **data)¶

Возвращает зарегистрированную функцию трассировки ссылок и значение непрозрачного указателя данных, который был зарегистрирован при вызове PyRefTracer_SetTracer(). Если трассировщик не был зарегистрирован, эта функция вернёт NULL и установит указатель data в NULL.

При вызове этой функции должно быть присоединённое состояние потока.