Metadata-Version: 2.4
Name: toil-radar
Version: 0.2.0
Summary: Detect, visualize, and reduce DevOps toil
Author-email: Amrut Pagidipally <amrut.pagidipally@gmail.com>
Project-URL: Homepage, https://github.com/amrutp24/toil-radar
Project-URL: Repository, https://github.com/amrutp24/toil-radar
Project-URL: Issues, https://github.com/amrutp24/toil-radar/issues
Keywords: devops,sre,toil,automation,cli,productivity
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dashboard
Requires-Dist: streamlit>=1.29.0; extra == "dashboard"
Requires-Dist: pandas>=2.0.0; extra == "dashboard"
Requires-Dist: plotly>=5.0.0; extra == "dashboard"
Provides-Extra: dev
Requires-Dist: pytest>=6.0; extra == "dev"
Requires-Dist: pytest-cov>=2.0; extra == "dev"
Dynamic: license-file

# Toil Radar

📡 **Detect, quantify, and reduce SRE/DevOps toil** — from signals your team already produces.

Toil is manual, repetitive, automatable operational work. The SRE handbook says to keep it under 50% of engineering time — but almost nobody measures it. Toil Radar estimates it from **structural signals** in git history and GitHub Actions, not keyword guessing, and tells you what to automate first.

## What it detects

**From git history (works offline):**

| Signal | What it means |
|---|---|
| `revert` | Reverts and rollbacks — bad changes reached mainline |
| `hotfix_merge` | Merges from hotfix/emergency branches |
| `quick_fix` | Same author re-touching the same file within 2 hours *with a corrective message* — fix-the-fix churn, not normal iteration |

Out-of-hours work (nights/weekends) doesn't create noise as its own signal — it **amplifies** the weight of real events, because a Saturday-night rollback costs more than a Tuesday-morning one.

**From GitHub Actions (via `gh`, optional):**

| Signal | What it means |
|---|---|
| `ci_rerun` | Workflow runs with `run_attempt > 1` — someone babysat flaky CI |
| `manual_dispatch` | `workflow_dispatch` runs — someone pushed a button that could be automated |

Every event gets an estimated cost in minutes. Rescans never double-count — events are deduplicated by commit hash / run id.

## Install

```bash
pip install toil-radar               # CLI only, zero dependencies
pip install "toil-radar[dashboard]"  # + Streamlit dashboard
```

## Usage

```bash
# Scan a repository (add --no-github to skip the gh API)
toil-radar scan /path/to/repo
toil-radar scan . --days 60

# Report: estimated hours, trend, hotspots, automation candidates
toil-radar summary
toil-radar summary --repo /path/to/repo --days 90

# Web dashboard
toil-dashboard
```

You can scan multiple repos into the same database — `summary` aggregates across all of them, or filter with `--repo`.

## Example output

```
Toil Radar - last 120 days - all repos
============================================================
Estimated toil: 6.2h (~1% of one engineer's time)   trend vs prior 120d: up 24%
Out-of-hours events: 13 (nights/weekends)

signal                        events  est. hours
------------------------------------------------
rapid follow-up fixes             17         5.9
CI re-runs                         1         0.3

Churn hotspots (same file touched in many commits):
  pyproject.toml  (10 commits)
  setup.py  (4 commits)

Top automation candidates:
1. rapid follow-up fixes: 17 events, ~5.9h
   Fix-the-fix churn means feedback arrives too late - add the missing
   linter, type check, or test that would catch these pre-push.
   e.g. "fix: explicitly include only toil_radar package in build" (2026-04-09)
2. CI re-runs: 1 events, ~0.3h
   Re-run workflows usually mean flaky tests or flaky infra - quarantine
   the flakiest jobs and fix them; every re-run is babysitting.
   e.g. "Publish to PyPI re-run (attempt 3)" (2026-03-30)
```

(That's real output from scanning this repo. The packaging churn was, in fact, toil.)

## Why structural signals instead of keywords?

Grepping commit messages for "fix" or "deploy" flags most normal development work and makes the numbers meaningless. Structural signals — an actual `Revert "..."` commit, a merge from a `hotfix/*` branch, the same file patched twice in 30 minutes, a CI run re-attempted three times — are things that *only* happen when somebody was doing operational cleanup. Low noise, defensible numbers.

## How the cost estimate works

Each signal type has a conservative per-event weight (revert 45 min, hotfix merge 60 min, quick fix 15 min, CI re-run 10 min per extra attempt, manual dispatch 10 min), multiplied ×1.5 out of hours. See `WEIGHTS` in [`toil_radar/git_signals.py`](toil_radar/git_signals.py). The point isn't per-minute accuracy — it's a consistent metric you can trend over time and use to rank what to automate first.

## Development

```bash
git clone https://github.com/amrutp24/toil-radar
cd toil-radar
pip install -e ".[dashboard,dev]"
pytest
```

## Roadmap

- PagerDuty / Opsgenie ingestion (repeated alerts = the strongest toil signal)
- Deploy→fix→deploy loop detection
- Per-team / per-author views
- Export to Prometheus metrics for long-term trending

## License

MIT — see [LICENSE](LICENSE)
