Commands / Counters and flows

Counters and flows

promtool

Also Prometheus, PromQL, prometheus query

Asks a Prometheus server a PromQL question from the shell, and checks its config and rule files.

promtool is Prometheus's command-line client. promtool query instant sends a PromQL query to a running server and prints each series it returns, one line each: the labels, =>, the value and the time it's true for. An empty answer prints nothing: a comparison such as > 80 drops every series that fails it. promtool check reads a config or rules file the way Prometheus will, before you reload it.

promtool command usage

promtool query instant URL 'QUERY'
promtool query range --start=TIME --end=TIME --step=STEP URL 'QUERY'
promtool check config|rules FILE

Options

query instant http://localhost:9090 up
the query's answer right now, from the server at that URL
query range --start= --end= --step=5s
the answer at every step between two times: a graph's worth
check config prometheus.yml
parse the main config, and the rule files it names
check rules rules.yml
parse a rules file and count its rules

promtool examples

promtool query instant http://localhost:9090 up
Lists every target with 1 if its last scrape worked, 0 if not.
promtool query instant http://localhost:9090 'rate(node_network_receive_bytes_total{device="eth0"}[1m]) * 8 / 1000000'
Prints the megabits a second eth0 received, averaged over the last minute.
promtool query instant http://localhost:9090 ALERTS
Lists the alerts that are pending or firing.
promtool check rules /etc/prometheus/rules.yml
Checks a rules file before Prometheus reloads it.

Reading the output

$ promtool query instant http://localhost:9090 up
up{instance="localhost:9090", job="prometheus"} => 1 @[1793660674.294]
up{instance="10.0.1.2:9100", job="router"} => 0 @[1793660674.294]
  • up: the metric's name. In the braces, its labels: job from the config, instance the address scraped.
  • => 0: the router's last scrape failed. @[…]: the moment, in seconds since 1970.
  • After arithmetic or rate(), the name is dropped and only the labels are printed.

Pitfalls

  • Quote the query in single quotes: its braces, double quotes and * are the shell's otherwise.
  • Node counters are in bytes; a line's speed is in bits. Multiply by 8 before comparing with a speed in Mbit/s.

Run it on real machines

Learn it on real machines.

Every lab is a small network of real Linux machines in your browser. Sign in with Google or email to start.

Start this lab