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. Valid options: promql-experimental-functions, promql-delayed-name-removal. See https://prometheus.io/docs/prometheus/latest/feature_flags/ for 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/scrape configs specified in the config. Available options are: all, duplicate-rules, none, too-long-scrape-interval. Use --lint=none to disable linting

--lint-fatal
    Make lint errors exit with exit code 3.

--ignore-unknown-fields
    Ignore unknown fields in the rule groups read by the config files. This is useful when you want to extend rule files with custom metadata. Ensure that those fields are removed before loading them into the Prometheus server as it performs strict checks by default.

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

--ignore-unknown-fields
    Ignore unknown fields in the rule files. This is useful when you want to extend rule files with custom metadata. Ensure that those fields are removed before loading them into the Prometheus server as it performs strict checks by default.

  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.

--debug
    Enable unit test debugging.

--diff
    [Experimental] Print colored differential output between expected & received output.

--ignore-unknown-fields
    Ignore unknown fields in the test files. This is useful when you want to extend rule files with custom metadata. Ensure that those fields are removed before loading them into the Prometheus server as it performs strict checks by default.

  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=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 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=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*>]

Import samples from OpenMetrics input and produce 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>...

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.