Counters and flows
promtool
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:jobfrom the config,instancethe 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.