pystackflame 0.1.1

Generate flamecharts and error graphs from python stacktraces

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 rustworkx-based graphs
• Build weighted execution graphs from logs using rustworkx
• 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. This is useful to restrict the flamechart or graph output to only relevant code paths.

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.