Tooling for the Prometheus monitoring system.
Flags
Flag |
Description |
-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
Command |
Description |
help |
Show help. |
check |
Check the resources for validity. |
query |
Run query against a Prometheus server. |
debug |
Fetch debug information. |
push |
Push to a Prometheus server. |
test |
Unit testing. |
tsdb |
Run tsdb commands. |
promql |
PromQL formatting and editing. Requires the --experimental flag. |
Show help.
Arguments
Argument |
Description |
command |
Show help on command. |
Check the resources for validity.
Flags
Flag |
Description |
--extended |
Print extended information related to the cardinality of the metrics. |
Perform service discovery for the given job name and report the results, including relabeling.
Flags
Flag |
Description |
Default |
--timeout |
The time to wait for discovery results. |
30s |
Arguments
Argument |
Description |
Required |
config-file |
The prometheus config file. |
Yes |
job |
The job to run service discovery for. |
Yes |
Check if the config files are valid or not.
Flags
Flag |
Description |
Default |
--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 |
duplicate-rules |
--lint-fatal |
Make lint errors exit with exit code 3. |
false |
--agent |
Check config file for Prometheus in Agent mode. |
|
Arguments
Argument |
Description |
Required |
config-files |
The config files to check. |
Yes |
Check if the web config files are valid or not.
Arguments
Argument |
Description |
Required |
web-config-files |
The config files to check. |
Yes |
Check if the Prometheus server is healthy.
Flags
Flag |
Description |
Default |
--http.config.file |
HTTP client configuration file for promtool to connect to Prometheus. |
|
--url |
The URL for the Prometheus server. |
http://localhost:9090 |
Check if the Prometheus server is ready.
Flags
Flag |
Description |
Default |
--http.config.file |
HTTP client configuration file for promtool to connect to Prometheus. |
|
--url |
The URL for the Prometheus server. |
http://localhost:9090 |
Check if the rule files are valid or not.
Flags
Flag |
Description |
Default |
--lint |
Linting checks to apply. Available options are: all, duplicate-rules, none. Use --lint=none to disable linting |
duplicate-rules |
--lint-fatal |
Make lint errors exit with exit code 3. |
false |
Arguments
Argument |
Description |
rule-files |
The rule files to check, default is read from standard input. |
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
Run query against a Prometheus server.
Flags
Flag |
Description |
Default |
-o , --format
|
Output format of the query. |
promql |
--http.config.file |
HTTP client configuration file for promtool to connect to Prometheus. |
|
Run instant query.
Flags
Flag |
Description |
--time |
Query evaluation time (RFC3339 or Unix timestamp). |
Arguments
Argument |
Description |
Required |
server |
Prometheus server to query. |
Yes |
expr |
PromQL query expression. |
Yes |
Run range query.
Flags
Flag |
Description |
--header |
Extra headers to send to server. |
--start |
Query range start time (RFC3339 or Unix timestamp). |
--end |
Query range end time (RFC3339 or Unix timestamp). |
--step |
Query step size (duration). |
Arguments
Argument |
Description |
Required |
server |
Prometheus server to query. |
Yes |
expr |
PromQL query expression. |
Yes |
Run series query.
Flags
Flag |
Description |
--match ...
|
Series selector. Can be specified multiple times. |
--start |
Start time (RFC3339 or Unix timestamp). |
--end |
End time (RFC3339 or Unix timestamp). |
Arguments
Argument |
Description |
Required |
server |
Prometheus server to query. |
Yes |
Run labels query.
Flags
Flag |
Description |
--start |
Start time (RFC3339 or Unix timestamp). |
--end |
End time (RFC3339 or Unix timestamp). |
--match ...
|
Series selector. Can be specified multiple times. |
Arguments
Argument |
Description |
Required |
server |
Prometheus server to query. |
Yes |
name |
Label name to provide label values for. |
Yes |
Run queries against your Prometheus to analyze the usage pattern of certain metrics.
Flags
Flag |
Description |
Default |
--server |
Prometheus server to query. |
|
--type |
Type of metric: histogram. |
|
--duration |
Time frame to analyze. |
1h |
--time |
Query time (RFC3339 or Unix timestamp), defaults to now. |
|
--match ...
|
Series selector. Can be specified multiple times. |
|
Fetch debug information.
Fetch profiling debug information.
Arguments
Argument |
Description |
Required |
server |
Prometheus server to get pprof files from. |
Yes |
Fetch metrics debug information.
Arguments
Argument |
Description |
Required |
server |
Prometheus server to get metrics from. |
Yes |
Fetch all debug information.
Arguments
Argument |
Description |
Required |
server |
Prometheus server to get all debug information from. |
Yes |
Push to a Prometheus server.
Flags
Flag |
Description |
--http.config.file |
HTTP client configuration file for promtool to connect to Prometheus. |
Push metrics to a prometheus remote write (for testing purpose only).
Flags
Flag |
Description |
Default |
--label |
Label to attach to metrics. Can be specified multiple times. |
job=promtool |
--timeout |
The time to wait for pushing metrics. |
30s |
--header |
Prometheus remote write header. |
|
Arguments
Argument |
Description |
Required |
remote-write-url |
Prometheus remote write url to push metrics. |
Yes |
metric-files |
The metric files to push, default is read from standard input. |
|
Unit testing.
Flags
Flag |
Description |
--junit |
File path to store JUnit XML test results. |
Unit tests for rules.
Flags
Flag |
Description |
Default |
--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. |
false |
Arguments
Argument |
Description |
Required |
test-rule-file |
The unit test file. |
Yes |
Run tsdb commands.
Run benchmarks.
Run a write performance benchmark.
Flags
Flag |
Description |
Default |
--out |
Set the output path. |
benchout |
--metrics |
Number of metrics to read. |
10000 |
--scrapes |
Number of scrapes to simulate. |
3000 |
Arguments
Argument |
Description |
Default |
file |
Input file with samples data, default is (../../tsdb/testdata/20kseries.json). |
../../tsdb/testdata/20kseries.json |
Analyze churn, label pair cardinality and compaction efficiency.
Flags
Flag |
Description |
Default |
--limit |
How many items to show in each list. |
20 |
--extended |
Run extended analysis. |
|
--match |
Series selector to analyze. Only 1 set of matchers is supported now. |
|
Arguments
Argument |
Description |
Default |
db path |
Database path (default is data/). |
data/ |
block id |
Block to analyze (default is the last block). |
|
List tsdb blocks.
Flags
Flag |
Description |
-r , --human-readable
|
Print human readable values. |
Arguments
Argument |
Description |
Default |
db path |
Database path (default is data/). |
data/ |
Dump samples from a TSDB.
Flags
Flag |
Description |
Default |
--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 |
Minimum timestamp to dump. |
-9223372036854775808 |
--max-time |
Maximum timestamp to dump. |
9223372036854775807 |
--match ...
|
Series selector. Can be specified multiple times. |
{__name__=~'(?s:.*)'} |
Arguments
Argument |
Description |
Default |
db path |
Database path (default is data/). |
data/ |
[Experimental] Dump samples from a TSDB into OpenMetrics text format, excluding native histograms and staleness markers, which are not representable in OpenMetrics.
Flags
Flag |
Description |
Default |
--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 |
Minimum timestamp to dump. |
-9223372036854775808 |
--max-time |
Maximum timestamp to dump. |
9223372036854775807 |
--match ...
|
Series selector. Can be specified multiple times. |
{__name__=~'(?s:.*)'} |
Arguments
Argument |
Description |
Default |
db path |
Database path (default is data/). |
data/ |
[Experimental] Import samples from input and produce TSDB blocks. Please refer to the storage docs for more details.
Flags
Flag |
Description |
-r , --human-readable
|
Print human readable values. |
-q , --quiet
|
Do not print created blocks. |
Import samples from OpenMetrics input and produce TSDB blocks. Please refer to the storage docs for more details.
Flags
Flag |
Description |
--label |
Label to attach to metrics. Can be specified multiple times. Example --label=labelname=labelvalue |
Arguments
Argument |
Description |
Default |
Required |
input file |
OpenMetrics file to read samples from. |
|
Yes |
output directory |
Output directory for generated blocks. |
data/ |
|
Create blocks of data for new recording rules.
Flags
Flag |
Description |
Default |
--http.config.file |
HTTP client configuration file for promtool to connect to Prometheus. |
|
--url |
The URL for the Prometheus API with the data where the rule will be backfilled from. |
http://localhost:9090 |
--start |
The time to start backfilling the new rule from. Must be a RFC3339 formatted date or Unix timestamp. Required. |
|
--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. |
data/ |
--eval-interval |
How frequently to evaluate rules when backfilling if a value is not set in the recording rule files. |
60s |
Arguments
Argument |
Description |
Required |
rule-files |
A list of one or more files containing recording rules to be backfilled. All recording rules listed in the files will be backfilled. Alerting rules are not evaluated. |
Yes |
PromQL formatting and editing. Requires the --experimental
flag.
Format PromQL query to pretty printed form.
Arguments
Argument |
Description |
Required |
query |
PromQL query. |
Yes |
Edit label matchers contained within an existing PromQL query.
Set a label matcher in the query.
Flags
Flag |
Description |
Default |
-t , --type
|
Type of the label matcher to set. |
= |
Arguments
Argument |
Description |
Required |
query |
PromQL query. |
Yes |
name |
Name of the label matcher to set. |
Yes |
value |
Value of the label matcher to set. |
Yes |
Delete a label from the query.
Arguments
Argument |
Description |
Required |
query |
PromQL query. |
Yes |
name |
Name of the label to delete. |
Yes |
This documentation is open-source. Please help improve it by filing issues or pull requests.