--- name: "promtool" section: "1" platform: "linux" package: "promtool" version: "2.53.3+ds1-2" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/promtool" --- # promtool(1) Tooling for the Prometheus monitoring system ## NAME promtool - Tooling for the Prometheus monitoring system ## SYNOPSIS - **promtool \[\\] \ \[\ ...\]** ## 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 \[\...\]** Show help. ### **check service-discovery \[\\] \ \** 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 \[\\] \...** 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 \...** Check if the web config files are valid or not. ### **check healthy \[\\]** Check if the Prometheus server is healthy. - **--http.config.file=\** HTTP client configuration file for promtool to connect to Prometheus. - **--url=http://localhost:9090** The URL for the Prometheus server. ### **check ready \[\\]** Check if the Prometheus server is ready. - **--http.config.file=\** HTTP client configuration file for promtool to connect to Prometheus. - **--url=http://localhost:9090** The URL for the Prometheus server. ### **check rules \[\\] \[\...\]** 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 \[\\] \ \** Run instant query. - **--time=TIME** Query evaluation time (RFC3339 or Unix timestamp). ### **query range \[\\] \ \** 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 \[\\] \** 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 \[\\] \ \** 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 \[\\]** 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 \** Fetch profiling debug information. ### **debug metrics \** Fetch metrics debug information. ### **debug all \** Fetch all debug information. ### **push metrics \[\\] \ \[\...\]** 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 \[\\] \...** 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 \[\\] \[\\]** 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 \[\\] \[\\] \[\\]** 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 \[\\] \[\\]** List tsdb blocks. - **-r, --human-readable** Print human readable values. ### **tsdb dump \[\\] \[\\]** 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 \[\\] \[\\]** \[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 \ \[\\]** 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 \[\\] \...** Create blocks of data for new recording rules. - **--http.config.file=\** 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 \** Format PromQL query to pretty printed form. ### **promql label-matchers set \[\\] \ \ \** Set a label matcher in the query. - **-t, --type==** Type of the label matcher to set. ### **promql label-matchers delete \ \** Delete a label from the query.