PROMTOOL(1)

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.