Metadata-Version: 2.4
Name: pystackflame
Version: 0.1.0
Summary: Generate flamecharts and error graphs from python stacktraces
Author: Alexander
License: MIT
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: POSIX :: Linux
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.14
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Software Development :: Debuggers
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: System :: Monitoring
Classifier: Topic :: System :: Logging
Classifier: Topic :: Utilities
Requires-Python: >=3.14
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.2.0
Requires-Dist: rustworkx>=0.16.0
Provides-Extra: dev
Requires-Dist: ruff==0.11.10; extra == "dev"
Dynamic: license-file

# 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](https://github.com/brendangregg/FlameGraph)-compatible output
- Pickle [rustworkx](https://github.com/Qiskit/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`](https://github.com/astral-sh/uv) for fast dependency management:

```bash
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.
```shell 
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.
```shell 
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.
```shell
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.
```shell
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.
```shell
pystackflame flame healthy.log -o healthy.flame
pystackflame flame chaos.log   -o chaos.flame
```
