Yappi

https://github.com/sumerc/yappi
Admin
Yappi is a fast, multithreaded, asyncio and gevent-aware tracing profiler for Python that supports...
Tokens:13,076
Snippets:156
Trust Score:9.6
License:MIT
Update:4 months ago
Show doc for...
Tokens:
Raw
### Install yappi with test dependencies

Source: https://github.com/sumerc/yappi/blob/master/CLAUDE.md

Install yappi in editable mode with all necessary test dependencies. This is a one-time setup step.

```bash
pip install -e ".[test"]
```

--------------------------------

### Simple CPU Profiling Example

Source: https://github.com/sumerc/yappi/blob/master/README.md

Profile a function's CPU time. Ensure 'cpu' clock type is set before starting the profiler.

```python
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()
```

--------------------------------

### Install Yappi from Source

Source: https://github.com/sumerc/yappi/blob/master/README.md

Install Yappi directly from its GitHub repository using pip. This is useful for installing the latest development version or if you need to modify the source.

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

--------------------------------

### Install Yappi with Test Dependencies

Source: https://github.com/sumerc/yappi/blob/master/CLAUDE.md

Installs the Yappi profiler in editable mode, including dependencies required for testing.

```bash
pip install -e ".[test]"
```

--------------------------------

### Basic Yappi Profiling Example

Source: https://github.com/sumerc/yappi/blob/master/doc/introduction.md

This snippet demonstrates how to profile a simple Python function using Yappi. It starts the profiler, calls a function, and then prints both function and thread statistics.

```python
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()
```

--------------------------------

### Install Yappi via PyPI

Source: https://github.com/sumerc/yappi/blob/master/README.md

Install Yappi using pip from the Python Package Index. This is the standard method for installing Python packages.

```bash
$
pip install yappi
```

--------------------------------

### run

Source: https://github.com/sumerc/yappi/blob/master/doc/api.md

Provides a context manager for profiling a block of code. It starts profiling upon entry and stops upon exit, accepting the same arguments as the start() function.

```APIDOC
## run(builtins=False, profile_threads=True, profile_greenlets=True)

### Description
Context manager for profiling a block of code. Starts profiling on entry and stops on exit. Accepts the same arguments as [`start()`](#startbuiltinsfalse-profile_threadstrue-profile_greenletstrue).

```python
with yappi.run():
    my_function()

yappi.get_func_stats().print_all()
```

**Note:** Do not nest `yappi.run()` contexts — the inner context will stop profiling when it exits, leaving the outer block unprofiled.

### Method
N/A (Context Manager)
```

--------------------------------

### start

Source: https://github.com/sumerc/yappi/blob/master/doc/api.md

Starts profiling all threads in the current interpreter instance. It can be called from any thread at any time and resumes profiling if stop() was previously called. Options include profiling built-in functions, all threads, and greenlets.

```APIDOC
## start(builtins=False, profile_threads=True, profile_greenlets=True)

### Description
Starts profiling all threads in the current interpreter instance. This function can be called from any thread at any time. Resumes profiling if stop() is called previously.

- `builtins`: enables profiling of builtin functions.
- `profile_threads`: enables profiling of all threads. If this flag is true, all current threads and the ones that are generated in the future will be profiled.
- `profile_greenlets`: enables profiling of multiple greenlets. This argument is only respected when context backend is 'greenlet' and ignored otherwise.

### Method
N/A (Function Call)

### Parameters
#### Arguments
- **builtins** (bool) - Optional - Enables profiling of builtin functions.
- **profile_threads** (bool) - Optional - Enables profiling of all threads.
- **profile_greenlets** (bool) - Optional - Enables profiling of multiple greenlets (only when context backend is 'greenlet').
```

--------------------------------

### Profile Gevent Application with Yappi

Source: https://github.com/sumerc/yappi/blob/master/README.md

Use this snippet to profile gevent applications. Ensure yappi and greenlet are installed. Set the context backend to 'greenlet' and clock type to 'wall' before starting the profiler.

```python
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()

```

--------------------------------

### Profile gevent application with Yappi

Source: https://github.com/sumerc/yappi/blob/master/doc/greenlet-profiling.md

Configure Yappi for greenlets, start profiling, run greenlets, stop profiling, and print function and greenlet statistics.

```python
import yappi
from gevent import Greenlet
import time

## Application logic

def burn_cpu(secs):
    t0 = time.process_time()
    elapsed = 0
    while (elapsed <= secs):
        for _ in range(1000):
            pass
        elapsed = time.process_time() - t0

class GreenletA(Greenlet):
    def _run(self):
        burn_cpu(0.1)

class GreenletB(Greenlet):
    def _run(self):
        burn_cpu(0.2)

# Running the profiler:

# 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()
```

--------------------------------

### Pyinstrument Output for Coroutine Profiling Example

Source: https://github.com/sumerc/yappi/blob/master/doc/coroutine-profiling.md

