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. Currently unused. |
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 |
Default |
--query.lookback-delta |
The server's maximum query lookback duration. |
5m |
--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/scrape configs specified in the config. Available options are: all, duplicate-rules, none, too-long-scrape-interval. Use --lint=none to disable linting |
duplicate-rules |
--lint-fatal |
Make lint errors exit with exit code 3. |
false |
--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. |
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 |
--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. |
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. |
|
--debug |
Enable unit test debugging. |
false |
--diff |
[Experimental] Print colored differential output between expected & received output. |
false |
--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. |
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.