---
title: promtool
---

# promtool

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

### `promtool help`

Show help.



#### Arguments

| Argument | Description |
| --- | --- |
| command | Show help on command. |




### `promtool check`

Check the resources for validity.

#### Flags

| Flag | Description |
| --- | --- |
| --extended | Print extended information related to the cardinality of the metrics. |

##### `promtool check service-discovery`

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 |




##### `promtool check config`

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 |

##### `promtool check web-config`

Check if the web config files are valid or not.



###### Arguments

| Argument | Description | Required |
| --- | --- | --- |
| web-config-files | The config files to check. | Yes |




##### `promtool check healthy`

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




##### `promtool check ready`

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




##### `promtool check rules`

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




##### `promtool 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



### `promtool query`

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

##### `promtool query instant`

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 |

##### `promtool query range`

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 |

##### `promtool query series`

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 |

##### `promtool query labels`

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 |

##### `promtool query analyze`

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

### `promtool debug`

Fetch debug information.



##### `promtool debug pprof`

Fetch profiling debug information.



###### Arguments

| Argument | Description | Required |
| --- | --- | --- |
| server | Prometheus server to get pprof files from. | Yes |




##### `promtool debug metrics`

Fetch metrics debug information.



###### Arguments

| Argument | Description | Required |
| --- | --- | --- |
| server | Prometheus server to get metrics from. | Yes |




##### `promtool debug all`

Fetch all debug information.



###### Arguments

| Argument | Description | Required |
| --- | --- | --- |
| server | Prometheus server to get all debug information from. | Yes |




### `promtool push`

Push to a Prometheus server.

#### Flags

| Flag | Description |
| --- | --- |
| --http.config.file | HTTP client configuration file for promtool to connect to Prometheus. |

##### `promtool push metrics`

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

### `promtool test`

Unit testing.



##### `promtool test rules`

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 |




### `promtool tsdb`

Run tsdb commands.



##### `promtool tsdb bench`

Run benchmarks.



##### `promtool tsdb bench write`

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




##### `promtool tsdb analyze`

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




##### `promtool tsdb list`

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/` |




##### `promtool tsdb dump`

Dump samples from a TSDB.

###### Flags

| Flag | Description | Default |
| --- | --- | --- |
| --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. | `data/` |
| --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/` |




##### `promtool tsdb dump-openmetrics`

[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 would be created in case WAL replay generates chunks. The sandbox directory is cleaned up at the end. | `data/` |
| --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/` |




##### `promtool tsdb create-blocks-from`

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

##### `promtool tsdb create-blocks-from openmetrics`

Import samples from OpenMetrics input and produce TSDB blocks. Please refer to the storage docs for more details.



###### Arguments

| Argument | Description | Default | Required |
| --- | --- | --- | --- |
| input file | OpenMetrics file to read samples from. |  | Yes |
| output directory | Output directory for generated blocks. | `data/` |  |




##### `promtool tsdb create-blocks-from rules`

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 |




### `promtool promql`

PromQL formatting and editing. Requires the `--experimental` flag.



##### `promtool promql format`

Format PromQL query to pretty printed form.



###### Arguments

| Argument | Description | Required |
| --- | --- | --- |
| query | PromQL query. | Yes |




##### `promtool promql label-matchers`

Edit label matchers contained within an existing PromQL query.



##### `promtool promql label-matchers set`

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 |




##### `promtool promql label-matchers delete`

Delete a label from the query.



###### Arguments

| Argument | Description | Required |
| --- | --- | --- |
| query | PromQL query. | Yes |
| name | Name of the label to delete. | Yes |


