promtool

Tooling for the Prometheus monitoring system.

Flags

FlagDescription
-h, —helpShow context-sensitive help (also try —help-long and —help-man).
—versionShow application version.
—experimentalEnable experimental commands.
—enable-featureComma separated feature names to enable (only PromQL related and no-default-scrape-port). See https://prometheus.io/docs/prometheus/latest/feature_flags/ for the options and more details.

Commands

CommandDescription
helpShow help.
checkCheck the resources for validity.
queryRun query against a Prometheus server.
debugFetch debug information.
pushPush to a Prometheus server.
testUnit testing.
tsdbRun tsdb commands.
promqlPromQL formatting and editing. Requires the —experimental flag.

promtool help

Show help.

Arguments

ArgumentDescription
commandShow help on command.

promtool check

Check the resources for validity.

Flags

FlagDescription
—extendedPrint extended information related to the cardinality of the metrics.
promtool check service-discovery

Perform service discovery for the given job name and report the results, including relabeling.

Flags
FlagDescriptionDefault
—timeoutThe time to wait for discovery results.30s
Arguments
ArgumentDescriptionRequired
config-fileThe prometheus config file.Yes
jobThe job to run service discovery for.Yes
promtool check config

Check if the config files are valid or not.

Flags
FlagDescriptionDefault
—syntax-onlyOnly check the config file syntax, ignoring file and content validation referenced in the config
—lintLinting checks to apply to the rules specified in the config. Available options are: all, duplicate-rules, none. Use —lint=none to disable lintingduplicate-rules
—lint-fatalMake lint errors exit with exit code 3.false
—agentCheck config file for Prometheus in Agent mode.
Arguments
ArgumentDescriptionRequired
config-filesThe config files to check.Yes
promtool check web-config

Check if the web config files are valid or not.

Arguments
ArgumentDescriptionRequired
web-config-filesThe config files to check.Yes
promtool check healthy

Check if the Prometheus server is healthy.

Flags
FlagDescriptionDefault
—http.config.fileHTTP client configuration file for promtool to connect to Prometheus.
—urlThe URL for the Prometheus server.http://localhost:9090
promtool check ready

Check if the Prometheus server is ready.

Flags
FlagDescriptionDefault
—http.config.fileHTTP client configuration file for promtool to connect to Prometheus.
—urlThe URL for the Prometheus server.http://localhost:9090
promtool check rules

Check if the rule files are valid or not.

Flags
FlagDescriptionDefault
—lintLinting checks to apply. Available options are: all, duplicate-rules, none. Use —lint=none to disable lintingduplicate-rules
—lint-fatalMake lint errors exit with exit code 3.false
Arguments
ArgumentDescription
rule-filesThe rule files to check, default is read from standard input.
promtool check metrics

Pass Prometheus metrics over stdin to lint them for consistency and correctness.

examples:

$ cat metrics.prom | promtool check metrics

$ curl -s http://localhost:9090/metrics | promtool check metrics

promtool query

Run query against a Prometheus server.

Flags

FlagDescriptionDefault
-o, —formatOutput format of the query.promql
—http.config.fileHTTP client configuration file for promtool to connect to Prometheus.
promtool query instant

Run instant query.

Flags
FlagDescription
—timeQuery evaluation time (RFC3339 or Unix timestamp).
Arguments
ArgumentDescriptionRequired
serverPrometheus server to query.Yes
exprPromQL query expression.Yes
promtool query range

Run range query.

Flags
FlagDescription
—headerExtra headers to send to server.
—startQuery range start time (RFC3339 or Unix timestamp).
—endQuery range end time (RFC3339 or Unix timestamp).
—stepQuery step size (duration).
Arguments
ArgumentDescriptionRequired
serverPrometheus server to query.Yes
exprPromQL query expression.Yes
promtool query series

Run series query.

Flags
FlagDescription
—matchSeries selector. Can be specified multiple times.
—startStart time (RFC3339 or Unix timestamp).
—endEnd time (RFC3339 or Unix timestamp).
Arguments
ArgumentDescriptionRequired
serverPrometheus server to query.Yes
promtool query labels

Run labels query.

Flags
FlagDescription
—startStart time (RFC3339 or Unix timestamp).
—endEnd time (RFC3339 or Unix timestamp).
—matchSeries selector. Can be specified multiple times.
Arguments
ArgumentDescriptionRequired
serverPrometheus server to query.Yes
nameLabel name to provide label values for.Yes

promtool debug

Fetch debug information.

promtool debug pprof

Fetch profiling debug information.

Arguments
ArgumentDescriptionRequired
serverPrometheus server to get pprof files from.Yes
promtool debug metrics

Fetch metrics debug information.

Arguments
ArgumentDescriptionRequired
serverPrometheus server to get metrics from.Yes
promtool debug all

