From 88cc266c5827ea0a04fdff1a296235dd210a59f0 Mon Sep 17 00:00:00 2001 From: Julius Volz Date: Mon, 21 Jun 2021 16:16:03 +0200 Subject: [PATCH] Migrate HTTP SD docs from docs repo (#8972) See discussion in https://github.com/prometheus/docs/pull/1975 Signed-off-by: Julius Volz --- docs/disabled_features.md | 4 +- docs/http_sd.md | 96 +++++++++++++++++++++++++++++++++++++++ docs/management_api.md | 2 +- docs/migration.md | 2 +- docs/stability.md | 2 +- 5 files changed, 101 insertions(+), 5 deletions(-) create mode 100644 docs/http_sd.md diff --git a/docs/disabled_features.md b/docs/disabled_features.md index 4066327a3..a9021383f 100644 --- a/docs/disabled_features.md +++ b/docs/disabled_features.md @@ -1,6 +1,6 @@ --- title: Disabled Features -sort_rank: 10 +sort_rank: 11 --- # Disabled Features @@ -52,4 +52,4 @@ The remote write receiver allows Prometheus to accept remote write requests from [OpenMetrics](https://github.com/OpenObservability/OpenMetrics/blob/main/specification/OpenMetrics.md#exemplars) introduces the ability for scrape targets to add exemplars to certain metrics. Exemplars are references to data outside of the MetricSet. A common use case are IDs of program traces. -Exemplar storage is implemented as a fixed size circular buffer that stores exemplars in memory for all series. Enabling this feature will enable the storage of exemplars scraped by Prometheus. The flag `storage.exemplars.exemplars-limit` can be used to control the size of circular buffer by # of exemplars. An exemplar with just a `traceID=` uses roughly 100 bytes of memory via the in-memory exemplar storage. If the exemplar storage is enabled, we will also append the exemplars to WAL for local persistence (for WAL duration). \ No newline at end of file +Exemplar storage is implemented as a fixed size circular buffer that stores exemplars in memory for all series. Enabling this feature will enable the storage of exemplars scraped by Prometheus. The flag `storage.exemplars.exemplars-limit` can be used to control the size of circular buffer by # of exemplars. An exemplar with just a `traceID=` uses roughly 100 bytes of memory via the in-memory exemplar storage. If the exemplar storage is enabled, we will also append the exemplars to WAL for local persistence (for WAL duration). diff --git a/docs/http_sd.md b/docs/http_sd.md new file mode 100644 index 000000000..8a2bbf18c --- /dev/null +++ b/docs/http_sd.md @@ -0,0 +1,96 @@ +--- +title: HTTP SD +sort_rank: 7 +--- + +# Writing HTTP Service Discovery + +Prometheus provides a generic [HTTP Service Discovery](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#http_sd_config), +that enables it to discover targets over an HTTP endpoint. + +The HTTP Service Discovery is complimentary to the supported service +discovery mechanisms, and is an alternative to [File-based Service Discovery](https://prometheus.io/docs/guides/file-sd/#use-file-based-service-discovery-to-discover-scrape-targets). + +## Comparison between File-Based SD and HTTP SD + +Here is a table comparing our two generic Service Discovery implementations. + +| Item | File SD | HTTP SD | +| ---- | ------- | ------- | +| Event Based | Yes, via inotify | No | +| Update frequency | Instant, thanks to inotify | Following refresh_interval | +| Format | Yaml or JSON | JSON | +| Transport | Local file | HTTP/HTTPS | +| Security | File-Based security | TLS, Basic auth, Authorization header, OAuth2 | + +## Requirements of HTTP SD endpoints + +If you implement an HTTP SD endpoint, here is a few requirements you should be +aware of. + +The response is consumed as is, unmodified. On each refresh interval (default: 1 +minute), Prometheus will perform a GET request to the HTTP SD endpoint. The GET +request contains a `X-Prometheus-Refresh-Interval-Seconds` HTTP header with the +refresh interval. + +The SD endpoint must answer with an HTTP 200 response, with the HTTP Header +`Content-Type: application/json`. The answer must be UTF-8 formatted. +If no targets should be transmitted, HTTP 200 must also be emitted, with +an empty list `[]`. Target lists are unordered. + +Prometheus caches target lists. If an error occurs while fetching an updated +targets list, Prometheus keeps using the current targets list. The targets list +is not saved across restart. + +The whole list of targets must be returned on every scrape. There is no support +for incremental updates. A Prometheus instance does not send its hostname and it +is not possible for a SD endpoint to know if the SD requests is the first one +after a restart or not. + +The URL to the HTTP SD is not considered secret. The authentication, and any API +keys should be passed with the appropriate authentication mechanisms. Prometheus +supports TLS authentication, basic authentication, OAuth2, and authorization +headers. + +## HTTP_SD format + +```json +[ + { + "targets": [ "", ... ], + "labels": { + "": "", ... + } + }, + ... +] +``` + + +Examples: + +```json +[ + { + "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" + } + } +] +``` diff --git a/docs/management_api.md b/docs/management_api.md index 0ac0da7ba..4bdfddcd0 100644 --- a/docs/management_api.md +++ b/docs/management_api.md @@ -1,6 +1,6 @@ --- title: Management API -sort_rank: 7 +sort_rank: 8 --- # Management API diff --git a/docs/migration.md b/docs/migration.md index a7aaac5b2..49e9aee8b 100644 --- a/docs/migration.md +++ b/docs/migration.md @@ -1,6 +1,6 @@ --- title: Migration -sort_rank: 8 +sort_rank: 9 --- # Prometheus 2.0 migration guide diff --git a/docs/stability.md b/docs/stability.md index 532d8fd50..7bb8e3184 100644 --- a/docs/stability.md +++ b/docs/stability.md @@ -1,6 +1,6 @@ --- title: API Stability -sort_rank: 9 +sort_rank: 10 --- # API Stability Guarantees