#
8.2 Profiling and Tracing

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

Starting with Python 2.2, the implementation of this facility was substantially revised, and an interface from C was added. This C interface allows the profiling or tracing code to avoid the overhead of calling through Python-level callable objects, making a direct C function call instead. The essential attributes of the facility have not changed; the interface allows trace functions to be installed per-thread, and the basic events reported to the trace function are the same as had been reported to the Python-level trace functions in previous versions.

`int (*Py_tracefunc)(PyObject *obj, PyFrameObject *frame, int what, PyObject *arg)`
  The type of the trace function registered using `PyEval_SetProfile()` and `PyEval_SetTrace()`. The first parameter is the object passed to the registration function as obj, frame is the frame object to which the event pertains, what is one of the constants `PyTrace_CALL`, `PyTrace_EXCEPTION`, `PyTrace_LINE`, `PyTrace_RETURN`, `PyTrace_C_CALL`, `PyTrace_C_EXCEPTION`, or `PyTrace_C_RETURN`, and arg depends on the value of what:

  Value of what | Meaning of arg
  --- | ---
  `PyTrace_CALL` | Always `NULL`.
  `PyTrace_EXCEPTION` | Exception information as returned by `sys.exc_info()`.
  `PyTrace_LINE` | Always `NULL`.
  `PyTrace_RETURN` | Value being returned to the caller.
  `PyTrace_C_CALL` | Name of function being called.
  `PyTrace_C_EXCEPTION` | Always `NULL`.
  `PyTrace_C_RETURN` | Always `NULL`.

int `PyTrace_CALL`
  The value of the what parameter to a `Py_tracefunc` function when a new call 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 reported as there is no control transfer to the Python bytecode in the corresponding frame.

int `PyTrace_EXCEPTION`
  The value of the what parameter to a `Py_tracefunc` function when an exception has been raised. The callback function is called with this value for what when after any bytecode is processed after which the exception becomes set within the frame being executed. The effect of this is that as exception propagation causes the Python stack to unwind, the callback is called upon return to each frame as the exception propagates. Only trace functions receives these events; they are not needed by the profiler.

int `PyTrace_LINE`
  The value passed as the what parameter to a trace function (but not a profiling function) when a line-number event is being reported.

int `PyTrace_RETURN`
  The value for the what parameter to `Py_tracefunc` functions when a call is returning without propagating an exception.

int `PyTrace_C_CALL`
  The value for the what parameter to `Py_tracefunc` functions when a C function is about to be called.

int `PyTrace_C_EXCEPTION`
  The value for the what parameter to `Py_tracefunc` functions when a C function has thrown an exception.

int `PyTrace_C_RETURN`
  The value for the what parameter to `Py_tracefunc` functions when a C function has returned.

void `PyEval_SetProfile`( | Py_tracefunc func, PyObject *obj)

  Set the profiler function to func. The obj parameter is passed to the function as its first parameter, and may be any Python object, or `NULL`. If the profile function needs to maintain state, using a different value for obj for each thread provides a convenient and thread-safe place to store it. The profile function is called for all monitored events except the line-number events.

void `PyEval_SetTrace`( | Py_tracefunc func, PyObject *obj)

  Set the tracing function to func. This is similar to `PyEval_SetProfile()`, except the tracing function does receive line-number events.