promtool

Check if the configuration files are valid or not (if present report errors)

$ promtool check config [config_file.yml]

$ promtool check rules [rules_file.yml]

$ curl --silent [http://example.com:9090/metrics/] | promtool check metrics

$ promtool test rules [test_file.yml]

promtool command [options] [arguments]

Common commands:
tsdb                    Tools for the Prometheus TSDB
check                  Check Prometheus configuration and rules
rule                   Tools for Prometheus rules
debug                  Tools for debugging
version                Print promtool version
help                   Help about any command

--help
    Displays help information for promtool or a specific subcommand.

--version
    Prints the promtool version and build information.

--log.level=level
    Sets the logging verbosity level (e.g., debug, info).

--log.format=format
    Sets the log output format (e.g., logfmt, json).

tsdb analyze --data-dir=path
    Analyzes and reports statistics about the Prometheus TSDB data in the specified directory.

tsdb compact --data-dir=path
    Manually triggers compaction of TSDB blocks within the given data directory.

check config config_file
    Validates the syntax and semantics of a Prometheus configuration file.

check rules rule_files...
    Validates the syntax and semantics of Prometheus recording and alert rule files.

rule convert --input=file --output=file
    Converts Prometheus rule files between different formats (e.g., from JSON to YAML).

promtool is a versatile command-line utility bundled with Prometheus, designed to assist administrators and developers in various tasks related to Prometheus deployments. It provides robust subcommands for managing and inspecting the underlying Time Series Database (TSDB), including operations like analyzing data integrity, forcing block compaction, and repairing metadata. Furthermore, it's indispensable for validating Prometheus configuration files and Alertmanager/recording rule files for syntax and semantic correctness before deployment, thus preventing potential runtime issues. It also includes tools for debugging Prometheus instances and converting rule formats between different specifications. Its comprehensive functionality makes it an essential tool for maintaining the health, integrity, and operational efficiency of any Prometheus monitoring system.

When using tsdb commands, especially compact or repair, it is critical to stop the Prometheus server first to prevent data corruption. promtool operates on files and directories, so ensure correct permissions. The check subcommands perform static analysis; they cannot guarantee runtime behavior or performance.

promtool is crucial for offline maintenance tasks, allowing administrators to interact directly with the TSDB data files without the Prometheus server running, which is vital for recovery or analysis of large datasets.

Utilizing promtool check config and promtool check rules in CI/CD pipelines ensures that configuration changes and rule updates are syntactically and semantically correct before deployment, preventing runtime errors.

promtool emerged as a dedicated utility alongside the Prometheus server. As Prometheus's TSDB matured and configuration complexities grew, the need for specialized tools to manage data, validate configurations, and aid debugging became apparent. It consolidated various scripts and internal tools into a single, comprehensive binary, evolving with Prometheus to support new features like TSDB block operations and improved rule management.

prometheus(1), alertmanager(1), node_exporter(1), yml(5)