| name | tune-buckets |
| description | Change the Prometheus histogram bucket boundaries for request_duration_seconds safely. Use when asked to add, remove, or retune latency buckets in prometheus.go. Guides the edit, explains the downstream blast radius (dashboards/alerts/SLOs), and verifies the result end-to-end. |
tune-buckets
The histogram buckets for request_duration_seconds are defined in one place — the Buckets slice inside registerMetrics in prometheus.go:
Buckets: []float64{0.1, 0.2, 0.3, 0.5, 0.75, 1, 1.5, 2, 3, 5},
These boundaries have been retuned across several PRs (see git history: "Update prom buckets", "remove 10, 15, 20 from bucket", "remove 7 from bucket"). Treat every change as significant — not cosmetic.
Why this is delicate
Buckets are cumulative (le = "less than or equal to") and Prometheus auto-appends +Inf. Consumers of this library build latency dashboards, histogram_quantile() queries, and alert thresholds against these exact boundaries. Changing them:
- Breaks historical continuity — a removed bucket leaves gaps in old time series; quantile estimates shift.
- Can silently degrade alerts — an SLO alert keyed on
le="7" goes dead if you remove the 7 bucket.
- Affects every consumer on upgrade, since this is a published module.
So the bar for a change is: it must be intentional, the values must stay strictly ascending, and the result must be verified.
Steps
-
Confirm the requested boundaries. Get the exact target slice from the user. If they only say "add X" / "remove Y", restate the full resulting slice back to them before editing.
-
Edit only the Buckets slice in registerMetrics (prometheus.go). Keep values strictly ascending; do not add +Inf (Prometheus adds it). Do not touch the metric name, Help, or label set unless asked.
-
Verify end-to-end with the verify-metrics skill. Confirm the scraped le= boundaries in /metrics exactly match the new slice (plus +Inf).
-
Flag the blast radius in your summary. Explicitly list which boundaries were added/removed so the reviewer knows what downstream dashboards/alerts to check. If a boundary was removed, call it out as a potentially breaking change for consumers.
Release note
A bucket change is meaningful to consumers. When it ships, it warrants a new version tag (see the release workflow) and a one-line changelog entry describing the added/removed boundaries.
