promtool

Prometheus configuration and query utility

TLDR

Check Prometheus config syntax

$ promtool check config [prometheus.yml]

Check alerting rules

$ promtool check rules [rules.yml]

Test alerting rules

$ promtool test rules [test.yml]

Query Prometheus metrics

$ promtool query instant [http://localhost:9090] "[up]"

Query range of metrics

$ promtool query range [http://localhost:9090] "[up]" --start [1h]

Validate metrics exposition

$ curl -s [http://localhost:9100/metrics] | promtool check metrics

Debug metrics parsing

$ promtool debug metrics [http://localhost:9090]

SYNOPSIS

promtool command subcommand [options] [arguments]

promtool is the command-line utility for Prometheus, the popular monitoring and alerting system. It validates configuration, tests rules, and queries metrics.
Configuration checking catches syntax errors and invalid settings before applying changes. This prevents Prometheus from failing to start due to configuration issues.
Rule validation ensures alerting and recording rules are syntactically correct. Combined with unit testing (test rules), you can verify alert behavior before deployment. Test files specify sample data and expected alert states.
Query commands execute PromQL queries against running Prometheus servers. Instant queries return current values; range queries return time series data. This enables scripting and automation around Prometheus data.
The tsdb subcommand provides direct TSDB (time series database) manipulation: analyzing, benchmarking, and maintaining the storage layer.

PARAMETERS

check config FILE

Validate Prometheus configuration file.

check rules FILES

Validate alerting/recording rules.

check metrics

Validate metrics format from stdin.

test rules FILES

Unit test alerting rules.

query instant SERVER QUERY

Execute instant query.

query range SERVER QUERY

Execute range query.

query labels SERVER LABEL

Query label values.

query series SERVER MATCH

Query time series.

debug pprof TYPE

Get debug profiling data.

debug metrics SERVER

Debug metrics endpoint.

debug all SERVER

Get all debug information.

tsdb subcommand

TSDB database operations.

--start TIME

Query start time.

--end TIME

Query end time.

--step DURATION

Query step interval.

CAVEATS

Requires Prometheus knowledge to use effectively. Query commands need running Prometheus server. Rule tests require careful test data construction. Some commands access remote servers. Output format varies by command.

HISTORY

promtool is part of Prometheus, created at SoundCloud around 2012 by Matt T. Proud and Julius Volz. Prometheus was open-sourced in 2015 and joined CNCF in 2016. The promtool utility evolved alongside Prometheus to provide operational tooling for configuration management and troubleshooting.