Flameprof

0.4 · active · verified Mon Apr 13

Flameprof is a Python library and command-line tool that generates interactive SVG flame graphs from `cProfile` statistics. It visualizes function call hierarchies and their CPU time consumption, offering a compact and understandable alternative to raw `cProfile` output or tools like `gprof2dot`. The current version is 0.4. Releases are sporadic, with major updates occurring infrequently.

Warnings

gotcha Flameprof is primarily a command-line utility. While it is a Python package, its main functionality is exposed via the `flameprof` executable after installation, not typically through direct Python `import` statements for generating flame graphs.
Fix: Always invoke `flameprof` from your terminal or shell scripts after generating a cProfile output file.
gotcha The input file for `flameprof` must be a statistics file generated by Python's `cProfile` module (e.g., created with `cProfile.run('my_func()', 'output.prof')` or `python -m cProfile -o output.prof myscript.py`). It does not natively support output from other profiling tools like `perf` or `py-spy` without prior conversion.
Fix: Ensure your profiling data is in the `cProfile` format. If you need to profile other sources, consider converting their output to a compatible format or using different flame graph generators.
gotcha Users have reported instances where `flameprof` can produce 'impossible stacks' or `ZeroDivisionError: float division by zero` when processing certain `cProfile` data, especially with unusual call patterns or highly optimized code.
Fix: If encountering these errors, try simplifying the profiled code or updating to the latest `flameprof` version. For critical debugging, consider alternative profiling visualization tools if the issue persists.

Install

pip install flameprof Install with pip

Imports

flameprof CLI
```
flameprof input.prof > output.svg
```
Flameprof is primarily used as a command-line tool to process cProfile output files, rather than through direct Python imports for its core functionality.

Quickstart

First, create a Python script (`my_app.py`) that you wish to profile. Use Python's built-in `cProfile` module to run your application and save the profiling data to a `.prof` file. Then, use the `flameprof` command-line tool to convert this `.prof` file into an interactive SVG flame graph. Open the generated SVG file in a web browser to view the visualization.

# my_app.py
import cProfile
import time

def func_a():
    time.sleep(0.1)

def func_b():
    time.sleep(0.05)
    func_a()

def main():
    for _ in range(3):
        func_b()
    func_a()

# Profile the application
profile_file = 'my_app.prof'
cProfile.run('main()', profile_file)

# To generate the flame graph, run in your terminal:
# flameprof my_app.prof > my_app_flamegraph.svg
# Then open my_app_flamegraph.svg in a web browser.

view raw JSON →