promtool(1)

📦

version 3.15.0 · 15 versions

🌸 NAME 🌸

okay so you're looking at the promtool(1) page — that's the manual for promtool, and the version stamped up top is 3.15.0. Bestie, it's literally Tooling for the Prometheus monitoring system. That's the whole name vibe. 💖

✨ SYNOPSIS ✨

promtool [<flags>] <command> [<args> ...]

💖 DESCRIPTION 💖

Tooling for the Prometheus monitoring system. No cap, that's the description — short, sweet, and doing exactly what it says on the label. 🎀

💅 OPTIONS 💅

-h, --help — Show context-sensitive help (also try --help-long and --help-man). It's giving "help me help you," and honestly? Iconic. 🫶
--version — Show application version. So you can check which era of promtool you're living in. ⭐
--experimental — Enable experimental commands. It's the "let me try something" flag, bestie. 🧚
--enable-feature= — Comma separated feature names to enable. Valid options: promql-experimental-functions, promql-delayed-name-removal, promql-extended-range-selectors. See https://prometheus.io/docs/prometheus/latest/feature_flags/ for more details. Lowkey important: those names are exact, so don't freestyle them. 💜

✨ COMMANDS ✨

okay bestie, this is the whole menu of stuff promtool can actually do. every subcommand with every flag, right here, no gatekeeping 💅

`help [<command>...]`

shows help. that's it, that's the whole vibe. ask it about a specific command and it'll spill the tea on that one 🫶

`check service-discovery [<flags>] <config-file> <job>`

runs service discovery for the job name you give it and reports back the results, including relabeling. it's giving "show me what you actually found" ✨

--timeout=30s — how long to wait for discovery results before giving up.

`check config [<flags>] <config-files>...`

the vibe check for your config files — valid or not, bestie? 💖

--syntax-only — only checks the config file syntax. it ignores the file and content validation that the config references. so like, syntax slay, but it's not looking at the referenced stuff.
--lint="duplicate-rules" — the linting checks to apply to the rules/scrape configs in the config. available options are: all, duplicate-rules, none, too-long-scrape-interval. use --lint=none to disable linting entirely.
--lint-fatal — makes lint errors exit with exit code 3. dramatic? yes. useful? also yes.
--ignore-unknown-fields — ignores unknown fields in the rule groups read by the config files. this is useful when you wanna extend rule files with custom metadata. but make sure you remove those fields before loading them into the Prometheus server, because it does strict checks by default 😭
--agent — checks the config file for Prometheus in Agent mode.

`check web-config <web-config-files>...`

same energy, but for your web config files. valid or not, one file at a time 🦋

`check healthy [<flags>]`

pings the Prometheus server to see if it's healthy. wellness check for your server, lowkey 🩺✨

--http.config.file=<filename> — HTTP client configuration file. the details live at https://prometheus.io/docs/prometheus/latest/configuration/promtool
--url=http://localhost:9090 — the URL for the Prometheus server.

`check ready [<flags>]`

basically the same as healthy but for readiness — is it ready or is it still doing its hair 💅

--http.config.file=<filename> — HTTP client configuration file, see details at https://prometheus.io/docs/prometheus/latest/configuration/promtool
--url=http://localhost:9090 — the URL for the Prometheus server.

`check rules [<flags>] [<rule-files>...]`

checks if your rule files are valid. rule files get the same rigorous vibe check 🎀

--lint="duplicate-rules" — linting checks to apply. available options are: all, duplicate-rules, none. use --lint=none to disable linting.
--lint-fatal — makes lint errors exit with exit code 3.
--ignore-unknown-fields — ignores unknown fields in the rule files. useful when you wanna extend rule files with custom metadata. again: remove those fields before loading them into the Prometheus server, because it performs strict checks by default. no cap.

`check metrics [<flags>]`

feeds Prometheus metrics in over stdin and lints them for consistency and correctness — and if you want, it'll also do a cardinality analysis. main character energy for your metrics 🔥

the examples, verbatim, because they're iconic:

$ cat metrics.prom | promtool check metrics

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

$ curl -s http://localhost:9100/metrics | promtool check metrics
--extended --lint=none

--extended — prints extended information related to the cardinality of the metrics.
--lint="all" — linting checks to apply for metrics. available options are: all, none. use --lint=none to disable metrics linting.

`query instant [<flags>] <server> <expr>`

runs an instant query. one moment in time, one slay 🕐

--time=TIME — query evaluation time (RFC3339 or Unix timestamp).
--header=HEADER — extra headers to send to server.

`query range [<flags>] <server> <expr>`

runs a range query. a whole era of time, bestie 📈

