promtool

Active contributors: dgl, roidelapluie, bjboreham

Purpose

promtool is the CLI counterpart to the server. It validates configuration, runs PromQL against a remote Prometheus, debugs and benchmarks the TSDB, generates documentation, runs rule unit tests, and imports metrics from OpenMetrics.

Directory layout

cmd/promtool/
├── main.go               # Subcommand registration (~1,500 lines).
├── analyze.go            # `tsdb analyze` and `query analyze` commands.
├── archive.go            # Generic archive helpers.
├── backfill.go           # `tsdb create-blocks-from openmetrics`.
├── debug.go              # `debug pprof|metrics|all` commands.
├── metrics.go            # `push metrics` for the OTLP write receiver.
├── query.go              # `query instant|range|series|labels`.
├── rules.go              # `tsdb create-blocks-from rules`.
├── sd.go                 # `check service-discovery`.
├── tsdb.go               # `tsdb` subcommands: list, dump, analyze, bench.
├── unittest.go           # `test rules` driver.
└── testdata/             # Fixtures for all the above.

Subcommand catalogue

Subcommand	Purpose
promtool check config	Validate one or more prometheus.yml files.
promtool check rules	Validate alerting/recording rule files.
promtool check service-discovery	Resolve a discovery section against a config file and print targets.
promtool check web-config	Validate the exporter-toolkit web config (TLS + basic auth).
promtool check metrics	Lint the contents of a /metrics endpoint or text file.
promtool query instant <url> <expr>	Run an instant query.
promtool query range <url> <expr>	Run a range query with --start/--end/--step.
promtool query series <url>	Series matcher lookup.
promtool query labels <url>	Label name listing.
promtool query analyze <url>	Cardinality analysis.
promtool query log-format <url>	Convert the query log into a more readable form.
promtool debug pprof	Capture pprof from a running server.
promtool debug metrics	Capture and tar the /metrics endpoint.
promtool debug all	Combined debug bundle (pprof + metrics + config + flags).
promtool tsdb list <data dir>	List blocks.
promtool tsdb dump <data dir>	Dump block contents as text.
promtool tsdb analyze <data dir> [block]	Cardinality and chunk stats.
promtool tsdb bench write	Write benchmark; backbone of make bench_tsdb.
promtool tsdb create-blocks-from openmetrics	Backfill from OpenMetrics text.
promtool tsdb create-blocks-from rules	Backfill recording-rule results into a block.
promtool test rules <files>	Rule unit-test driver (Datadog-style YAML cases).
promtool push metrics ...	Push metrics to a remote write or OTLP endpoint.
promtool write-documentation	Emit the full subcommand reference (used by make cli-documentation).

Key files and abstractions

File	Purpose
cmd/promtool/main.go	All kingpin subcommand registration and dispatch.
cmd/promtool/tsdb.go	Block iteration, printBlocks, write benchmark.
cmd/promtool/backfill.go	OpenMetrics -> TSDB block writer.
cmd/promtool/rules.go	Rule recording -> block writer.
cmd/promtool/unittest.go	YAML schema for test rules (promql_expr_test, series, alerts_tests).
cmd/promtool/analyze.go	Histogram and label cardinality analysis.
cmd/promtool/sd.go	Resolve a config's *_sd_configs and print discovered targets.

Rule unit tests

promtool test rules is one of the most-used subcommands. Test files declare:

rule_files:
  - my-rules.yml

evaluation_interval: 1m

tests:
  - interval: 1m
    input_series:
      - series: 'http_errors{job="api"}'
        values: '0+1x10'
    promql_expr_test:
      - expr: rate(http_errors[1m])
        eval_time: 5m
        exp_samples:
          - labels: 'http_errors{job="api"}'
            value: 0.016
    alert_rule_test:
      - eval_time: 10m
        alertname: HighErrors
        exp_alerts:
          - exp_labels: { severity: warning }

The runner (unittest.go) uses promqltest and the tsdb package directly, so it shares evaluation semantics with the production engine.

Backfill

promtool tsdb create-blocks-from openmetrics input.txt outdir reads a stream of OpenMetrics samples, sorts them, groups them into 2-hour blocks, and emits TSDB blocks. The implementation in backfill.go reuses tsdb/blockwriter.go. It's the recommended way to import historical data without going through scraping or remote write.

promtool tsdb create-blocks-from rules is the equivalent for recording rules: it evaluates a rule against an existing storage and writes the result as a block.

Integration with the server

promtool is built from the same go.mod as the server, so it shares all internal libraries. It does not embed UI assets.

Entry points for modification

• Add a new subcommand: register it in main.go's kingpin setup, then create a sibling *.go file for its implementation. Run make cli-documentation to refresh docs/command-line/promtool.md.
• Change rule unit-test format: edit unittest.go and update the integration tests in unittest_test.go. Make sure any change is reflected in docs/configuration/unit_testing_rules.md.
• Add a new validation: prefer hooking into config/config.go's Validate() so the same rule applies in the server. promtool check config shells out to the same code path.

See also: PromQL, TSDB, Rules.