Skip to main content

pystackflame

Generate flamecharts from Python stacktraces in logs

pystackflame is a command-line tool that parses Python logs for stack traces and turns them into flamecharts or weighed graphs for performance analysis, visualization, and debugging.


Features

  • Generate FlameGraph-compatible output
  • Pickle json graphs
  • Build weighted execution graphs from logs and saves them in json format.
  • Python 3.14+ support
  • Fast and lightweight CLI built with click
  • Developer-friendly with optional linting via ruff

Installation

We recommend using uv for fast dependency management:

uv sync -p 3.14
source .venv/bin/activate
pystackflame --help

Possible applications

Web Service Error Hotspots

Aggregate Python exceptions in your web server (e.g. Flask/FastAPI/Django) logs to quickly pinpoint which request-handling paths are failing most often without any need of restarting your application.

pystackflame flame /var/log/myapp/**/*.log -o web_errors.flame

Analysis of the historical data

Identify problematic places in the codebase that require the most attention.

pystackflame flame /var/log/all_logs_we_have/**/*.log -o errors.flame
./flamegraph.pl errors.flame > example.svg

Performance Regression Detection in CI

As part of your GitHub Actions or GitLab CI pipeline, run against the previous and current test logs to compare flamecharts—spot new slow-paths introduced by recent commits.

pystackflame flame old_tests.log -o baseline.flame
pystackflame flame new_tests.log -o current.flame

Visualize of diff the two SVGs or flame files to analyze regressions

Batch-Job Profiling

For long-running data-processing jobs (ETL, ML training, batch analytics), collect stacktraces on failure or periodically dump traces, then visualize the cumulative “hot” stacks to optimize slow stages.

pystackflame flame /logs/batch_job_*.log -o batch_profile.flame

Chaos-Engineering Fault Analysis

During fault-injection experiments, collect and compare flamecharts from healthy vs. faulted runs to understand how injected errors propagate.

pystackflame flame healthy.log -o healthy.flame
pystackflame flame chaos.log   -o chaos.flame

Advanced filtering

You can specify an option --trace-filter / -tf [PATH_PREFIX] to filter tracebacks to include only those paths that start with the given prefix and filter out the prefix out from the output. This is useful to restrict the flamechart or graph output to only relevant code paths with relevant names.

Additionally, you can specify multiple --exclude / -e [PATH_PREFIX] to exclude traces that starts from the given path prefix. Wildcard is supported as well.

Example

This command

pystackflame flame ~/test.log -tf '/opt/app/venv/lib64/python3.9/site-packages' 

Will produce the following flame data output

package;database;session.py;wrapper 2
package;apihelper.py;_make_request 2
package;apihelper.py;_check_result 2

And this command

pystackflame flame ~/test.log

Will give you this

/;opt;app;venv;lib64;python3.9;site-packages;package;database;session.py;wrapper 2
/;opt;app;venv;lib64;python3.9;site-packages;package;apihelper.py;_make_request 2
/;opt;app;venv;lib64;python3.9;site-packages;package;apihelper.py;_check_result 2

However, this command

pystackflame flame ~/test.log -tf '/opt/app/venv/lib64/python3.9/site-packages/package/apihelper.py' 

Will produce the following output

_make_request 2
_check_result 2

Usage

  • The filter must start with / (absolute path).
  • * can be used to match any folder (e.g., /var/log/app-logs/dates/*/application).
  • The filter must not end with /.

Result:

  • Only stack trace frames that match the filter will be added to the flamechart or graph.
  • Useful for narrowing down logs to project-specific code or a specific dependency tree.

Metadata

Release files for pystackflame 0.1.4

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pystackflame 0.1.4
File Size Uploaded Provenance Actions
pystackflame-0.1.4.tar.gz 7.0 kB Without provenance Details for pystackflame-0.1.4.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for pystackflame 0.1.4
File Interpreter ABI Platform Actions
pystackflame-0.1.4-py3-none-any.whl Python 3 none any Details for pystackflame-0.1.4-py3-none-any.whl

Total release size: 14.8 kB

Release files / pystackflame-0.1.4.tar.gz

Download URL pystackflame-0.1.4.tar.gz
Size 7.0 kB
Tags Source
SHA-256 checksum
How to use checksums
ba821f51feb137ef0c135066f101cc538d453ebb4a66e1ad0e2aea88bee73607
BLAKE2b-256 checksum
How to use checksums
7316b4dfa2124b2a346d7893a0f17e00484ebbd6bdac88a3faabd72d9fb422c6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.6.14

Release files / pystackflame-0.1.4-py3-none-any.whl

Download URL pystackflame-0.1.4-py3-none-any.whl
Size 7.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
d77f2e40bd1898b39da50ef82aeccb692791b56756388c4450f6586179f92e73
BLAKE2b-256 checksum
How to use checksums
83d0bdce0e7e567fa2e1d2fa9906c95ed74bf6045abd0fb8ed349ea9c492d7f7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.6.14

Security for pystackflame 0.1.4

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page