Validate Your Prometheus Rules Using promtool on macOS

When working with Prometheus, you often write custom recording and alerting rules in YAML files. However, even a small formatting or syntax mistake in these rule files can prevent Prometheus from starting or evaluating your rules correctly. That’s where promtool comes in!

 

In this post, you’ll learn:

 

·      What promtool is

·      How to install it on macOS

·      How to use it to validate your Prometheus rule files

 

1. What is promtool?

promtool is a command-line utility that comes with Prometheus. It helps you:

 

·      Check if your rule files (YAML) are valid

·      Verify PromQL queries

·      Test alert rules

·      Debug time series data and more

 

In short, it’s your go-to tool to make sure your Prometheus configuration is solid before you reload or restart the server.

 

2. Installing promtool on macOS

There are two main ways to install promtool on macOS:

 

2.1 Using brew

If you have Homebrew installed, open terminal and execute following command.

brew install prometheus

This installs both the Prometheus server and promtool.

 

You can verify it with by executing below command.

promtool --version

You should see something like:

$promtool --version
promtool, version 3.2.1 (branch: non-git, revision: non-git)
  build user:       reproducible@reproducible
  build date:       20250225-19:11:52
  go version:       go1.24.0
  platform:         darwin/arm64
  tags:             netgo,builtinassets,stringlabels

2.2 Download Binary from Prometheus Website

 

Step 1: Go to Prometheus downloads page (https://prometheus.io/download/)

 

Step 2: Download the latest macOS tarball

 

Step 3: Extract it:

tar -xvzf prometheus-*.tar.gz
cd prometheus-*

You can see a promtool command available here.

 

3. How to Use promtool to Validate Rule Files?

 

Example rule file: cpu_recording_rules.yaml

 

cpu_recording_rules.yaml

groups:
  - name: per_cpu_avg_rate
    interval: 1m
    rules:
      - record: cpu0:node_cpu_seconds_total:avg_rate5m
        expr: avg(rate(node_cpu_seconds_total{cpu="0"}[5m]))
      - record: cpu1:node_cpu_seconds_total:avg_rate5m
        expr: avg(rate(node_cpu_seconds_total{cpu="1"}[5m]))
      - record: cpu2:node_cpu_seconds_total:avg_rate5m
        expr: avg(rate(node_cpu_seconds_total{cpu="2"}[5m]))
      - record: cpu3:node_cpu_seconds_total:avg_rate5m
        expr: avg(rate(node_cpu_seconds_total{cpu="3"}[5m]))

Validate it by executing below command.

 

promtool check rules cpu_recording_rules.yaml

$promtool check rules cpu_recording_rules.yaml
Checking cpu_recording_rules.yaml
  SUCCESS: 4 rules found

Since the file is a valid rule file, we can’t see any errors.

 

Let’s create a rule file with some indentation errors.

 

improper_indentation.yml

 

groups:
  - name: per_cpu_avg_rate
    interval: 1m
     rules:
      - record: cpu0:node_cpu_seconds_total:avg_rate5m
        expr: avg(rate(node_cpu_seconds_total{cpu="0"}[5m]))

 

Now, when you check the rules, you will see below error.

$promtool check rules improper_indentation.yml 
Checking improper_indentation.yml
  FAILED:
improper_indentation.yml: yaml: line 4: mapping values are not allowed in this context
improper_indentation.yml: yaml: line 4: mapping values are not allowed in this context

 

That’s it….Happy learning…

  

Previous                                                    Next                                                    Home