GillMacedo/seriesdiff

A Claude Code skill and Go CLI for backend developers and SREs who change instrumented code and want to know, before merging, whether the change breaks Prometheus alerts and Grafana dashboards or blows up metric cardinality. It compares two /metrics scrapes, one from the base branch and one from your change, and lists removed or renamed metrics, type changes, removed labels, changed histogram buckets, label values that look like IDs, lost series and series growth. With --refs it names the alert rules and dashboard lines that use each changed metric.
Renaming a metric, dropping a label or switching a route label from the template to the raw path usually pass code review and CI, because tests rarely check metric names and labels. The first sign is an alert that silently stops firing or a Prometheus server running out of memory. seriesdiff reads the scrape files, so it works with any exporter or client library, and it refuses an empty, garbled or cut-off scrape instead of calling it clean.
## What you can ask Claude
"Does my branch rename or remove any Prometheus metrics our alerts use?"
"Will this change add high-cardinality labels to our metrics?"
"Compare /metrics from main and from my branch and tell me what breaks."
"We upgraded nodeexporter. Which of our dashboards will lose data?"
## Install
As a Claude Code plugin:
claude plugin marketplace add GillMacedo/seriesdiff
claude plugin install seriesdiff@seriesdiff-marketplace
Or as a CLI with Go 1.22 or newer. It has no dependencies:
go run github.com/GillMacedo/seriesdiff/plugin/scripts@latest compare base.prom head.prom
## Example
examples/orders holds three versions of a small made-up HTTP service instrumented with the real clientgolang library. after makes typical pull request mistakes: it labels requests with the raw path instead of the route template, changes the latency buckets, drops the reason label from payment errors, renames a gauge, and turns a counter into a gauge. scripts/scrape-examples.sh builds each version, sends the same requests, and saves /metrics. examples/monitoring holds alert rules and a dashboard written against the before metrics. From a clone of this repo:
$ go run ./plugin/scripts compare --refs examples/monitoring examples/scrapes/orders-before.prom examples/scrapes/orders-after.prom
1 removed metric, 1 type change, 1 removed label, 1 bucket change, 2 labels with ID-like values, 2 metrics that lost series, 2 new metrics
Series: 114 -> 114. Metrics: 45 -> 46.
Removed metrics (queries, alerts and dashboards using them get no data):
orderqueuedepth gauge, 1 series
probably renamed to ordersqueuedepth
used in examples/monitoring/alerts.yml:11, examples/monitoring/dashboards/orders.json:22
Type changed (rate() and histogramquantile() depend on the type):
cacheentries counter -> gauge
used in examples/monitoring/dashboards/orders.json:17
Removed labels (by() and label matchers using them stop matching):
paymenterrorstotal label reason, which had 2 values
used in examples/monitoring/alerts.yml:14, examples/monitoring/dashboards/orders.json:12
Histogram buckets changed (quantiles across the change and le= matchers are affected):