This output from Pyinstrument, a statistical profiler, also demonstrates difficulties in accurately measuring wall time for asynchronous operations due to its interval-based sampling.

```text
pyinstrument:
4.016 <module>  cprofile_asyncio.py:1
└─ 4.005 run  asyncio/runners.py:8
      [7 frames hidden]  asyncio, selectors
         2.003 select  selectors.py:451
         2.002 _run  asyncio/events.py:86
         └─ 2.002 foo  cprofile_asyncio.py:22
            ├─ 1.001 burn_io  cprofile_asyncio.py:18
            └─ 1.001 burn_cpu  cprofile_asyncio.py:5
```

--------------------------------

### Profile with CPU Clock Type

Source: https://github.com/sumerc/yappi/blob/master/doc/clock_types.md

This example demonstrates profiling a function using the default CPU clock type. Note that blocking functions like `time.sleep()` will show minimal CPU time.

```python
import time

import yappi


def my_func():
    time.sleep(4.0)


yappi.start()

my_func()

yappi.get_func_stats().print_all()
```

--------------------------------

### Profile with Wall Clock Type

Source: https://github.com/sumerc/yappi/blob/master/doc/clock_types.md

This example shows how to profile a function using the Wall clock type. This is useful for accurately measuring the time spent in blocking operations like `time.sleep()`.

```python
import time

import yappi


def my_func():
    time.sleep(4.0)


yappi.set_clock_type("wall")
yappi.start()

my_func()

yappi.get_func_stats().print_all()
```

--------------------------------

### Run code block with Yappi profiler

Source: https://github.com/sumerc/yappi/blob/master/doc/api.md

Use `yappi.run()` as a context manager to profile a block of code. Profiling starts on entry and stops on exit. Ensure not to nest `yappi.run()` contexts.

```python
with yappi.run():
    my_function()

yappi.get_func_stats().print_all()
```

--------------------------------

### Profile Simple Greenlet Application

Source: https://github.com/sumerc/yappi/blob/master/doc/greenlet-profiling.md

Demonstrates profiling a basic application with two greenlets. Configure Yappi for greenlets, start profiling, run greenlets, stop profiling, and print function and greenlet statistics.

```python
import yappi
from greenlet import greenlet
import time

## Application logic

def burn_cpu(secs):
    t0 = time.process_time()
    elapsed = 0
    while (elapsed <= secs):
        for _ in range(1000):
            pass
        elapsed = time.process_time() - t0

class GreenletA(greenlet):
    def run(self):
        burn_cpu(0.1)

class GreenletB(greenlet):
    def run(self):
        burn_cpu(0.2)

# Running the profiler:

# 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 Thread Statistics Output

Source: https://github.com/sumerc/yappi/blob/master/doc/introduction.md

This is an example output of Yappi's thread statistics, detailing thread name, ID, total time spent, and scheduling count.

```text
name           tid              ttot      scnt
_MainThread    6016             0.296402  1
```

--------------------------------

### Yappi Function Statistics Output

Source: https://github.com/sumerc/yappi/blob/master/doc/introduction.md

This is an example output of Yappi's function statistics, showing details like call count, total time, and average time spent in functions.

```text
Clock type: cpu
Ordered by: totaltime, desc

name                    ncall      tsub      ttot      tavg
deneme.py:35 a          1          0.296402  0.296402  0.296402
```

--------------------------------

### get()

Source: https://github.com/sumerc/yappi/blob/master/doc/api.md

Retrieves the current thread stats. This is a wrapper for `yappi.get_thread_stats()`.

```APIDOC
#### `get()`

This method retrieves the current thread stats.     