--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>`

runs a series query. --match=MATCH is a required flag here, iykyk 👑

--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>`

runs a labels query. gimme the label names 🏷️✨

--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>]`

runs queries against your Prometheus to analyze the usage pattern of certain metrics. detective mode activated 🔍💜

--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>`

fetches profiling debug information. for when you need to see what's going on inside 🫣

`debug metrics <server>`

fetches metrics debug information.

`debug all <server>`

fetches all the debug information. the whole buffet 🍓

`push metrics [<flags>] <remote-write-url> [<metric-files>...]`

pushes metrics to a Prometheus remote write — for testing purpose only ⚠️ like, do not make this your whole personality, it's literally just for testing.

--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.
--protobuf_message="prometheus.WriteRequest" — protobuf message to use when writing (prometheus.WriteRequest or io.prometheus.write.v2.Request).
--remote-write.path="/api/v1/write" — override the default remote write API path.

`test rules [<flags>] <test-rule-file>...`

unit tests for rules. yes bestie, we're testing the rules themselves 🧪💖

--run=RUN — if set, will only run test groups whose names match the regular expression. can be specified multiple times.
--debug — enable unit test debugging.
--diff — [Experimental] prints colored differential output between expected & received output.
--ignore-unknown-fields — ignores unknown fields in the test files. useful when you wanna extend rule files with custom metadata. and yes, remove those fields before loading them into the Prometheus server — strict checks by default, always 😭

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

runs a write performance benchmark. let's see how hard your disk can go 🏃‍♀️💨

--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>]`

analyzes churn, label pair cardinality and compaction efficiency. the TSDB gossip session 💅

--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>]`

lists tsdb blocks. the lineup 🌸

-r, --human-readable — print human readable values.

`tsdb dump [<flags>] [<db path>]`

dumps data (series+samples, or optionally just series) from a TSDB. dump it, queen 👑

--sandbox-dir-root=SANDBOX-DIR-ROOT — root directory where a sandbox directory will be created. this sandbox is used in case WAL replay generates chunks (default is the database path). the sandbox is cleaned up at the end.
--min-time=-9223372036854775808 — minimum timestamp to dump, in milliseconds since the Unix epoch.
--max-time=9223372036854775807 — maximum timestamp to dump, in milliseconds since the Unix epoch.
--match={__name__=~'(?s:.*)'} — series selector. can be specified multiple times.
--format=prom — output format of the dump (prom (default) or seriesjson).

`tsdb dump-openmetrics [<flags>] [<db path>]`

[Experimental] dumps samples from a TSDB into OpenMetrics text format — excluding native histograms and staleness markers, which are not representable in OpenMetrics. be aware of the exclusions, bestie 🙈

--sandbox-dir-root=SANDBOX-DIR-ROOT — root directory where a sandbox directory will be created. this sandbox is used in case WAL replay generates chunks (default is the database path). the sandbox is cleaned up at the end.
--min-time=-9223372036854775808 — minimum timestamp to dump, in milliseconds since the Unix epoch.
--max-time=9223372036854775807 — maximum timestamp to dump, in milliseconds since the Unix epoch.
--match={__name__=~'(?s:.*)'} — series selector. can be specified multiple times.

`tsdb create-blocks-from openmetrics [<flags>] <input file> [<output directory>]`

imports samples from OpenMetrics input and produces TSDB blocks. please refer to the storage docs for more details 📚✨

--label=LABEL — label to attach to metrics. can be specified multiple times. example: --label=label_name=label_value

`tsdb create-blocks-from rules --start=START [<flags>] <rule-files>...`

creates blocks of data for new recording rules. backfilling era 💫

--http.config.file=<filename> — HTTP client configuration file, see details at https://prometheus.io/docs/prometheus/latest/configuration/promtool
--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.

`promql format <query>`

formats a PromQL query into pretty printed form. make it cute, make it readable 🎀

`promql label-matchers set [<flags>] <query> <name> <value>`

sets a label matcher in the query.

-t, --type== — type of the label matcher to set.

`promql label-matchers delete <query> <name>`

deletes a label from the query. bye bye label 👋💜

and that's the whole page, bestie 🫶 this one's from the promtool manual — promtool, promtool(1) — straight out of the Prometheus source and version, dated whenever that build was cut ✨ go forth and lint responsibly 💅

📦 where this page comes from

epel 9: prometheus 3.15.0-1.el9 · Apache-2.0 AND BSD-2-Clause AND BSD-3-Clause AND ISC AND MIT AND MIT-0 AND MPL-2.0
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-04: a language model's rewrite of the original, under its terms