How to add a Prometheus scrape config

Adding a Prometheus scrape config tells Prometheus about a metrics endpoint that should feed time series into queries, alerts, and dashboards. Use it when a new exporter, application, or internal service already exposes metrics and needs to appear as a named job with predictable labels.

Prometheus stores scrape jobs in the active YAML configuration file under scrape_configs. A static job normally sets a job_name, optional scrape timing or path settings, and one or more static_configs target groups; each target is written as host and optional port, while scheme and metrics_path stay as separate job settings.

A local Prometheus self-scrape target keeps validation reproducible without a second host. Replace that target with the exporter or application endpoint Prometheus can reach from its own network path, validate the full file with promtool, reload the running server, and confirm the new job returns up and at least one metric.

Steps to add a Prometheus scrape config:

Test the metrics endpoint from the Prometheus host.

$ curl --silent --show-error http://127.0.0.1:9090/metrics
# HELP prometheus_build_info A metric with a constant '1' value labeled by version, revision, branch, goversion from which prometheus was built, and the goos and goarch for the build.
# TYPE prometheus_build_info gauge
prometheus_build_info{version="3.5.4"} 1
##### snipped #####

Replace the local URL with the exporter or application metrics endpoint that Prometheus will scrape. The endpoint must answer from the Prometheus host, not only from an operator workstation.
Related: How to test a Prometheus metrics endpoint

Open the active Prometheus configuration file.
```
$ sudo vi /etc/prometheus/prometheus.yml
```
Use the path from the running --config.file flag when Prometheus was installed outside the package default.

Add the new scrape job under scrape_configs.

scrape_configs:
  - job_name: prometheus
    static_configs:
      - targets:
          - 127.0.0.1:9090

  - job_name: local-prometheus
    metrics_path: /metrics
    static_configs:
      - targets:
          - 127.0.0.1:9090
        labels:
          role: monitoring
          service: prometheus

Keep existing jobs in place, choose a stable job_name for alerts and dashboards, and write targets without http:// or https:// prefixes.
Tool: Prometheus Scrape Config Generator

Check the updated configuration with promtool.
```
$ promtool check config /etc/prometheus/prometheus.yml
Checking /etc/prometheus/prometheus.yml
 SUCCESS: /etc/prometheus/prometheus.yml is valid prometheus config file syntax
```
promtool check config validates the complete file, including the added scrape job and any referenced rule files.
Related: How to test Prometheus configuration
Reload Prometheus to apply the scrape job.
```
$ curl --request POST --include http://127.0.0.1:9090/-/reload
HTTP/1.1 200 OK
Date: Sat, 20 Jun 2026 10:27:12 GMT
Content-Length: 0
```
A Lifecycle APIs are not enabled response means the server was not started with --web.enable-lifecycle. Use the service manager to send SIGHUP or reload the managed service instead.

Related: How to reload Prometheus configuration
Related: How to manage the Prometheus service with systemctl

Check the new scrape target state.

$ promtool query instant http://127.0.0.1:9090 'up{job="local-prometheus"}'
up{instance="127.0.0.1:9090", job="local-prometheus", role="monitoring", service="prometheus"} => 1 @[1781951239.576]

Value 1 means the latest scrape succeeded. Value 0 means the job exists, but the target failed its latest scrape.
Related: How to check Prometheus targets

Query a metric from the new scrape job.

$ promtool query instant http://127.0.0.1:9090 'prometheus_build_info{job="local-prometheus"}'
prometheus_build_info{instance="127.0.0.1:9090", job="local-prometheus", role="monitoring", service="prometheus", version="3.5.4"} => 1 @[1781951239.723]

A returned metric with the new job value and static labels confirms the target is not only listed, but also sending samples into Prometheus.
Related: How to run a PromQL query in Prometheus