Intro to PromTools

Promtool is the command-line utility bundled with Prometheus. It helps you validate configurations, test rules, and debug metric exposition so Prometheus can reliably scrape and evaluate targets. Common promtool use cases:

Validate Prometheus configuration files (for example, prometheus.yml) and rule files.
Validate metric exposition formats to ensure Prometheus can consume them.
Run ad hoc queries against a Prometheus server.
Debug and profile a Prometheus server.
Execute unit-style checks against recording and alerting rules.

Slide titled "Promtools" describing a Prometheus utility. It lists features: checking/validating configuration (Prometheus.yml and rules files), validating metric formatting, and performing queries on a Prometheus server.

Validate Prometheus configuration: `promtool check config`

One of the most useful promtool commands is check config. It parses and validates a Prometheus configuration file before you deploy it so you don’t accidentally bring Prometheus down with a bad config. Example — successful validation of /etc/prometheus/prometheus.yml:

$ promtool check config /etc/prometheus/prometheus.yml
Checking prometheus.yml
    SUCCESS: prometheus.yml is valid prometheus config file syntax

If the configuration contains a typo or an unsupported field, promtool returns a parsing error and usually shows the line and field that caused the problem. For example, if metrics_path is misspelled as metric_path inside a scrape_config, promtool reports the offending line:

$ promtool check config /etc/prometheus/prometheus.yml
Checking prometheus.yml
    FAILED: parsing YAML file prometheus.yml: yaml: unmarshal errors:
    line 24: field metric_path not found in type config.ScrapeConfig

Minimal problematic snippet (typo: metric_path instead of metrics_path):

scrape_configs:
  - job_name: "node"
    metric_path: "/metrics"   # <-- typo: should be `metrics_path`
    static_configs:
      - targets: ["node1:9100"]

Promtool pointing to the exact line and field makes it fast to locate and fix configuration errors before reloading or restarting Prometheus.

Always validate Prometheus configuration files with promtool check config before reloading or restarting Prometheus in production to avoid downtime caused by invalid configs.

Useful promtool commands (quick reference)

Command	Purpose	Example
`promtool check config <file>`	Validate Prometheus config syntax	`promtool check config /etc/prometheus/prometheus.yml`
`promtool check rules <file>`	Validate alerting/recording rules and alert expression syntax	`promtool check rules /etc/prometheus/rules.yml`
`promtool test rules <dir\|file>`	Run rule tests written using PromQL test cases	`promtool test rules ./rule_tests/`
`promtool check metrics <file\|URL>`	Validate an endpoint’s metric exposition format	`promtool check metrics http://localhost:9100/metrics`
`promtool query <expr> --<flags>`	Execute ad-hoc PromQL queries against a Prometheus server	`promtool query 'up{job="node"}' --storage.tsdb.path=/var/lib/prometheus`

Common error messages and remediation

Error message	Likely cause	Suggested fix
`field <name> not found in type config.ScrapeConfig`	Typo or unsupported config field (e.g., `metric_path`)	Correct the field name to the expected config key (e.g., `metrics_path`)
`yaml: line X: did not find expected key`	Bad YAML indentation or syntax	Fix YAML indentation or format; validate with a YAML linter
`FAILED: parsing rule file`	Invalid PromQL or malformed rule	Check rule expressions and alert labels; use `promtool check rules` to get details

Best practices

Always run promtool check config locally or in CI before applying config changes.
Save rule and config changes in version control so you can review diffs and run automated promtool checks in CI pipelines.
Pair promtool check rules with promtool test rules to verify alerting and recording rules behave as expected.
Use promtool check metrics <URL> when developing instrumented applications to ensure metrics are exposed in the correct format.

Introduction

Observability Fundamentals

Prometheus Fundamentals

PromQL

Dashboarding & Visualization

Application Instrumentation

Service Discovery

Push Gateway

Alerting

Monitoring Kubernetes

Conclusion

Scaling & Long Term Storage

Intro to PromTools

Validate Prometheus configuration: `promtool check config`

Useful promtool commands (quick reference)

Common error messages and remediation

Best practices

Links and references

Watch Video

​Validate Prometheus configuration: promtool check config

​Useful promtool commands (quick reference)

​Common error messages and remediation

​Best practices

​Links and references

Watch Video

Validate Prometheus configuration: `promtool check config`

Useful promtool commands (quick reference)

Common error messages and remediation

Best practices

Links and references