Project: Prometheus (Observability and Analysis / Observability)
File: recording_rules.md

title: Recording rules sort_rank: 2 Prometheus supports two types of rules which may be configured and then evaluated at regular intervals: recording rules and [alerting rules](alerting_rules.md). To include rules in Prometheus, create a file containing the necessary rule statements and have Prometheus load the file via the `rule_files` field in the . Rule files use YAML. The rule files can be reloaded at runtime by sending `SIGHUP` to the Prometheus process. The changes are only applied if all rule files are well-formatted. _Note about native histograms (experimental feature): Native histogram are always recorded as gauge histograms (for now). Most cases will create gauge histograms naturally, e.g. after `rate()`._ To quickly check whether a rule file is syntactically correct without starting a Prometheus server, you can use Prometheus's `promtool` command-line utility tool: ```bash promtool check rules /path/to/example.rules.yml ``` The `promtool` binary is part of the `prometheus` archive offered on the project's . When the file is syntactically valid, the checker prints a textual representation of the parsed rules to standard output and then exits with a `0` return status. If there are any syntax errors or invalid input arguments, it prints an error message to standard error and exits with a `1` return status. Recording rules allow you to precompute frequently needed or computationally expensive expressions and save their result as a new set of time series. Querying the precomputed result will then often be much faster than executing the original expression every time it is needed. This is especially useful for dashboards, which need to query the same expression repeatedly every time they refresh. Recording and alerting rules exist in a rule group. Rules within a group are run sequentially at a regular interval, with the same evaluation time. The names of recording rules must be . The names of alerting rules must be . The syntax of a rule file is: ```yaml groups: [ - <rule_group> ] ``` A simple example rules file would be: ```yaml groups: name: example rules: record: code:prometheushttprequests_total:sum expr: sum by (code) (prometheushttprequests_total) ``` ``` name: <string> [ interval: <duration> | default = global.evaluation_interval ] [ limit: <int> | default = 0 ] rules: [ - <rule> ... ] ``` The syntax for recording rules is: ``` record: <string> expr: <string> labels: [ <labelname>: <labelvalue> ] ``` The syntax for alerting rules is: ``` alert: <string> expr: <string> [ for: <duration> | default = 0s ] [ keepfiringfor: <duration> | default = 0s ] labels: [ <labelname>: <tmpl_string> ] annotations: [ <labelname>: <tmpl_string> ] ``` See also the . A limit for alerts produced by alerting rules and series produced recording rules can be configured per-group. When the limit is exceeded, all series produced by the rule are discarded, and if it's an alerting rule, all alerts for the rule, active, pending, or inactive, are cleared as well. The event will be recorded as an error in the evaluation, and as such no stale markers are written. If a rule group hasn't finished evaluating before its next evaluation is supposed to start (as defined by the `evaluationinterval`), the next evaluation will be skipped. Subsequent evaluations of the rule group will continue to be skipped until the initial evaluation either completes or times out. When this happens, there will be a gap in the metric produced by the recording rule. The `rulegroupiterationsmissed_total` metric will be incremented for each missed iteration of the rule group.