promtool

Tooling for the Prometheus monitoring system.

Flags

Flag Description

-h, –help

Show context-sensitive help (also try –help-long and –help-man).

–version

Show application version.

–experimental

Enable experimental commands.

–enable-feature

Comma 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

Command Description

help

Show help.

check

Check the resources for validity.

query

Run query against a Prometheus server.

debug

Fetch debug information.

push

Push to a Prometheus server.

test

Unit testing.

tsdb

Run tsdb commands.

promql

PromQL formatting and editing. Requires the –experimental flag.

promtool help

Show help.

Arguments
Argument Description

command

Show help on command.

promtool check

Check the resources for validity.

Flags
Flag Description

–extended

Print 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

Flag Description Default

–timeout

The time to wait for discovery results.

30s

======= Arguments

Argument Description Required

config-file

The prometheus config file.

Yes

job

The job to run service discovery for.

Yes
promtool check config

Check if the config files are valid or not.

======= Flags

Flag Description Default

–syntax-only

Only check the config file syntax, ignoring file and content validation referenced in the config

–lint

Linting checks to apply to the rules specified in the config. Available options are: all, duplicate-rules, none. Use –lint=none to disable linting

duplicate-rules

–lint-fatal

Make lint errors exit with exit code 3.

false

–agent

Check config file for Prometheus in Agent mode.

======= Arguments

Argument Description Required

config-files

The config files to check.

Yes
promtool check web-config

Check if the web config files are valid or not.

======= Arguments

Argument Description Required

web-config-files

The config files to check.

Yes
promtool check healthy

Check if the Prometheus server is healthy.

======= Flags

Flag Description Default

–http.config.file

HTTP client configuration file for promtool to connect to Prometheus.

–url

The URL for the Prometheus server.

http://localhost:9090
promtool check ready

Check if the Prometheus server is ready.

======= Flags

Flag Description Default

–http.config.file

HTTP client configuration file for promtool to connect to Prometheus.

–url

The URL for the Prometheus server.

http://localhost:9090
promtool check rules

Check if the rule files are valid or not.

======= Flags

Flag Description Default

–lint

Linting checks to apply. Available options are: all, duplicate-rules, none. Use –lint=none to disable linting

duplicate-rules

–lint-fatal

Make lint errors exit with exit code 3.

false

======= Arguments

Argument Description

rule-files

The 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
Flag Description Default

-o, –format

Output format of the query.

promql

–http.config.file

HTTP client configuration file for promtool to connect to Prometheus.
promtool query instant

Run instant query.

======= Flags

Flag Description

–time

Query evaluation time (RFC3339 or Unix timestamp).

======= Arguments

Argument Description Required

server

Prometheus server to query.

Yes

expr

PromQL query expression.

Yes
promtool query range

Run range query.

======= Flags

Flag Description

–header

Extra headers to send to server.

–start

Query range start time (RFC3339 or Unix timestamp).

–end

Query range end time (RFC3339 or Unix timestamp).

–step

Query step size (duration).

======= Arguments

Argument Description Required

server

Prometheus server to query.

Yes

expr

PromQL query expression.

Yes
promtool query series

Run series query.

======= Flags

Flag Description

–match

Series selector. Can be specified multiple times.

–start

Start time (RFC3339 or Unix timestamp).

–end

End time (RFC3339 or Unix timestamp).

======= Arguments

Argument Description Required

server

Prometheus server to query.

Yes
promtool query labels

Run labels query.

======= Flags

Flag Description

–start

Start time (RFC3339 or Unix timestamp).

–end

End time (RFC3339 or Unix timestamp).

–match

Series selector. Can be specified multiple times.

======= Arguments

Argument Description Required

server

Prometheus server to query.

Yes

name

Label name to provide label values for.

Yes
promtool query analyze

Run queries against your Prometheus to analyze the usage pattern of certain metrics.

======= Flags

Flag Description Default

–server

Prometheus server to query.

–type

Type of metric: histogram.

–duration

Time frame to analyze.

1h

–time

Query time (RFC3339 or Unix timestamp), defaults to now.

–match

Series selector. Can be specified multiple times.

promtool debug

Fetch debug information.

promtool debug pprof

