Profiling and tracing¶

The Python interpreter provides some low-level support for attaching profilingand execution tracing facilities. These are used for profiling, debugging, andcoverage analysis tools.

This C interface allows the profiling or tracing code to avoid the overhead ofcalling through Python-level callable objects, making a direct C function callinstead. The essential attributes of the facility have not changed; theinterface allows trace functions to be installed per-thread, and the basicevents reported to the trace function are the same as had been reported to thePython-level trace functions in previous versions.

typedefint(*Py_tracefunc)(PyObject*obj,PyFrameObject*frame,intwhat,PyObject*arg)¶

The type of the trace function registered usingPyEval_SetProfile() andPyEval_SetTrace(). The first parameter is the object passed to theregistration function asobj,frame is the frame object to which the eventpertains,what is one of the constantsPyTrace_CALL,PyTrace_EXCEPTION,PyTrace_LINE,PyTrace_RETURN,PyTrace_C_CALL,PyTrace_C_EXCEPTION,PyTrace_C_RETURN,orPyTrace_OPCODE, andarg depends on the value ofwhat:

Value ofwhat	Meaning ofarg
PyTrace_CALL	AlwaysPy_None.
PyTrace_EXCEPTION	Exception information as returned bysys.exc_info().
PyTrace_LINE	AlwaysPy_None.
PyTrace_RETURN	Value being returned to the caller,orNULL if caused by an exception.
PyTrace_C_CALL	Function object being called.
PyTrace_C_EXCEPTION	Function object being called.
PyTrace_C_RETURN	Function object being called.
PyTrace_OPCODE	AlwaysPy_None.

intPyTrace_CALL¶

The value of thewhat parameter to aPy_tracefunc function when a newcall to a function or method is being reported, or a new entry into a generator.Note that the creation of the iterator for a generator function is not reportedas there is no control transfer to the Python bytecode in the correspondingframe.

intPyTrace_EXCEPTION¶

The value of thewhat parameter to aPy_tracefunc function when anexception has been raised. The callback function is called with this value forwhat when after any bytecode is processed after which the exception becomesset within the frame being executed. The effect of this is that as exceptionpropagation causes the Python stack to unwind, the callback is called uponreturn to each frame as the exception propagates. Only trace functions receivethese events; they are not needed by the profiler.

intPyTrace_LINE¶

The value passed as thewhat parameter to aPy_tracefunc function(but not a profiling function) when a line-number event is being reported.It may be disabled for a frame by settingf_trace_lines to0 on that frame.

intPyTrace_RETURN¶

The value for thewhat parameter toPy_tracefunc functions when acall is about to return.

intPyTrace_C_CALL¶

The value for thewhat parameter toPy_tracefunc functions when a Cfunction is about to be called.

intPyTrace_C_EXCEPTION¶

The value for thewhat parameter toPy_tracefunc functions when a Cfunction has raised an exception.

intPyTrace_C_RETURN¶

The value for thewhat parameter toPy_tracefunc functions when a Cfunction has returned.

intPyTrace_OPCODE¶

The value for thewhat parameter toPy_tracefunc functions (but notprofiling functions) when a new opcode is about to be executed. This event isnot emitted by default: it must be explicitly requested by settingf_trace_opcodes to1 on the frame.

voidPyEval_SetProfile(Py_tracefuncfunc,PyObject*obj)¶

Set the profiler function tofunc. Theobj parameter is passed to thefunction as its first parameter, and may be any Python object, orNULL. Ifthe profile function needs to maintain state, using a different value forobjfor each thread provides a convenient and thread-safe place to store it. Theprofile function is called for all monitored events exceptPyTrace_LINEPyTrace_OPCODE andPyTrace_EXCEPTION.

See also thesys.setprofile() function.

The caller must have anattached thread state.

voidPyEval_SetProfileAllThreads(Py_tracefuncfunc,PyObject*obj)¶

LikePyEval_SetProfile() but sets the profile function in all running threadsbelonging to the current interpreter instead of the setting it only on the current thread.

The caller must have anattached thread state.

AsPyEval_SetProfile(), this function ignores any exceptions raised whilesetting the profile functions in all threads.

voidPyEval_SetTrace(Py_tracefuncfunc,PyObject*obj)¶

Set the tracing function tofunc. This is similar toPyEval_SetProfile(), except the tracing function does receive line-numberevents and per-opcode events, but does not receive any event related to C functionobjects being called. Any trace function registered usingPyEval_SetTrace()will not receivePyTrace_C_CALL,PyTrace_C_EXCEPTION orPyTrace_C_RETURN as a value for thewhat parameter.

See also thesys.settrace() function.

The caller must have anattached thread state.

voidPyEval_SetTraceAllThreads(Py_tracefuncfunc,PyObject*obj)¶

LikePyEval_SetTrace() but sets the tracing function in all running threadsbelonging to the current interpreter instead of the setting it only on the current thread.

The caller must have anattached thread state.

AsPyEval_SetTrace(), this function ignores any exceptions raised whilesetting the trace functions in all threads.

Reference tracing¶

typedefint(*PyRefTracer)(PyObject*,intevent,void*data)¶

The type of the trace function registered usingPyRefTracer_SetTracer().The first parameter is a Python object that has been just created (wheneventis set toPyRefTracer_CREATE) or about to be destroyed (wheneventis set toPyRefTracer_DESTROY). Thedata argument is the opaque pointerthat was provided whenPyRefTracer_SetTracer() was called.

If a new tracing function is registered replacing the current one, a call to thetrace function will be made with the object set toNULL andevent set toPyRefTracer_TRACKER_REMOVED. This will happen just before the newfunction is registered.

intPyRefTracer_CREATE¶

The value for theevent parameter toPyRefTracer functions when a Pythonobject has been created.

intPyRefTracer_DESTROY¶

The value for theevent parameter toPyRefTracer functions when a Pythonobject has been destroyed.

intPyRefTracer_TRACKER_REMOVED¶

The value for theevent parameter toPyRefTracer functions when thecurrent tracer is about to be replaced by a new one.

Added in version 3.14.

intPyRefTracer_SetTracer(PyRefTracertracer,void*data)¶

Register a reference tracer function. The function will be called when a newPython object has been created or when an object is going to be destroyed. Ifdata is provided it must be an opaque pointer that will be provided whenthe tracer function is called. Return0 on success. Set an exception andreturn-1 on error.

Note that tracer functionsmust not create Python objects inside orotherwise the call will be re-entrant. The tracer alsomust not clearany existing exception or set an exception. Athread state will be activeevery time the tracer function is called.

There must be anattached thread state when calling this function.

If another tracer function was already registered, the old function will becalled withevent set toPyRefTracer_TRACKER_REMOVED just beforethe new function is registered.

PyRefTracerPyRefTracer_GetTracer(void**data)¶

Get the registered reference tracer function and the value of the opaque datapointer that was registered whenPyRefTracer_SetTracer() was called.If no tracer was registered this function will return NULL and will set thedata pointer to NULL.

There must be anattached thread state when calling this function.