How to load a Prometheus rule file

Loading a Prometheus rule file makes recording or alerting rules part of the running server configuration. It connects a saved YAML rule group to scheduled evaluation, so dashboards and alerts can use the rule output after Prometheus reloads.

Prometheus does not scan arbitrary directories for rules. The active configuration file must include a rule_files entry, and each entry can be a single YAML file or a glob such as /etc/prometheus/rules/*.yml.

The path /etc/prometheus/prometheus.yml is common on Linux package installs, but the active --config.file startup flag wins when a service or container uses another file. Keep the order strict by validating the rule file, validating the full configuration, reloading Prometheus, and querying the loaded rule after the next evaluation interval.

Steps to load a Prometheus rule file:

Create a directory for Prometheus rule files.

$ sudo install -d -m 0755 /etc/prometheus/rules

Open a rule file in that directory.

$ sudoedit /etc/prometheus/rules/rule-file-load.yml

Add a rule group to the file.

groups:
  - name: rule-file-load
    interval: 30s
    rules:
      - record: job:prometheus_build_info:count
        expr: count by (job) (prometheus_build_info)
        labels:
          rule_source: file

This rule records one count from Prometheus's own prometheus_build_info metric. Use a recording or alerting expression that already returns data in your Prometheus server.

Open the active Prometheus configuration file.
```
$ sudoedit /etc/prometheus/prometheus.yml
```
Use the file path from the server's --config.file startup flag when Prometheus was started with a non-default configuration file.
Add the rule-file glob under rule_files.
```
global:
  evaluation_interval: 30s

rule_files:
  - /etc/prometheus/rules/*.yml
```
Keep existing scrape_configs, alerting, storage, and remote-write settings in the same file. A glob lets Prometheus load several rule files from the same directory.

Check the rule-file syntax.

$ promtool check rules /etc/prometheus/rules/rule-file-load.yml
Checking /etc/prometheus/rules/rule-file-load.yml
  SUCCESS: 1 rules found

Check the full Prometheus configuration.

$ promtool check config /etc/prometheus/prometheus.yml
Checking /etc/prometheus/prometheus.yml
  SUCCESS: 1 rule files found
 SUCCESS: /etc/prometheus/prometheus.yml is valid prometheus config file syntax

Checking /etc/prometheus/rules/rule-file-load.yml
  SUCCESS: 1 rules found

Reload Prometheus so it reads the rule file.
```
$ curl --request POST --include --silent --show-error http://127.0.0.1:9090/-/reload
HTTP/1.1 200 OK
Date: Sat, 20 Jun 2026 10:23:07 GMT
Content-Length: 0
```
The HTTP reload endpoint works only when Prometheus starts with --web.enable-lifecycle. Use SIGHUP or the service manager when the endpoint returns Lifecycle APIs are not enabled.

Related: How to reload Prometheus configuration
Wait for the next rule evaluation interval.

This group uses interval: 30s. A rule can stay absent from query results until Prometheus has scraped the source metric and evaluated the group.

Query the recorded series from Prometheus.

$ curl --silent --show-error 'http://127.0.0.1:9090/api/v1/query?query=job:prometheus_build_info:count'
{"status":"success","data":{"resultType":"vector","result":[{"metric":{"__name__":"job:prometheus_build_info:count","job":"prometheus","rule_source":"file"},"value":[1781951007.460,"1"]}]}}

The response should show status set to success and include the recorded metric name. An empty result usually means the rule file loaded but the source expression has not produced a sample yet.