Yappi Documentation

Unlike deterministic profilers (like cProfile) or statistical profilers (like pyinstrument), Yappi (since v1.2) correctly handles coroutine context switches.

In standard profilers, when a coroutine yields (e.g., during an await), the profiler treats it as a function exit. This leads to two major inaccuracies:

1. Incorrect Call Counts: Every yield increments the call count as if the function exited.
2. Incorrect Wall Time: The time spent while the coroutine is in a yield state is not accumulated into the cumtime (cumulative time).

Yappi differentiates between a yield and a real function exit. When using clock_type='wall', Yappi accumulates the time spent during await states and maintains an accurate call count for the coroutine.

Yappi supports coroutine profiling, allowing you to see correct wall-time and call counts for coroutines, including time spent in context switches. Use yappi.set_clock_type("WALL") and wrap your asyncio.run() calls within a with yappi.run(): block.

import asyncio
import yappi

async def foo():
    await asyncio.sleep(1.0)
    await baz()
    await asyncio.sleep(0.5)

async def bar():
    await asyncio.sleep(2.0)

async def baz():
    await asyncio.sleep(1.0)

yappi.set_clock_type("WALL")
with yappi.run():
    asyncio.run(foo())
    asyncio.run(bar())
yappi.get_func_stats().print_all()

You can install Yappi using PyPI or directly from the GitHub source.

Via PyPI:

$ pip install yappi

From source:

$ pip install git+https://github.com/sumerc/yappi#egg=yappi

To profile greenlet-based applications, set the context backend to greenlet using yappi.set_context_backend("greenlet"). It is recommended to use yappi.start(builtins=True) to ensure comprehensive coverage.

import yappi
from greenlet import greenlet
import time

class GreenletA(greenlet):
    def run(self):
        time.sleep(1)

yappi.set_context_backend("greenlet")
yappi.set_clock_type("wall")

yappi.start(builtins=True)
a = GreenletA()
a.switch()
yappi.stop()

yappi.get_func_stats().print_all()

To profile applications using the greenlet library, you must configure Yappi's context backend to greenlet and set the clock type (e.g., cpu). After starting the profiler, you can retrieve and print function statistics using yappi.get_func_stats() and greenlet-specific statistics using yappi.get_greenlet_stats().

import yappi
from greenlet import greenlet
import time

# ... application logic ...

# Step 1: Configure the profiler to work with greenlets
yappi.set_context_backend("greenlet")
yappi.set_clock_type("cpu")

# Step 2: Run the profiler and stop it
yappi.start()

a = GreenletA()
b = GreenletB()

a.switch()
b.switch()

yappi.stop()

# Step 3: View results
print("## Function stats:")
yappi.get_func_stats().print_all()

print("\n## Greenlet stats:")
yappi.get_greenlet_stats().print_all()

Yappi supports profiling gevent applications by setting the context backend to greenlet. This allows you to capture statistics for greenlets managed by the gevent event loop. Note that functions running in a gevent ThreadPool cannot be tracked by Yappi.

import yappi
from gevent import Greenlet
import time

# ... application logic ...

# Step 1: Configure the profiler to work with greenlets
yappi.set_context_backend("greenlet")
yappi.set_clock_type("cpu")

# Step 2: Run the profiler and stop it
yappi.start()

a = GreenletA()
b = GreenletB()

a.start()
b.start()
a.get()
b.get()

yappi.stop()

# Step 3: View results
print("## Function stats:")
yappi.get_func_stats().print_all()

print("\n## Greenlet stats:")
yappi.get_greenlet_stats().print_all()

To profile a Python application with Yappi, follow these three steps:

1. Call yappi.start() to begin profiling.
2. Execute the code you wish to profile.
3. Retrieve and print statistics using yappi.get_func_stats().print_all() for function-level data and yappi.get_thread_stats().print_all() for thread-level data.

Note that the output will indicate the Clock type (e.g., cpu) and the Ordered by criteria used for the report.

import yappi


def a():
    for i in range(10000000): pass

yappi.start()

a()

yappi.get_func_stats().print_all()
yappi.get_thread_stats().print_all()

The following example demonstrates the difference between cpu and wall clock types when profiling a function that calls time.sleep().

When using the default cpu clock, time.sleep() will show negligible timing because the CPU is not actively processing instructions for that thread. When using wall clock, the full duration of the sleep is captured in ttot (total time).

import time
import yappi

def my_func():
    time.sleep(4.0)

# Example 1: CPU Clock (Default)
# Results will show near-zero time for the sleep call
yappi.set_clock_type("cpu")
yappi.start()
my_func()
yappi.get_func_stats().print_all()

# Example 2: Wall Clock
# Results will show ~4.0 seconds for the sleep call
yappi.set_clock_type("wall")
yappi.start()
my_func()
yappi.get_func_stats().print_all()

To perform a simple profile, use yappi.set_clock_type() to choose between cpu or wall time, then call yappi.start() and yappi.stop(). You can retrieve function statistics using yappi.get_func_stats() and thread statistics using yappi.get_thread_stats().

Note: yappi.set_clock_type("cpu") measures actual CPU time, while yappi.set_clock_type("wall") measures elapsed real time.

import yappi

def a():
    for _ in range(10000000):  # do something CPU heavy
        pass

yappi.set_clock_type("cpu") # Use set_clock_type("wall") for wall time
yappi.start()
a()

yappi.get_func_stats().print_all()
yappi.get_thread_stats().print_all()