promtool

build user: team+pkg-go@tracker.debian.org
build date: 20250421-12:29:42
go version: go1.19.8
platform: linux/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.

--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="duplicate-rules"

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 rules [<flags>] <rule-files>...

Check if the rule files are valid or not.
--lint="duplicate-rules"

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.

debug pprof <server>

Fetch profiling debug information.

debug metrics <server>

Fetch metrics debug information.

debug all <server>

Fetch all debug information.

test rules <test-rule-file>...

Unit tests for rules.

tsdb bench write [<flags>] [<file*>]

Run a write performance benchmark.
--out="benchout"

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.

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.
--min-time=-9223372036854775808

Minimum timestamp to dump.

--max-time=9223372036854775807

Maximum timestamp to dump.

--match="{__name__=˜’(?s:.*)’}"

Series selector.

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.
--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="data/"

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.