Prometheus HTTP Service Discovery: Compare, Requirements & JSON Format

1. HTTP SD Overview

Prometheus provides a generic HTTP service discovery that can discover targets at HTTP endpoints.

HTTP service discovery complements other mechanisms and serves as an alternative to file‑based discovery.

2. Comparison between File SD and HTTP SD

Based on events : File SD – yes (via inotify); HTTP SD – no.

Update frequency : File SD – immediate via inotify; HTTP SD – based on refresh_interval.

Format : File SD – YAML or JSON; HTTP SD – JSON.

Transport : File SD – local files; HTTP SD – HTTP/HTTPS.

Security : File SD – file‑based security; HTTP SD – TLS, Basic auth, Authorization header, OAuth2.

3. Requirements for HTTP SD Endpoints

If you implement an HTTP SD endpoint, note the following requirements.

Responses are used as‑is. At each refresh interval (default 1 minute), Prometheus sends a GET request with the header X-Prometheus-Refresh-Interval-Seconds.

The endpoint must return HTTP 200 with header Content-Type: application/json and UTF‑8 charset. If the target list is empty, it must still return HTTP 200 with an empty list []. The target list is unordered.

Prometheus caches the current target list; on errors it continues using the cached list. The list is not persisted across restarts.

Each request must return the full target list; incremental updates are not supported. The SD endpoint cannot know whether the request follows a restart.

The URL should consider security; authentication and API keys must be passed via appropriate mechanisms. Prometheus supports TLS, basic auth, OAuth2, and authorization headers.

4. HTTP SD JSON Format

[
  {
    "targets": ["<host>", ...],
    "labels": {
      "<labelname>": "<labelvalue>", ...
    }
  },
  ...
]

Example:

[
    {
        "targets": ["10.0.10.2:9100","10.0.10.3:9100","10.0.10.4:9100","10.0.10.5:9100"],
        "labels": {
            "__meta_datacenter": "london",
            "__meta_prometheus_job": "node"
        }
    },
    {
        "targets": ["10.0.40.2:9100","10.0.40.3:9100"],
        "labels": {
            "__meta_datacenter": "london",
            "__meta_prometheus_job": "alertmanager"
        }
    },
    {
        "targets": ["10.0.40.2:9093","10.0.40.3:9093"],
        "labels": {
            "__meta_datacenter": "newyork",
            "__meta_prometheus_job": "alertmanager"
        }
    }
]

Conclusion

Using Prometheus HTTP SD makes it easy to collect service lists from Spring Cloud, eliminating the need for Eureka or Nacos users to emulate Consul interfaces.