Skip to content
Back to top
View this page

# Tracing And Profiling

Standard Python tracing and profiling doesn’t work as expected when used with greenlet since stack and frame switching happens on the same Python thread. It is difficult to detect greenlet switching reliably with conventional methods, so to improve support for debugging, tracing and profiling greenlet based code there are new functions in the greenlet module, `gettrace` and `settrace`.

## Trace Callback Functions

Trace callback functions are installed using `settrace` and must have the signature `callback(event: str, args: Any)`.

Important

For compatibility it is very important to unpack `args` tuple only when `event` is one of those defined here, and not when `event` is potentially something else. This way API can be extended to new events similar to `sys.settrace()`.

The parameter event is a string naming what happened. The following events are defined:

`switch`

  In this case, `args` is a two-tuple `(origin, target)`.

  Called to handle a switch from `origin` to `target`.

  Note that callback is running in the context of the `target` greenlet and any exceptions will be passed as if `target.throw()` was used instead of a switch.

`throw`

  In this case, `args` is a two-tuple `(origin, target)`.

  Called to handle a throw from `origin` to `target`.

  Note that callback is running in the context of `target` greenlet and any exceptions will replace the original, as if `target.throw()` was used with the replacing exception.

For example:

    >>> import greenlet
    >>> def callback(event, args):
    ...     if event in ('switch', 'throw'):
    ...         origin, target = args
    ...         print("Transfer from %s to %s with %s"
    ...               % (origin, target, event))

    >>> class Origin(greenlet.greenlet):
    ...     def run(self):
    ...         print("In origin")
    ...         target.switch()
    ...         print("Returned to origin")
    ...         target.throw()
    ...     def __str__(self):
    ...        return "<origin>"

    >>> class Target(greenlet.greenlet):
    ...     def run(self):
    ...         origin.switch()
    ...     def __str__(self):
    ...        return "<target>"

    >>> old_trace = greenlet.settrace(callback)
    >>> origin = Origin()
    >>> target = Target()
    >>> _ = origin.switch()
    Transfer from <greenlet.greenlet object ...> to <origin> with switch
    In origin
    Transfer from <origin> to <target> with switch
    Transfer from <target> to <origin> with switch
    Returned to origin
    Transfer from <origin> to <target> with throw
    Transfer from <target> to <greenlet.greenlet object ...> with switch

Of course, when we’re done, it’s important to restore the previous state:

    >>> _ = greenlet.settrace(old_trace)