Skip to content

Latest commit

 

History

History
255 lines (193 loc) · 6.96 KB

File metadata and controls

255 lines (193 loc) · 6.96 KB

Getting Started with Burnless

Burnless is an open-source SRE platform that brings reliability engineering under version control. Instead of SLOs living in a Datadog dashboard and runbooks rotting in Confluence, everything lives in a single sre.yaml file — reviewed via pull requests, validated in CI, and eventually enforced automatically.

Phase 1 (available now): Track the manual toil your team absorbs every week, convert it to dollar cost, and produce reports that give managers the data to justify automation investment.

Phase 2 (in development): A burn rate agent watches Prometheus continuously and triggers remediation runbooks automatically — scaling replicas, rolling back deploys — before a human alert even fires.


1. Install

Homebrew (macOS/Linux):

brew install --cask Custos-com/tap/burnless

curl one-liner:

curl -fsSL https://raw.githubusercontent.com/Custos-com/Burnless/main/install.sh | sh

Go install:

go install github.com/Custos-com/Burnless/cmd/burnless@latest

Verify your install:

burnless version
burnless --help

2. Create your first sre.yaml

Run the interactive wizard:

burnless init

You'll be prompted for six things:

  Let's create your sre.yaml

? Service name: payments-api
? Team: platform-engineering
? SLO availability target %: 99.9
? SLO window: 30d
? Prometheus metric name: http_requests_total
? Slack channel for alerts: #sre-incidents
? On-call provider: pagerduty

This generates a complete sre.yaml. Here's what each section means:

service: payments-api
team: platform-engineering

# SLOs — what "good" looks like for this service.
# 99.9% availability over 30 days = ~43 minutes of allowed downtime per month.
slos:
  - name: availability
    target: 99.9
    window: 30d
    indicator:
      metric: http_requests_total
      good_filter: status!~"5.."

# Error budget alerts — when to fire and what to do.
# 14.4x burn rate = you will exhaust your monthly error budget in 2 days. Critical.
# 6x burn rate = you will exhaust it in 5 days. Warning.
error_budget:
  burn_rate_alerts:
    - severity: critical
      rate: 14.4
      window: 1h
      remediate: scale-up
    - severity: warning
      rate: 6
      window: 6h
      remediate: restart-pods

# Runbooks — what to do when an alert fires.
# auto: agent executes immediately. semi-auto: agent asks for Slack approval first.
runbooks:
  scale-up:
    mode: auto
    steps:
      - kubectl scale deploy/payments-api --replicas=+2
  restart-pods:
    mode: semi-auto
    steps:
      - kubectl rollout restart deploy/payments-api

oncall:
  provider: pagerduty
  escalation_minutes: 10
  notify_slack: '#sre-incidents'

dashboards:
  provider: grafana
  auto_generate: true

3. Validate it

burnless validate

Success:

✓ sre.yaml is valid
  service: payments-api
  1 SLO(s) defined
  2 burn rate alert(s) configured
  2 runbook(s) defined

To see what a failure looks like, set target: 150 in your sre.yaml and run validate again:

✗ sre.yaml is invalid
  slo[0] target must be between 0 and 100, got 150.00

Fix it and validate again. Use this in CIburnless validate exits 1 on failure, so it blocks merges with broken configs:

# .github/workflows/ci.yml
- run: burnless validate

4. Preview what apply will do

burnless diff
Would create:
  SLO: availability  target=99.9%  window=30d
  Alert: critical @ 14.4x burn rate -> scale-up
  Alert: warning  @ 6.0x burn rate  -> restart-pods
  Runbook: scale-up (auto, 1 step)
  Runbook: restart-pods (semi-auto, 1 step)

Nothing is deployed yet. Run 'burnless apply' to deploy.

burnless diff with no arguments previews what apply would create. Nothing is deployed — it is a dry run.


5. Check your config summary

burnless status
  Service:  payments-api
  Team:     platform-engineering

  SLOs configured:
  -----------------------------------------------------
  availability         target 99.9%   window 30d

  Error budget alerts:
  -----------------------------------------------------
  critical   14.4x burn rate   window 1h     -> scale-up
  warning     6.0x burn rate   window 6h     -> restart-pods

  Runbooks:
  -----------------------------------------------------
  scale-up       mode: auto       1 step(s)
  restart-pods   mode: semi-auto  1 step(s)

  On-call:   pagerduty  (escalation: 10 min)
  Dashboard: grafana    (auto-generate: true)

  Run 'burnless apply' to deploy this config.

6. Track your first toil event

Toil is manual, repetitive work that interrupts your week and could be automated. Log it as it happens:

burnless toil log --service payments-api --task manual-rollback --duration 45m --automatable
burnless toil log --service payments-api --task restart-pods --duration 20m --automatable
burnless toil log --service payments-api --task update-config --duration 30m

Flags:

  • --service — which service caused the toil
  • --task — short name for the task
  • --duration — how long it took (e.g. 45m, 2h)
  • --automatable — flag if this could be automated (used for priority scoring)

7. Generate your first report

burnless toil report --month 2026-06
Toil Report — June 2026
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Total toil hours:    4h 35m
Estimated cost:      $110.58
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Top tasks by automation priority:

  HIGH  manual-rollback    3x   2h 15m   $54.37
  HIGH  restart-pods       2x   40m      $16.10
  MED   update-config      1x   30m      $12.10

What "estimated cost" means: Burnless uses a $180,000/year fully-loaded SRE salary as the basis. Each hour of toil = ~$90. This gives your manager a concrete number, not just hours.

What HIGH/MED/LOW means: Tasks flagged --automatable score higher. Tasks that recur frequently score higher. Use this table in your next 1:1 — it makes the case for automation investment without needing to build a spreadsheet.


8. Export for your manager

burnless toil export --output june-toil.csv

Opens cleanly in Excel or Google Sheets. Share it directly with your manager or attach it to your quarterly review.


What's next

  • Add sre.yaml to your Git repo — treat it like infrastructure code, review changes via PRs
  • Add burnless validate to your CI/CD pipeline — catch broken configs before they merge
  • Coming soon: burnless apply — deploy your SLO config to Prometheus and Grafana automatically
  • Coming soon: burn rate agent — watches Prometheus every 60 seconds and triggers your runbooks before a human alert fires

Links: