Promruval is a validation tool written in Go that extends the capabilities of Prometheus rule management by validating rule metadata and expression properties against specific cluster requirements and constraints. While Promtool handles syntactic correctness and PromQL expression testing, Promruval fills a gap by ensuring that rules conform to organizational policies and setup-specific requirements defined through YAML configuration files.
The tool supports validation across multiple monitoring solutions in the Prometheus ecosystem. Users can validate rules for standard Prometheus, Thanos, Mimir, and Loki by using appropriate command-line flags. For Thanos, the --support-thanos flag enables validation of fields like partial_response_strategy. Mimir support via --support-mimir allows validation of source_tenants configuration. Loki support through --support-loki enables validation of LogQL expressions and Loki-specific fields like namespace and remote_write. This multi-platform support reflects the tool's integration with the broader observability ecosystem, as evidenced by GitGenius linking this repository to thanos-io/thanos, grafana/mimir, and grafana/grafana through overlapping contributors.
The validation rules are highly customizable and cover diverse use cases. Users can enforce that alert playbooks reference valid URLs, ensure range selectors in expressions respect Prometheus scrape intervals, verify expressions don't query beyond retention periods, forbid usage of specific labels or annotations, require particular alert labels for Alertmanager routing, validate annotation presence for alert templates, and deprecate old labels or annotations. A default validation configuration is provided in docs/default_validation.yaml as a starting point for most users.
Promruval supports both YAML and Jsonnet rule file formats, automatically rendering Jsonnet files using the go-jsonnet library before validation. Configuration files can also be written in Jsonnet, and multiple configuration files can be composed together with later configurations overriding earlier ones. This flexibility accommodates teams using code generation for rule management.
The tool provides multiple mechanisms for disabling specific validations. Users can employ command-line flags with --disable-rule, YAML comments in the format ignore_validations: validationName, PromQL expression comments for inline disabling, or alert annotations using disabled_validation_rules. This granularity is particularly useful for teams generating rules through Jsonnet where YAML comments may not be feasible.
Promruval is typically integrated into CI pipelines to enforce rule quality standards. The tool can validate rules against live Prometheus instances, though this approach is noted as potentially flaky and resource-intensive for large rule sets, making periodic rather than per-commit validation advisable. The repository is actively maintained by FUSAKLA with 24 tracked events, while jmichalek132 and jpescalona have contributed with 2 events each. Issue and PR response latency shows a median of 61.3 hours across 11 tracked items.
The tool is distributed as prebuilt binaries for Linux, Darwin, and Windows across amd64 and arm64 architectures, though testing is primarily on Linux amd64. Docker images are available through Docker Hub. A validation-docs command generates human-readable validation summaries in text, markdown, or HTML formats for documentation purposes. The repository includes comprehensive documentation of all supported validations in docs/validations.md and example configurations demonstrating practical usage patterns.