Fetch profiling debug information.

Arguments
Argument Description Required

server

Prometheus server to get pprof files from.

Yes
promtool debug metrics

Fetch metrics debug information.

Arguments
Argument Description Required

server

Prometheus server to get metrics from.

Yes
promtool debug all

Fetch all debug information.

Arguments
Argument Description Required

server

Prometheus server to get all debug information from.

Yes

promtool push

Push to a Prometheus server.

Flags
Flag Description

–http.config.file

HTTP client configuration file for promtool to connect to Prometheus.
promtool push metrics

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

======= Flags

Flag Description Default

–label

Label to attach to metrics. Can be specified multiple times.

job=promtool

–timeout

The time to wait for pushing metrics.

30s

–header

Prometheus remote write header.

======= Arguments

Argument Description Required

remote-write-url

Prometheus remote write url to push metrics.

Yes

metric-files

The metric files to push, default is read from standard input.

promtool test

Unit testing.

promtool test rules

Unit tests for rules.

Flags
Flag Description Default

–run

If set, will only run test groups whose names match the regular expression. Can be specified multiple times.

–diff

[Experimental] Print colored differential output between expected & received output.

false
Arguments
Argument Description Required

test-rule-file

The unit test file.

Yes

promtool tsdb

Run tsdb commands.

promtool tsdb bench

Run benchmarks.

promtool tsdb bench write

Run a write performance benchmark.

Flags
Flag Description Default

–out

Set the output path.

benchout

–metrics

Number of metrics to read.

10000

–scrapes

Number of scrapes to simulate.

3000
Arguments
Argument Description Default

file

Input 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
Flag Description Default

–limit

How many items to show in each list.

20

–extended

Run extended analysis.

–match

Series selector to analyze. Only 1 set of matchers is supported now.
Arguments
Argument Description Default

db path

Database path (default is data/).

data/

block id

Block to analyze (default is the last block).
promtool tsdb list

List tsdb blocks.

Flags
Flag Description

-r, –human-readable

Print human readable values.
Arguments
Argument Description Default

db path

Database path (default is data/).

data/
promtool tsdb dump

Dump samples from a TSDB.

Flags
Flag Description Default

–min-time

Minimum timestamp to dump.

-9223372036854775808

–max-time

Maximum timestamp to dump.

9223372036854775807

–match

Series selector. Can be specified multiple times.

{__name__=~'(?s:.*)'}
Arguments
Argument Description Default

db path

Database path (default is data/).

data/
promtool tsdb dump-openmetrics

[Experimental] Dump samples from a TSDB into OpenMetrics format. Native histograms are not dumped.

Flags
Flag Description Default

–min-time

Minimum timestamp to dump.

-9223372036854775808

–max-time

Maximum timestamp to dump.

9223372036854775807

–match

Series selector. Can be specified multiple times.

{__name__=~'(?s:.*)'}
Arguments
Argument Description Default

db path

Database 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
Flag Description

-r, –human-readable

Print human readable values.

-q, –quiet

Do 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
Argument Description Default Required

input file

OpenMetrics file to read samples from.

Yes

output directory

Output directory for generated blocks.

data/
promtool tsdb create-blocks-from rules

Create blocks of data for new recording rules.

Flags
Flag Description Default

–http.config.file

HTTP client configuration file for promtool to connect to Prometheus.

–url

The URL for the Prometheus API with the data where the rule will be backfilled from.

http://localhost:9090

–start

The time to start backfilling the new rule from. Must be a RFC3339 formatted date or Unix timestamp. Required.

–end

If 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-dir

Output directory for generated blocks.

data/

–eval-interval

How frequently to evaluate rules when backfilling if a value is not set in the recording rule files.

60s
Arguments
Argument Description Required

rule-files

A 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
Argument Description Required

query

PromQL 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
Flag Description Default

-t, –type

Type of the label matcher to set.

=
Arguments
Argument Description Required

query

PromQL query.

Yes

name

Name of the label matcher to set.

Yes

value

Value of the label matcher to set.

Yes
promtool promql label-matchers delete

Delete a label from the query.

Arguments
Argument Description Required

query

PromQL query.

Yes

name

Name of the label to delete.

Yes