Skip to main content
In this guide you’ll learn how to configure Prometheus so it knows which targets to scrape. Prometheus uses a pull model: the server must be configured explicitly to retrieve metrics from each exporter. The main configuration file is a YAML file, typically located at /etc/prometheus/prometheus.yml. Below are concise examples and explanations of the most common configuration options you’ll use.

​
Basic example

A minimal configuration that scrapes Prometheus itself:

​
Key sections

  • global: Default parameters applied to all scrape jobs unless overridden.
  • scrape_configs: Defines scrape jobs (a job is a collection of instances) and how to scrape them.
  • static_configs.targets: A simple list of host:port targets to scrape.

​
Common configuration fields (per job)

Example configuration that overrides some global settings for a specific job:

​
Field summary table

Note: Keep scrape_timeout shorter than or equal to scrape_interval. Timeouts longer than the interval are usually not useful. Prometheus configuration can also include additional sections such as alerting, rule_files, remote_read, remote_write, and storage. Use rule_files to store recording and alerting rules.

​
Example: custom metrics path and multiple targets

​
Add a new job to your Prometheus config

  1. Open the configuration file:
  1. Add a new job under scrape_configs. Minimal example:
  1. Save the file.

​
Validate and reload configuration

Prometheus does not automatically pick up YAML changes. First validate the file to catch syntax problems:
Common ways to apply the new configuration:
  • HTTP reload endpoint (recommended): ask Prometheus to reload configuration without restarting:
  • Graceful reload by sending a signal to the process:
Find the process ID with pidof prometheus or pgrep prometheus. When Prometheus is managed by systemd, using signals may be less reliable.
  • Restart the systemd service:
Some environments support systemctl reload prometheus for a graceful reload if the unit file allows it. Use the service name your system provides.
If you run Prometheus in the foreground (for example, ./prometheus), stopping it with Ctrl+C and starting it again will apply the new configuration. For systemd-managed instances, prefer systemctl restart prometheus or the HTTP reload endpoint.

​
Verify targets in the Prometheus UI

  1. Open the Prometheus UI (default: http://localhost:9090).
  2. Navigate to Status → Targets. This page shows configured targets and their current scrape status.
  3. Query the up metric to check target health. Examples:
A value of 1 means the target is up and being scraped; 0 means it is down.

​
Troubleshooting tips

  • If a target shows as DOWN on the Targets page:
    • Confirm the exporter is running and listening on the expected host:port.
    • Test connectivity locally with curl http://<host>:<port><metrics_path>.
    • Check Prometheus server logs for scrape errors.
  • If promtool check config fails, fix YAML formatting and re-run the tool before reloading.
  • When using basic_auth or TLS, verify certificates and credentials match the exporter configuration.

​
Summary

  • Define targets and jobs in /etc/prometheus/prometheus.yml.
  • Use scrape_interval, scrape_timeout, metrics_path, and scheme to control scraping behavior.
  • Validate changes with promtool check config and reload Prometheus using the HTTP reload endpoint, SIGHUP, or systemctl restart/reload.
  • Confirm scrapes via the Prometheus web UI (Status → Targets) or by querying the up metric.

Watch Video

Practice Lab