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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.