Skip to content

promtool

The tool kit of Prometheus: checks configuration and alert rules, runs PromQL queries on the command line and tests rules.

promtool output

Syntax

promtool check config FILE
promtool check rules FILE...
promtool query instant URL QUERY

Options

Command Description
check config FILE Check prometheus.yml and the rule files it names
check rules FILE... Check rule files
check metrics Check metrics from stdin against the naming rules
query instant URL QUERY Run a PromQL query against a server
query range URL QUERY --start --end Query a time range
test rules FILE Run unit tests for alert rules

promtool comes with the prometheus package. Its exit code is 0 if everything is valid, which makes it a good fit for scripts and CI.

Examples

Check the configuration including the rules:

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/node.yml
  SUCCESS: 2 rules found

An error in a rule file:

promtool check rules /etc/prometheus/rules/node.yml
Checking /etc/prometheus/rules/node.yml
  FAILED:
/etc/prometheus/rules/node.yml: unknown unit " minutes" in duration "2 minutes"

Durations are written as 2m, 1h or 7d.

An error in the configuration:

promtool check config /etc/prometheus/prometheus.yml
Checking /etc/prometheus/prometheus.yml

  FAILED: parsing YAML file /etc/prometheus/prometheus.yml: not a valid duration string: "15"

scrape_interval: 15 lacks the unit; correct is 15s.

Which targets are down:

promtool query instant http://localhost:9090 'up == 0'
up{instance="192.0.2.21:9100", job="node"} => 0 @[1793007737.358]

RAM usage of all servers in percent:

promtool query instant http://localhost:9090 \
  '100 * (1 - node_memory_MemAvailable_bytes / node_memory_MemTotal_bytes)'
{instance="192.0.2.22:9100", job="node"} => 71.48203125 @[1793007737.358]
{instance="localhost:9100", job="node"} => 36.47693447 @[1793007737.358]

Which alerts are firing right now:

promtool query instant http://localhost:9090 ALERTS
ALERTS{alertname="InstanceDown", alertstate="firing", instance="192.0.2.21:9100", job="node", severity="critical"} => 1 @[1793007737.358]

When do I need it?

  • Before every reload of Prometheus, after changing the configuration or rules
  • In CI, so that broken rules never reach the server
  • For quick queries in a terminal, without opening the web interface

Check rules in CI

A step promtool check rules rules/*.yml in your pipeline finds typos before the merge. With promtool test rules you can even prove that an alert fires for given values.

Valid doesn't mean useful

check rules checks the syntax. A rule with a wrong metric name is valid and just never fires. Test new expressions with promtool query instant first: no output means no data.

Distribution differences

Debian Ubuntu RHEL Arch
Package prometheus prometheus in the release archive of Prometheus prometheus

prometheus · amtool · node_exporter · yamllint