Utilities

Prometheus Config Linter

Lint Prometheus alert rules, recording rules, and scrape configs against best practices. Catches missing for: clauses, missing severity labels, naming convention violations, and more — before they reach production.

Paste your Prometheus rule file or scrape config

Paste your YAML above and click Lint Config.

Findings will be listed here grouped by severity. The linter checks alert rules, recording rules, and scrape configs against common Prometheus best practices.

Automate your incident response

Reduce MTTR by 90% with AI-powered root cause analysis. Free to start.

Try Uptimes.ai Free

The four mistakes that account for most alerting pain

We have audited a lot of Prometheus rule files. The same handful of mistakes show up over and over, and each one produces real on-call pain.

  1. No for: clause — alert fires on a single bad evaluation, which means flap. The fix is one line: for: 5m. Burn-rate alerts can use for: 2m because the burn rate math already filters blips.
  2. No severity label — alertmanager has nothing to route on, so you either silence everything or page on everything. Add labels: { severity: page } or labels: { severity: ticket }.
  3. No summary / description annotations — alert lands in PagerDuty as the rule name only. Responder has no idea what is wrong without opening the dashboard. Both annotations should template in actual values from the metric (use {{ $value }}).
  4. No runbook_url annotation — responder is alone with their thoughts at 3 AM. Generate a runbook with the Runbook Generator tool and link it here.

Recording rule naming pays for itself

The Prometheus community standardized on <level>:<metric>:<operation> because anonymous recording rule names produce a debugging nightmare six months later. Following the convention is free, makes recording rules instantly self-documenting, and makes them visually distinct from raw metrics in PromQL queries.

From linting to live monitoring

Static linting catches design mistakes before they ship. But alerting hygiene degrades over time as rules accumulate, services churn, and thresholds drift. Uptimes.ai monitors your alerts continuously, flags rules that fire often without resolution (likely noise), detects correlated alerts that should be deduplicated, and surfaces coverage gaps where signals are missing entirely. Use this linter to catch the obvious problems; use Uptimes for the rest.

Frequently Asked Questions

What does the linter check?+
For alert rules: missing for: clauses (flapping risk), missing severity labels (alertmanager cannot route), missing summary/description annotations (poor PagerDuty/Slack messages), missing runbook_url annotations, and PascalCase naming convention. For recording rules: the level:metric:operation naming convention (job:http_requests:rate5m). For scrape configs: missing job_name and evaluation_interval shorter than scrape_interval. The checks are best-practice heuristics, not Prometheus syntax validation — promtool check rules is still the authoritative validator.
Why does the linter recommend a `for:` clause on every alert?+
Without a for: clause, an alert fires on every single bad evaluation — meaning a one-second blip will page someone. With for: 5m, the condition has to hold for 5 minutes before firing, which filters out the vast majority of false positives. Multi-window burn-rate alerts use for: 2m as a minimum because the burn rate calculation already filters short blips. Either way, never deploy alerts without a for: clause.
What is the level:metric:operation convention for recording rules?+
Prometheus best practice for recording rule names: `<level>:<metric>:<operation>`. Examples: job:http_requests:rate5m, instance:cpu_usage_seconds:rate5m, namespace:pod_memory_bytes:avg. The level tells you what was aggregated by, the metric tells you the source signal, the operation tells you what was applied. This makes recording rules self-documenting — a query author can read the name and know what it represents without looking at the rule definition.
Does this replace promtool?+
No. promtool check rules validates Prometheus syntax and catches malformed rules. This linter checks higher-level conventions and best practices that promtool does not — things like "is this alert routable" and "does this rule follow naming conventions". Run both: promtool catches syntax errors, this catches design errors.
My alerts pass the linter but still page too much. What now?+
Linting structure does not fix bad thresholds. If alerts fire too often, the right answer is usually multi-window burn-rate alerts based on your SLO — see the Burn Rate Calculator. The Alert Noise Score tool can help quantify how much noise your current alerting produces.

Related Tools

Burn Rate Calculator

Generate multi-window SLO alert thresholds.

Prometheus Cardinality Estimator

Series count, memory, and disk for any metric.

Alert Noise Score

Score your alerting hygiene with prioritized fixes.