Using Promtool CLI

1. Validating Configuration

Command	Description	Options	Example
promtool check config	Validates Prometheus configuration files	`--config.file`, `--dry-run`	`promtool check config prometheus.yml`

Note: The promtool check config command ensures that your Prometheus configuration is syntactically correct and does not contain any invalid elements.

2. Checking Rule Files

Example: Validating a rule file

promtool check rules /path/to/rules.yml

Option	Values	Description
--dry-run	`false`	Perform a dry run without actually checking rules
--rule-timeout	`30s`	Timeout for rule evaluation
--output	`json`	Output format (json or yaml)

Note: The promtool check rules command validates rule files for syntax errors and ensures they conform to Prometheus's rule format.

Warning: Rule files must follow the correct YAML structure and use valid Prometheus expression syntax.

3. Testing Rules Against Data

Example: Testing a Rule

promtool test rules example.yaml

Option	Values	Description
--dry-run	`false`	Run without actually applying rules
--output	`console`	Output format (console, json)

Note: The promtool test rules command evaluates rule files against sample data to ensure they behave as expected.

Warning: Ensure that your rule files are valid YAML and follow Prometheus rule syntax.

4. Querying Prometheus

Example: Querying rate of HTTP requests

rate(http_requests_total[5m])

Query Type	Description	Example
Instant Query	Retrieves the value of a metric at a specific timestamp	`http_requests_total`
Range Query	Retrieves metric values over a time range	`http_requests_total[1h]`
Aggregation	Groups metrics by labels and applies an aggregation function	`sum by (method) (http_requests_total)`
Rate Functions	Calculates the per-second average rate of increase of a counter	`rate(http_requests_total[5m])`

Note: Promtool supports both instant and range queries. Use rate() for counter metrics to get per-second rates.

Example: Using Promtool to query a range

promtool query range --url=http://localhost:9090 'http_requests_total[1h]'

5. Debugging Metrics

Command	Description	Example
promtool check metrics	Validates metric names and labels against Prometheus rules	`promtool check metrics /path/to/metrics.txt`
promtool check rules	Checks Prometheus recording and alerting rules for syntax errors	`promtool check rules /path/to/rules.yaml`
promtool test rules	Runs a set of rule files against sample data to verify behavior	`promtool test rules /path/to/rules.yaml /path/to/sample_data.json`

Note: Ensure all metric names follow the Prometheus naming conventions to avoid validation errors.

Warning: The promtool test rules command requires a valid JSON file with sample data in the format specified by recording rules.

6. Checking Metric Format

Field	Description	Example
metric_name	Name of the metric	`http_requests_total`
labels	Key-value pairs for metric identification	`{method="GET", handler="/api"}`
value	Numeric value of the metric	`1234.56`
timestamp	Optional Unix timestamp in milliseconds	`1634567890000`

Example: Valid Metric Format


http_requests_total{method="GET", handler="/api"} 1234.56

Example: Invalid Metric Format


http_requests_total{method="GET", handler="/api"} 1234.56
invalid_line_without_metric_name

Note: The promtool check metrics command validates the format of metric lines in a file or stream.

Workflow: Validate Metrics Using Promtool

Prepare a file containing Prometheus metrics in the correct format.
Run promtool check metrics <file> to validate the format.
Fix any errors reported by the tool before using the metrics in a Prometheus server.

7. Importing TSDB Data

Example: Importing TSDB data using promtool

promtool tsdb create-blocks-from-metrics \
  --input.metrics="http://localhost:9090/api/v1/series?match[]={__name__=~"node_cpu_seconds_total"}" \
  --output.directory="/path/to/output/dir" \
  --max.samples=1000000

Option	Description	Default Value
--input.metrics	URL to fetch metrics from	None
--output.directory	Directory to store the created blocks	./blocks
--max.samples	Maximum number of samples to process	1000000

Note: Ensure that the input URL returns valid metric data in Prometheus format.

Warning: Large datasets may require significant memory and time to process.

8. Analyzing TSDB Blocks

Command	Description	Options
promtool tsdb analyze	Analyses the contents of a TSDB block directory	`--max-samples` limits samples analyzed `--timeout` sets analysis timeout

Example: Analyze TSDB block

promtool tsdb analyze /path/to/tsdb/block/0123456789

Note: The command outputs statistics about series, samples, and chunks in the block.

Output Field	Description	Sample Value
series count	Number of series in the block	`12345`
sample count	Total number of samples	`567890`
chunk count	Total number of chunks	`23456`
max timestamp	Latest timestamp in the block	`1680000000000`

9. Creating TSDB Snapshots

TSDB snapshots are used to create point-in-time backups of the Prometheus storage data. They are useful for disaster recovery, long-term archival, or for creating consistent baselines for performance analysis.

Command	Description	Options
promtool tsdb snapshot	Creates a snapshot of the TSDB data	`--snapshot.dir` - Directory to write the snapshot into `--db.path` - Path to the TSDB directory (default: `/prometheus/data`) `--max-block-duration` - Maximum block duration to include in the snapshot (default: `2h`)

Example: Creating a TSDB Snapshot

promtool tsdb snapshot --snapshot.dir=/backup/prometheus-snapshot --db.path=/prometheus/data

Note: Snapshots are created by copying the block files and metadata, ensuring data consistency at a specific point in time.

Warning: Ensure sufficient disk space is available before creating a snapshot, as it can be large depending on the data size.

10. Dumping TSDB Data

Example: Dumping TSDB data to JSON

promtool tsdb dump /path/to/data/directory

Command	Description	Flags
promtool tsdb dump	Dumps the contents of a TSDB directory to JSON format	`--dry-run` - Preview without writing `--output` - Specify output file

Note: The dumped data includes all samples and metadata from the TSDB.

11. Running Unit Tests

Example: Test a Prometheus rule file

promtool test rules example.rules

Command	Description	Options
promtool test rules	Validate and run unit tests on Prometheus rule files	`-dry-run` to preview without execution

Note: Rule files must follow the Prometheus rule syntax and include valid PromQL expressions.

12. Benchmarking Queries

Command	Description	Options	Example
promtool bench query	Benchmark Prometheus query performance	`-timeout`, `-queries`, `-output`	`promtool bench query -timeout=30s -queries=query1,query2 http://localhost:9090`

Example: Benchmarking a Query

promtool bench query -timeout=10s -queries="up" http://localhost:9090

Note: The benchmarking tool runs queries multiple times and reports average execution time.