Provided by: promtool_2.53.3+ds1-2_amd64 
NAME
promtool - Tooling for the Prometheus monitoring system
SYNOPSIS
promtool [<flags>] <command> [<args> ...]
DESCRIPTION
Tooling for the Prometheus monitoring system.
OPTIONS
-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
help [<command>...]
Show help.
check service-discovery [<flags>] <config-file> <job>
Perform service discovery for the given job name and report the results, including relabeling.
--timeout=30s
The time to wait for discovery results.
check config [<flags>] <config-files>...
Check if the config files are valid or not.
--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
--lint-fatal
Make lint errors exit with exit code 3.
--agent
Check config file for Prometheus in Agent mode.
check web-config <web-config-files>...
Check if the web config files are valid or not.
check healthy [<flags>]
Check if the Prometheus server is healthy.
--http.config.file=<filename>
HTTP client configuration file for promtool to connect to Prometheus.
--url=http://localhost:9090
The URL for the Prometheus server.
check ready [<flags>]
Check if the Prometheus server is ready.
--http.config.file=<filename>
HTTP client configuration file for promtool to connect to Prometheus.
--url=http://localhost:9090
The URL for the Prometheus server.
check rules [<flags>] [<rule-files>...]
Check if the rule files are valid or not.
--lint Linting checks to apply. Available options are: all, duplicate-rules, none. Use --lint=none to
disable linting
--lint-fatal
Make lint errors exit with exit code 3.
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
query instant [<flags>] <server> <expr>
Run instant query.
--time=TIME
Query evaluation time (RFC3339 or Unix timestamp).
query range [<flags>] <server> <expr>
Run range query.
--header=HEADER
Extra headers to send to server.
--start=START
Query range start time (RFC3339 or Unix timestamp).
--end=END
Query range end time (RFC3339 or Unix timestamp).
--step=STEP
Query step size (duration).
query series --match=MATCH [<flags>] <server>
Run series query.
--match=MATCH
Series selector. Can be specified multiple times.
--start=START
Start time (RFC3339 or Unix timestamp).
--end=END
End time (RFC3339 or Unix timestamp).
query labels [<flags>] <server> <name>
Run labels query.
--start=START
Start time (RFC3339 or Unix timestamp).
--end=END
End time (RFC3339 or Unix timestamp).
--match=MATCH
Series selector. Can be specified multiple times.
query analyze --server=SERVER --type=TYPE --match=MATCH [<flags>]
Run queries against your Prometheus to analyze the usage pattern of certain metrics.
--server=SERVER
Prometheus server to query.
--type=TYPE
Type of metric: histogram.
--duration=1h
Time frame to analyze.
--time=TIME
Query time (RFC3339 or Unix timestamp), defaults to now.
--match=MATCH
Series selector. Can be specified multiple times.
debug pprof <server>
Fetch profiling debug information.
debug metrics <server>
Fetch metrics debug information.
debug all <server>
Fetch all debug information.
push metrics [<flags>] <remote-write-url> [<metric-files>...]
Push metrics to a prometheus remote write (for testing purpose only).
--label=job=promtool
Label to attach to metrics. Can be specified multiple times.
--timeout=30s
The time to wait for pushing metrics.
--header=HEADER
Prometheus remote write header.
test rules [<flags>] <test-rule-file>...
Unit tests for rules.
--run=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.
tsdb bench write [<flags>] [<file*>]
Run a write performance benchmark.
--out Set the output path.
--metrics=10000
Number of metrics to read.
--scrapes=3000
Number of scrapes to simulate.
tsdb analyze [<flags>] [<db path*>] [<block id>]
Analyze churn, label pair cardinality and compaction efficiency.
--limit=20
How many items to show in each list.
--extended
Run extended analysis.
--match=MATCH
Series selector to analyze. Only 1 set of matchers is supported now.
tsdb list [<flags>] [<db path*>]
List tsdb blocks.
-r, --human-readable
Print human readable values.
tsdb dump [<flags>] [<db path*>]
Dump samples from a TSDB.
--sandbox-dir-root
Root directory where a sandbox directory would be created in case WAL replay generates chunks. The
sandbox directory is cleaned up at the end.
--min-time=-9223372036854775808
Minimum timestamp to dump.
--max-time=9223372036854775807
Maximum timestamp to dump.
--match={__name__=~'(?s:.*)'}
Series selector. Can be specified multiple times.
tsdb dump-openmetrics [<flags>] [<db path*>]
[Experimental] Dump samples from a TSDB into OpenMetrics text format, excluding native histograms and
staleness markers, which are not representable in OpenMetrics.
--sandbox-dir-root
Root directory where a sandbox directory would be created in case WAL replay generates chunks. The
sandbox directory is cleaned up at the end.
--min-time=-9223372036854775808
Minimum timestamp to dump.
--max-time=9223372036854775807
Maximum timestamp to dump.
--match={__name__=~'(?s:.*)'}
Series selector. Can be specified multiple times.
tsdb create-blocks-from openmetrics <input file> [<output directory*>]
Import samples from OpenMetrics input and produce TSDB blocks. Please refer to the storage docs for more
details.
tsdb create-blocks-from rules --start=START [<flags>] <rule-files>...
Create blocks of data for new recording rules.
--http.config.file=<filename>
HTTP client configuration file for promtool to connect to Prometheus.
--url=http://localhost:9090
The URL for the Prometheus API with the data where the rule will be backfilled from.
--start=START
The time to start backfilling the new rule from. Must be a RFC3339 formatted date or Unix
timestamp. Required.
--end=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.
--eval-interval=60s
How frequently to evaluate rules when backfilling if a value is not set in the recording rule
files.
promql format <query>
Format PromQL query to pretty printed form.
promql label-matchers set [<flags>] <query> <name> <value>
Set a label matcher in the query.
-t, --type==
Type of the label matcher to set.
promql label-matchers delete <query> <name>
Delete a label from the query.
prometheus 2.53.3+ds1 June 2025 PROMTOOL(1)