Fetch all debug information.

Arguments
ArgumentDescriptionRequired
serverPrometheus server to get all debug information from.Yes

promtool push

Push to a Prometheus server.

Flags

FlagDescription
—http.config.fileHTTP client configuration file for promtool to connect to Prometheus.
promtool push metrics

Push metrics to a prometheus remote write (for testing purpose only).

Flags
FlagDescriptionDefault
—labelLabel to attach to metrics. Can be specified multiple times.job=promtool
—timeoutThe time to wait for pushing metrics.30s
—headerPrometheus remote write header.
Arguments
ArgumentDescriptionRequired
remote-write-urlPrometheus remote write url to push metrics.Yes
metric-filesThe metric files to push, default is read from standard input.

promtool test

Unit testing.

promtool test rules

Unit tests for rules.

Arguments
ArgumentDescriptionRequired
test-rule-fileThe unit test file.Yes

promtool tsdb

Run tsdb commands.

promtool tsdb bench

Run benchmarks.

promtool tsdb bench write

Run a write performance benchmark.

Flags
FlagDescriptionDefault
—outSet the output path.benchout
—metricsNumber of metrics to read.10000
—scrapesNumber of scrapes to simulate.3000
Arguments
ArgumentDescriptionDefault
fileInput file with samples data, default is (../../tsdb/testdata/20kseries.json).../../tsdb/testdata/20kseries.json
promtool tsdb analyze

Analyze churn, label pair cardinality and compaction efficiency.

Flags
FlagDescriptionDefault
—limitHow many items to show in each list.20
—extendedRun extended analysis.
—matchSeries selector to analyze. Only 1 set of matchers is supported now.
Arguments
ArgumentDescriptionDefault
db pathDatabase path (default is data/).data/
block idBlock to analyze (default is the last block).
promtool tsdb list

List tsdb blocks.

Flags
FlagDescription
-r, —human-readablePrint human readable values.
Arguments
ArgumentDescriptionDefault
db pathDatabase path (default is data/).data/
promtool tsdb dump

Dump samples from a TSDB.

Flags
FlagDescriptionDefault
—min-timeMinimum timestamp to dump.-9223372036854775808
—max-timeMaximum timestamp to dump.9223372036854775807
—matchSeries selector.{name=~’(?s:.*)’}
Arguments
ArgumentDescriptionDefault
db pathDatabase path (default is data/).data/
promtool tsdb create-blocks-from

[Experimental] Import samples from input and produce TSDB blocks. Please refer to the storage docs for more details.

Flags
FlagDescription
-r, —human-readablePrint human readable values.
-q, —quietDo not print created blocks.
promtool tsdb create-blocks-from openmetrics

Import samples from OpenMetrics input and produce TSDB blocks. Please refer to the storage docs for more details.

Arguments
ArgumentDescriptionDefaultRequired
input fileOpenMetrics file to read samples from.Yes
output directoryOutput directory for generated blocks.data/
promtool tsdb create-blocks-from rules

Create blocks of data for new recording rules.

Flags
FlagDescriptionDefault
—http.config.fileHTTP client configuration file for promtool to connect to Prometheus.
—urlThe URL for the Prometheus API with the data where the rule will be backfilled from.http://localhost:9090
—startThe time to start backfilling the new rule from. Must be a RFC3339 formatted date or Unix timestamp. Required.
—endIf an end time is provided, all recording rules in the rule files provided will be backfilled to the end time. Default will backfill up to 3 hours ago. Must be a RFC3339 formatted date or Unix timestamp.
—output-dirOutput directory for generated blocks.data/
—eval-intervalHow frequently to evaluate rules when backfilling if a value is not set in the recording rule files.60s
Arguments
ArgumentDescriptionRequired
rule-filesA list of one or more files containing recording rules to be backfilled. All recording rules listed in the files will be backfilled. Alerting rules are not evaluated.Yes

promtool promql

PromQL formatting and editing. Requires the --experimental flag.

promtool promql format

Format PromQL query to pretty printed form.

Arguments
ArgumentDescriptionRequired
queryPromQL query.Yes
promtool promql label-matchers

Edit label matchers contained within an existing PromQL query.

promtool promql label-matchers set

Set a label matcher in the query.

Flags
FlagDescriptionDefault
-t, —typeType of the label matcher to set.=
Arguments
ArgumentDescriptionRequired
queryPromQL query.Yes
nameName of the label matcher to set.Yes
valueValue of the label matcher to set.Yes
promtool promql label-matchers delete

Delete a label from the query.

Arguments
ArgumentDescriptionRequired
queryPromQL query.Yes
nameName of the label to delete.Yes

This documentation is open-source. Please help improve it by filing issues or pull requests.