py-spy

Show a live view of the functions that take the most execution time of a running process

$ py-spy top [[-p|--pid]] [pid]

$ py-spy top -- python [path/to/file.py]

$ py-spy record [[-o|--output]] [path/to/profile.svg] [[-p|--pid]] [pid]

$ py-spy dump [[-p|--pid]] [pid]

py-spy command [options]

record
    Records a profile of the specified Python process to a file.

dump
    Dumps the stack traces of the specified Python process to stdout.

top
    Displays a real-time view of the top Python functions being executed.

--pid pid
    The PID of the Python process to profile.

--name name
    The name of the Python program to profile.

--native
    Profile native extensions as well as Python code.
This requires debug symbols to be installed.

--rate rate
    Sampling rate (samples/sec). Defaults to 100.

--output filename
    Output file for the profile. Supports .svg (flamegraph), .json (speedscope), or text.

--duration seconds
    Duration to record profile for in seconds. Defaults to indefinitely.

--gil-only
    Only samples when the GIL is held.

py-spy is a sampling profiler for Python programs. It lets you visualize what your Python program is spending time on without modifying the program itself or restarting it. Py-spy is written in Rust for speed and doesn't have any Python dependencies making it safe to use on production Python code. It supports profiling any Python process including those running in Docker containers. Py-spy works by sampling the stack frames of the Python process at a regular interval (default is 100 times per second) and then aggregating these samples to produce a profile. This profile can be visualized in a variety of ways, including using tools like speedscope or flamegraph. Unlike traditional Python profilers (like cProfile) py-spy does not need to be imported into the target process and doesn't introduce any performance overhead as it works by directly reading memory using the operating system's debugging APIs.

py-spy requires sufficient permissions to read the memory of the target process.
This typically means running py-spy as root or with `CAP_SYS_PTRACE` capability.
Accuracy of profiling depends on the sampling rate and the duration of the profiling session.
The native profiling option requires debug symbols to be available for native extensions.

py-spy can be installed via pip: `pip install py-spy` or using cargo: `cargo install py-spy`.

Flame graphs are a common visualization of profiling data showing the call stack of a program over time. py-spy can generate flame graphs directly using the `--output` option with a `.svg` extension.

py-spy was developed to provide a low-overhead, non-invasive way to profile Python applications, especially in production environments.
It addresses the limitations of traditional Python profilers which can introduce significant performance overhead or require code modifications.
Written in Rust, it aims for efficiency and minimal impact on the profiled application.

perf(1), gdb(1), strace(1)