[`yappi.get_thread_stats()`](#get_thread_stats) is actually just a wrapper for this function.
```

--------------------------------

### Profile CPU-Intensive Function with CPU Clock

Source: https://github.com/sumerc/yappi/blob/master/doc/clock_types.md

This example profiles a function that performs a large number of iterations, demonstrating how CPU clock type accurately measures CPU-bound tasks.

```python
import yappi

import time


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

yappi.set_clock_type("cpu")
yappi.start()

my_func()

yappi.get_func_stats().print_all()
```

--------------------------------

### cProfile Output for Coroutine Profiling Example

Source: https://github.com/sumerc/yappi/blob/master/doc/coroutine-profiling.md

This output from cProfile shows the limitations in profiling asynchronous code. Notice the incorrect call counts and accumulated times for functions involving await operations.

```text
   ncalls  tottime  percall  cumtime  percall filename:lineno(function)
        4    0.000    0.000    0.000    0.000 cprofile_asyncio.py:14(burn_async_io)
        1    0.000    0.000    1.001    1.001 cprofile_asyncio.py:18(burn_io)
        3    0.000    0.000    2.002    0.667 cprofile_asyncio.py:22(foo)
        1    0.947    0.947    1.000    1.000 cprofile_asyncio.py:5(burn_cpu)
```

--------------------------------

### Yappi v1.2 Output for Coroutine Profiling Example

Source: https://github.com/sumerc/yappi/blob/master/doc/coroutine-profiling.md

This output from Yappi v1.2 shows corrected profiling data for coroutines, accurately reflecting the time spent in each function and correct call counts.

```text
profile_asyncio.py:25 foo             1      0.000044  4.004661  4.004661
profile_asyncio.py:17 burn_async_io   2      0.000041  2.003238  1.001619
profile_asyncio.py:21 burn_io         1      0.000019  1.001135  1.001135
profile_asyncio.py:8 burn_cpu         1      0.935974  1.000244  1.000244
```

--------------------------------

### Filter function stats by name using filter_callback

Source: https://github.com/sumerc/yappi/blob/master/doc/api.md

Retrieve function statistics and filter them using a callback function. This example filters for functions named 'foo'.

```python
stats = yappi.get_func_stats(
    filter_callback=lambda x: x.name == 'foo'
).print_all()
```

--------------------------------

### stop

Source: https://github.com/sumerc/yappi/blob/master/doc/api.md

Stops the profiler. The same profiling session might be resumed later by calling start().

```APIDOC
## stop()

### Description
Stop the profiler. Same profiling session might be resumed later by calling `start()`.

### Method
N/A (Function Call)
```

--------------------------------

### Example Application for Coroutine Profiling

Source: https://github.com/sumerc/yappi/blob/master/doc/coroutine-profiling.md

This Python code defines functions for CPU-bound, I/O-bound, and asynchronous I/O operations, and an async main function to orchestrate them. It serves as a test case for profiling different types of operations within an asynchronous context.

```python
def burn_cpu(secs):
    t0 = time.process_time()
    elapsed = 0
    while (elapsed <= secs):
        for _ in range(1000):
            pass
        elapsed = time.process_time() - t0


async def burn_async_io(secs):
    await asyncio.sleep(secs)

def burn_io(secs):
    time.sleep(secs)


async def foo():
    burn_cpu(1.0)
    await burn_async_io(1.0)
    burn_io(1.0)
    await burn_async_io(1.0)

asyncio.run(foo)
```

--------------------------------

### Profile Greenlets with Monkey Patched Threading

Source: https://github.com/sumerc/yappi/blob/master/doc/greenlet-profiling.md

Configure Yappi to profile greenlets when threading is monkey patched. This involves setting the context backend, clock type, and a custom context name callback to correctly identify thread names. Run the profiler, start and join threads, stop the profiler, and then print function and greenlet stats.

```python
from gevent import monkey
monkey.patch_all()

import yappi
import threading
import gevent
import time

## Application logic

def burn_cpu(secs):
    t0 = time.process_time()
    elapsed = 0
    while (elapsed <= secs):
        for _ in range(1000):
            pass
        elapsed = time.process_time() - t0

class ThreadA(threading.Thread):
    def run(self):
        burn_cpu(0.1)

class ThreadB(threading.Thread):
    def run(self):
        burn_cpu(0.2)

# Running the profiler:

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

# Step 2: Configure the system to capture thread names correctly
def _ctx_name_callback():
    curr_gl = gevent.getcurrent()
    if curr_gl is gevent.get_hub():
        return curr_gl.__class__.__name__
    # yappi._ctx_name_callback returns the name of the thread
    # class
    return yappi._ctx_name_callback()

yappi.set_context_name_callback(_ctx_name_callback)

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

a = ThreadA()
b = ThreadB()

a.start()
b.start()
a.join()
b.join()

yappi.stop()

# Step 4: View results

print("## Function stats:")
yappi.get_func_stats().print_all()

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

--------------------------------

### print_all(out=sys.stdout, limit=None)

Source: https://github.com/sumerc/yappi/blob/master/doc/api.md

Prints the current profile stats to a specified output stream, with an optional limit on the number of entries.

```APIDOC
#### `print_all(out=sys.stdout, limit=None)`

 This method prints the current profile stats to the file `out`.

`limit` limits the output to the first `limit` entries. When `None` (default), all entries are printed.
```

--------------------------------

### YFuncStat.print_all(out=sys.stdout, limit=None)

Source: https://github.com/sumerc/yappi/blob/master/doc/api.md

Prints the current profile stats to a specified output stream, with an optional limit.

```APIDOC
## print_all(out=sys.stdout, limit=None)

### Description
This method prints the current profile stats to `out`.

`limit` limits the output to the first `limit` entries. When `None` (default), all entries are printed. Useful when you only want to see the top N results after sorting.

### Request Example
```python
yappi.get_func_stats().sort("ttot").print_all(limit=20)
```
```

--------------------------------

### Run all yappi tests

Source: https://github.com/sumerc/yappi/blob/master/CLAUDE.md

Execute the entire test suite for yappi using the provided run script.

```bash
python run_tests.py
```

--------------------------------

### Build Yappi C Extension In-Place

Source: https://github.com/sumerc/yappi/blob/master/CLAUDE.md

Rebuilds only the C extension for faster iteration when working on C code. This command is typically used during active C code development.

```bash
python setup.py build_ext --inplace
```

--------------------------------

### Profile Asyncio Application

Source: https://github.com/sumerc/yappi/blob/master/README.md

Profile an asyncio application, ensuring coroutine wall-times are correctly captured. Set clock type to 'WALL' for accurate asyncio profiling.

```python
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()
```

--------------------------------

### YFuncStat.add(path, type='ystat')

Source: https://github.com/sumerc/yappi/blob/master/doc/api.md

Loads saved profile stats from a file. Currently only supports the 'ystat' format.

```APIDOC
## add(path, type="ystat")

### Description
This method loads the saved profile stats stored in file at `path`.

`type` indicates the type of the saved profile stats.

Currently, only loading from `"ystat"` format is possible. `"ystat"` is the current Yappi internal format.
```

--------------------------------

### set_context_backend(type='native_thread')

Source: https://github.com/sumerc/yappi/blob/master/doc/api.md

Sets the internal context backend for tracking execution context. The type must be either 'greenlet' or 'native_thread'.

```APIDOC
## set_context_backend(type='native_thread')

### Description
Sets the internal context backend used to track execution context. Type must be one of 'greenlet' or 'native_thread'. Default is `native_thread` and there is no need to call this function for initialization.

Setting the context backend will reset any callbacks configured via `set_context_id_callback` and `set_context_name_callback`.

### Parameters
* **type** (string) - The type of context backend to set. Must be 'greenlet' or 'native_thread'. Defaults to 'native_thread'.
```

--------------------------------

### Yappi Core Data Structures

Source: https://github.com/sumerc/yappi/blob/master/CLAUDE.md

Illustrates the hierarchical C-layer data structures used by Yappi for profiling, including contexts, recursion levels, and profile items.

```text
contexts (global htab)
  └── context_id → _ctx
        ├── cs         — call stack (_cstack), tracks the current call chain
        ├── rec_levels — htab tracking recursion depth per function
        ├── t0         — profiling start tick
        ├── sched_cnt  — how many times this thread was scheduled
        └── tags (htab)
              └── tag_id → pits (htab)
                    └── code_obj / m_ml → _pit (profile item)
                          ├── callcount, nonrecursive_callcount
                          ├── ttotal   — total time including children
                          ├── tsubtotal — self time (excluding children)
                          ├── children — linked list of _pit_children_info (callee timing per caller-callee pair)
                          └── coroutines — linked list of _coro (active coroutine frames + start tick)
```

--------------------------------

### Profile Multithreaded Application

Source: https://github.com/sumerc/yappi/blob/master/README.md

Profile a multithreaded application and retrieve per-thread profile information by filtering on ctx_id.

```python
import yappi
import time
import threading

_NTHREAD = 3


def _work(n):
    time.sleep(n * 0.1)


yappi.start()

threads = []
# generate _NTHREAD threads
for i in range(_NTHREAD):
    t = threading.Thread(target=_work, args=(i + 1, ))
    t.start()
    threads.append(t)
# wait all threads to finish
for t in threads:
    t.join()

yappi.stop()

# retrieve thread stats by their thread id (given by yappi)
threads = yappi.get_thread_stats()
for thread in threads:
    print(
        "Function stats for (%s) (%d)" % (thread.name, thread.id) 
    )  # it is the Thread.__class__.__name__
    yappi.get_func_stats(ctx_id=thread.id).print_all()
```

--------------------------------

### Print Top 20 Sorted Function Stats

Source: https://github.com/sumerc/yappi/blob/master/doc/api.md

Retrieves function statistics, sorts them by total time spent (ttot) in descending order, and prints the top 20 entries. Ensure yappi is imported.

```python
yappi.get_func_stats().sort("ttot").print_all(limit=20)
```

--------------------------------

### YFuncStat.debug_print()

Source: https://github.com/sumerc/yappi/blob/master/doc/api.md

Debug prints the current profile stats to stdout, showing callees and more detailed information than print_all().

```APIDOC
## debug_print()

### Description
This method _debug_ prints the current profile stats to stdout.

Debug print prints out callee functions and more detailed info than the [`print_all()`](#print_alloutsysstdout-limitnone) function call.
```

--------------------------------

### empty()

Source: https://github.com/sumerc/yappi/blob/master/doc/api.md

Returns a boolean indicating whether any stats are currently available.

```APIDOC
#### `empty()`

Returns a `bool` indicating whether we have any stats available or not.
```

--------------------------------

### Run a specific test module

Source: https://github.com/sumerc/yappi/blob/master/CLAUDE.md

Execute tests for a particular module within the yappi test suite.

```bash
python run_tests.py test_functionality
```

--------------------------------

### YFuncStat.save(path, type='ystat')

Source: https://github.com/sumerc/yappi/blob/master/doc/api.md

Saves the current profile stats to a file. Supports 'pstat' and 'callgrind' formats.

```APIDOC
## save(path, type="ystat")

### Description
This method saves the current profile stats to file at `path`.

`type` indicates the target type that the profile stats will be saved in.

Can be either
[`"pstat"`](http://docs.python.org/3.3/library/profile.html?highlight=pstat#pstats.Stats.print_stats) or
[`"callgrind"`](http://kcachegrind.sourceforge.net/html/CallgrindFormat.html).
```

--------------------------------

### YFuncStat.empty()

Source: https://github.com/sumerc/yappi/blob/master/doc/api.md

Checks if there are any profiling stats available.

```APIDOC
## empty()

### Description
Returns a boolean indicating whether we have any stats available or not.
```

--------------------------------

### Run a specific pytest test

Source: https://github.com/sumerc/yappi/blob/master/CLAUDE.md

Execute a single, specific test case using pytest, identified by its module, class, and test name.

```bash
python -m pytest tests/test_functionality.py::ClassName::test_name -v
```

--------------------------------

### is_running

Source: https://github.com/sumerc/yappi/blob/master/doc/api.md

Returns a boolean indicating whether the profiler is currently running.

```APIDOC
## is_running()

### Description
Returns a boolean indicating whether profiler is running or not.

### Method
N/A (Function Call)
```

--------------------------------

### Yappi Stat Collection Mapping

Source: https://github.com/sumerc/yappi/blob/master/CLAUDE.md

Maps C-side structs used in Yappi's profiling to their corresponding Python wrappers and collection types.

```text
C struct | Python wrapper | Collection
----------|---------------|------------
`_pit`   | `YFuncStat`   | `YFuncStats` 
`_ctx`   | `YThreadStat` | `YThreadStats` 
```

--------------------------------

### Filtering Yappi Stats with filter_callback

Source: https://github.com/sumerc/yappi/blob/master/doc/coroutine-profiling.md

This Python code demonstrates how to use Yappi's `filter_callback` to exclude framework internals from the profiling output, focusing on the application's own code.

```python
yappi.get_func_stats(
    filter_callback=lambda s: 'profile_asyncio' in s.module
).print_all()
```

--------------------------------

### set_ctx_id_callback(callback)

Source: https://github.com/sumerc/yappi/blob/master/doc/api.md

Sets a callback function that is called for every profile event to retrieve the current context ID.

```APIDOC
## set_ctx_id_callback(callback)

### Description
Sets a callback function that is called for every profile event to get the current context id of a running context. A `context` in Yappi terminology means a construct that has its own callstack.

**Note:** The context id callback can be called from the `threading.Thread` initialization code and thus can hold some related locks in `threading` library (e.x: _active_limbo_lock). So, it is not safe to use threading APIs like `threading.current_thread()` which can also use these locks and lead to deadlocks. However, it is safe to use `threading.local()` or global variables using your own locks.

If you use `set_context_id_callback` without also calling `set_context_name_callback`, context names will fall back to reading from `threading._active`, which may produce unhelpful names like `_DummyThread` or `Thread` (especially under gevent). Always pair it with a `set_context_name_callback` for meaningful names.

### Parameters
* **callback** (callable) - A simple callable with no arguments that returns an integer representing the context ID.
```

--------------------------------

### YFuncStat.get()

Source: https://github.com/sumerc/yappi/blob/master/doc/api.md

Retrieves the current profiling stats. This method is a wrapper for yappi.get_func_stats().

```APIDOC
## get()

### Description
This method retrieves the current profiling stats.

[`yappi.get_func_stats()`](#get_func_statstagnone-ctx_idnone-filter_callbacknone) is actually just a wrapper for this function.
```

--------------------------------

### Set Custom Tag Callback for Profiling

Source: https://github.com/sumerc/yappi/blob/master/doc/api.md

Implement a custom tag callback function to associate profiling events with specific tags, enabling granular data aggregation. This is particularly useful for profiling request/response cycles in web applications.

```python
_req_counter = 0
tlocal = threading.local()

def _worker_tag_cbk():
    global _req_counter

    if not hasattr(tlocal, '_request_id'):
        _req_counter += 1 # protect this with mutex
        tlocal._request_id = _req_counter
    
    return tlocal._request_id


yappi.set_tag_callback(_worker_tag_cbk)
yappi.start()
...
# code that starts a server serving request with different threads
...
yappi.stop()

# get per-request/response cycle profiling info
for i in range(_req_counter):
    req_stats = yappi.get_func_stats(filter={'tag': i})
    req_stats.print_all()
```

--------------------------------

### Filter Stats by Module

Source: https://github.com/sumerc/yappi/blob/master/README.md

Filter function statistics by module object using `yappi.module_matches`.

```python
import package_a
import yappi
import sys

def a():
    pass

def b():
    pass

yappi.start()
a()
b()
package_a.a()
yappi.stop()

# filter by module object
current_module = sys.modules[__name__]
stats = yappi.get_func_stats(
    filter_callback=lambda x: yappi.module_matches(x, [current_module])
)  # x is a yappi.YFuncStat object
stats.sort("name", "desc").print_all()
```

--------------------------------

### yappi.get_mem_usage()

Source: https://github.com/sumerc/yappi/blob/master/doc/api.md

Retrieves the internal memory usage of the Yappi profiler itself.

```APIDOC
## yappi.get_mem_usage()

### Description
Returns the internal memory usage of the profiler itself.

### Returns
* (int) - The memory usage in bytes.
```

--------------------------------

### sort(sort_type, sort_order="desc")

Source: https://github.com/sumerc/yappi/blob/master/doc/api.md

Sorts the current profile stats based on a specified type and order.

```APIDOC
#### `sort(sort_type, sort_order="desc")`

This method sorts the current profile stats.

`sort_type` must be either `"ttot"` or `"scnt"`

`sort_order` must be either `"desc"` or `"asc"`
```

--------------------------------

### Customize greenlet names in Yappi

Source: https://github.com/sumerc/yappi/blob/master/doc/greenlet-profiling.md

Set a custom callback for naming greenlets to provide more descriptive names than the default class name.

```python
yappi.set_context_backend("greenlet")
yappi.set_context_name_callback(lambda: f"worker-{id(greenlet.getcurrent())}")
```

--------------------------------

### Yappi Clock Type Indicator

Source: https://github.com/sumerc/yappi/blob/master/doc/introduction.md

This output line indicates that the profiling statistics were collected using the CPU clock, representing the actual CPU time consumed by functions.

```text
Clock type: cpu
```

--------------------------------

### YFuncStat.sort(sort_type, sort_order='desc')

Source: https://github.com/sumerc/yappi/blob/master/doc/api.md

Sorts the current profile stats by a specified type and order.

```APIDOC
## sort(sort_type, sort_order="desc")

### Description
This method sorts the current profile stats.

The `sort_type` must be one of the following:

- `ncall`
- `ttot`
- `tsub`
- `tavg`

`sort_order` must be either `"desc"` or `"asc"`
```

--------------------------------

### Filter Stats by Module Name

Source: https://github.com/sumerc/yappi/blob/master/README.md

Filter function statistics by module name string.

```python
import yappi

def a():
    pass

yappi.start()
a()
yappi.stop()

# filter by module name
stats = yappi.get_func_stats(filter_callback=lambda x: 'package_a' in x.module
                             ).print_all()
```

--------------------------------

### Yappi Sorting Order Indicator

Source: https://github.com/sumerc/yappi/blob/master/doc/introduction.md

This output line specifies the sorting criteria for the profiling statistics, indicating they are ordered by total time in descending order.

```text
Ordered by: totaltime, desc
```

--------------------------------

### convert2pstats(stats)

Source: https://github.com/sumerc/yappi/blob/master/doc/api.md

Converts Yappi's internal stat type to a pstats object for compatibility with Python's standard profiling tools.

```APIDOC
## convert2pstats(stats)

### Description
Converts the internal stat type of Yappi (as returned by `YFuncStat.get()`) to a [`pstats`](https://docs.python.org/3/library/profile.html#module-pstats) object.

### Parameters
* **stats** (YFuncStat) - The internal Yappi stat object to convert.
```

--------------------------------

### Filter Stats by Function

Source: https://github.com/sumerc/yappi/blob/master/README.md

Filter function statistics by function objects using `yappi.func_matches`.

```python
import yappi

def a():
    pass

def b():
    pass

yappi.start()
a()
b()
yappi.stop()

# filter by function object
stats = yappi.get_func_stats(
    filter_callback=lambda x: yappi.func_matches(x, [a, b])
).print_all()
```

--------------------------------

### Filter function stats by actual function objects

Source: https://github.com/sumerc/yappi/blob/master/doc/api.md

Use `yappi.func_matches` within a `filter_callback` to filter statistics based on a list of actual function objects. Note that this is not supported on loaded or saved profiles.

```python
def a():
    pass

def b():
    pass

... stats = yappi.get_func_stats(
    filter_callback=lambda x: yappi.func_matches(x, [a, b])
)
```

--------------------------------

### get_func_stats

Source: https://github.com/sumerc/yappi/blob/master/doc/api.md

Returns function statistics as a list of YFuncStat objects, merging entries for the same function across threads and tags. Optional filtering by tag, context ID, or a callback function is supported.

```APIDOC
## get_func_stats(tag=None, ctx_id=None, filter_callback=None)

### Description
Returns the function stats as a list of [`YFuncStat`](#yfuncstat) object. Internally, Yappi stores profiling data per-thread (context) and per-tag in C. `get_func_stats` enumerates all of this buffered data and **merges entries that belong to the same function** (matched by `full_name`) into a single `YFuncStat` object — aggregating `ncall`, `ttot`, and `tsub` across all threads and tags. This means each unique function appears **exactly once** in the returned list, regardless of how many threads called it.

If you need per-thread or per-tag breakdowns, pass `ctx_id` or `tag` to restrict the enumeration before merging. Otherwise, data from all threads and tags will be combined.

If you really would like to enumerate buffered stats in raw (one entry per function per thread per tag), you can use an undocumented function: `_yappi.enum_func_stats(enum_callback, filter_dict)`. You can see the usage in `get_func_stats` function.

**Note:** Filtering `tag` and `ctx_id` are very fast compared to using `filter_callback` since the filtering is completely done on the C extension with an internal hash table.

- `tag`: retrieves the `YFuncStat` objects having the same `tag` as specified.
- `ctx_id`: retrieves the `YFuncStat` objects having the same `ctx_id` as specified.
- `filter_callback`: is a callback which takes a `YFuncStat` object as an argument and returns a boolean value to indicate to include or exclude it. As the object is directly passed to the `filter_callback` you can easily filter on any attribute that `YFuncStat` has.

**Note:** The `filter` dict is deprecated. Please do not use it anymore. We still support that for backward compatability but it is not recommended anymore.

An example demonstrating how `filter_callback` can be used to filter on a function name having `foo`:

```python
stats = yappi.get_func_stats(
    filter_callback=lambda x: x.name == 'foo'
).print_all()
```

There are handy functions that can be used with `filter_callback` to match multiple functions or modules easily. See [func_matches](#func_matchesstat-funcs) and [module_matches](#module_matchesstat-modules).

### Method
N/A (Function Call)

### Parameters
#### Arguments
- **tag** (any) - Optional - Retrieves `YFuncStat` objects with the specified tag.
- **ctx_id** (any) - Optional - Retrieves `YFuncStat` objects with the specified context ID.
- **filter_callback** (callable) - Optional - A callback function that takes a `YFuncStat` object and returns `True` to include it, `False` otherwise.
```

--------------------------------

### clear()

Source: https://github.com/sumerc/yappi/blob/master/doc/api.md

Clears the retrieved stats for the current object. Note that `yappi.clear_stats()` must be called to clear session stats.

```APIDOC
#### `clear()`

Clears the retrieved stats. 

---
**Note:**

This method only clears the current object. You need to explicitly call [`yappi.clear_stats()`](#clear_stats) to clear the current profile session stats.

---
```

--------------------------------

### set_clock_type

Source: https://github.com/sumerc/yappi/blob/master/doc/api.md

Sets the underlying clock type to either "wall" or "cpu". Refer to Clock Types documentation for more details.

```APIDOC
## set_clock_type(type)

### Description
Sets the underlying clock type. `type` must be one of `"wall"` or `"cpu"`.
Read [Clock Types](./clock_types.md) for more information.

### Method
N/A (Function Call)

### Parameters
#### Arguments
- **type** (string) - Required - Must be either `"wall"` or `"cpu"`.
```

--------------------------------

### YFuncStat.strip_dirs()

Source: https://github.com/sumerc/yappi/blob/master/doc/api.md

Strips directory information from the profiling results, affecting child function stats as well.

```APIDOC
## strip_dirs()

### Description
Strip the directory information from the results. Affects the child function stats too.
```

--------------------------------

### get_greenlet_stats

Source: https://github.com/sumerc/yappi/blob/master/doc/api.md

Returns the greenlet statistics as a YGreenletStats object.

```APIDOC
## get_greenlet_stats()

### Description
Returns the greenlet stats as a [`YGreenletStats`](#ygreenletstats) object.

### Method
N/A (Function Call)
```

--------------------------------

### module_matches(stat, modules)

Source: https://github.com/sumerc/yappi/blob/master/doc/api.md

Checks if a given YStat object belongs to any of the specified modules. Useful for filtering statistics based on module origin.

```APIDOC
## module_matches(stat, modules)

### Description
Returns `True` if the `stat`(`YStat`) object is in a given list of `modules`(`ModuleType`) list. An example usage is when filtering stats based on actual module objects.

**Note:** Once a profile session is saved or loaded from a file, you cannot use `func_matches` on the items as the mapping between the stats and the functions are not serialized.

### Parameters
* **stat** (YStat) - The stat object to check.
* **modules** (list[ModuleType]) - A list of modules to check against.
```

--------------------------------

### YGreenletStats Attributes

Source: https://github.com/sumerc/yappi/blob/master/doc/api.md

Describes the attributes available for a YGreenletStats object, which represents statistics for a greenlet.

```APIDOC
## `YGreenletStats`

`YGreenletStats` object has following attributes:

| Attribute   	| Description                                                                                    	|
|-------------	|------------------------------------------------------------------------------------------------	|
| name        	| class name of the current greenlet                                                             	|
| id          	| a unique id given by Yappi (ctx_id)                                                            	|
| ttot        	| total time spent in the thread                                                                 	|
| sched_count 	| number of times this thread is scheduled.                                                      	|
```

--------------------------------

### Filter Stats by Function Name

Source: https://github.com/sumerc/yappi/blob/master/README.md

Filter function statistics by function name string.

```python
import yappi

def a():
    pass

yappi.start()
a()
yappi.stop()

# filter by function name
stats = yappi.get_func_stats(filter_callback=lambda x: 'a' in x.name
                             ).print_all()
```

--------------------------------

### YFuncStat.clear()

Source: https://github.com/sumerc/yappi/blob/master/doc/api.md

Clears the stats for the current object. Note: yappi.clear_stats() is needed to clear session stats.

```APIDOC
## clear()

### Description
Clears the stats.

**Note:**

This method only clears the current object. You need to explicitly call [`yappi.clear_stats()`](#clear_stats) to clear the current profile session stats.
```

--------------------------------

### set_tag_callback(callback)

Source: https://github.com/sumerc/yappi/blob/master/doc/api.md

Sets a callback function to retrieve the current tag ID for a running function, allowing for custom data aggregation.

```APIDOC
## set_tag_callback(callback)

### Description
Sets a callback function that is called for every profile event to get the current tag id of a running function. In Yappi, every profiled function is associated with a tag. By default, this tag is same for all stats collected. You can change this behavior and aggregate different function stat data in different tags.

A recent use case for this functionality is aggregating of single request/response cycle in an ASGI application via `contextvar` module. See [here](https://github.com/sumerc/yappi/issues/21) for details. It can also be used for profiling multithreaded WSGI applications, too.

### Parameters
* **callback** (callable) - A simple callable with no arguments that returns an integer representing the tag ID.
```

--------------------------------

### get_thread_stats

Source: https://github.com/sumerc/yappi/blob/master/doc/api.md

Returns the thread statistics as a YThreadStat object.

```APIDOC
## get_thread_stats()

### Description
Returns the thread stats as a [`YThreadStat`](#ythreadstat) object.

### Method
N/A (Function Call)
```

--------------------------------

### get_clock_type

Source: https://github.com/sumerc/yappi/blob/master/doc/api.md

Returns information about the underlying clock type Yappi uses for timing measurements. Refer to Clock Types documentation for more details.

```APIDOC
## get_clock_type()

### Description
Returns information about the underlying clock type Yappi should use to measure timing. Read [Clock Types](./clock_types.md) for more information.

### Method
N/A (Function Call)
```

--------------------------------

### YThreadStat Attributes

Source: https://github.com/sumerc/yappi/blob/master/doc/api.md

Describes the attributes available for a YThreadStat object, which represents statistics for a thread.

```APIDOC
## `YThreadStat`

`YThreadStat` object has following attributes:

| Attribute   	| Description                                                                                    	|
|-------------	|------------------------------------------------------------------------------------------------	|
| name        	| class name of the current thread object which is derived from the `threading.Thread`<br> class 	|
| id          	| a unique id given by Yappi (ctx_id)                                                            	|
| tid         	| the real OS thread id                                                                          	|
| ttot        	| total time spent in the thread                                                                 	|
| sched_count 	| number of times this thread is scheduled.                                                      	|
```

--------------------------------

### clear_stats

Source: https://github.com/sumerc/yappi/blob/master/doc/api.md

Clears the profiler results. All results remain in memory unless the application exits or clear_stats() is explicitly called.

```APIDOC
## clear_stats()

### Description
Clears the profiler results. All results stay in memory unless application (all threads including the main thread) exits or `clear_stats()` is explicitly called.

### Method
N/A (Function Call)
```

--------------------------------

### func_matches

Source: https://github.com/sumerc/yappi/blob/master/doc/api.md

Checks if a YStat object is present in a given list of callable functions. Useful for filtering stats based on actual function objects.

```APIDOC
## func_matches(stat, funcs)

### Description
This function returns `True` if the `stat`(`YStat`) object is in a given list of `funcs`(`callable`) list. An example usage is when filtering stats based on actual function objects:

```python
def a():
    pass

def b():
    pass

... # Assuming 'stats' is a result from get_func_stats
stats = yappi.get_func_stats(
    filter_callback=lambda x: yappi.func_matches(x, [a, b])
)
```

**Note:** Once a profile session is saved or loaded from a file, you cannot use `func_matches` on the items as the mapping between the stats and the functions are not serialized.

### Method
N/A (Function Call)

### Parameters
#### Arguments
- **stat** (YStat) - Required - The YStat object to check.
- **funcs** (list of callable) - Required - A list of function objects to match against.
```
Tokens:
Raw