HTTP 기반 서비스 디스커버리

HTTP 기반 서비스 디스커버리 (HTTP service discovery)

HTTP 기반 서비스 디스커버리(SD)는 Prometheus가 스크랩할 타깃 목록을 얻기 위해 사용하는 범용 인터페이스예요. 타깃 목록(DNS, Kubernetes 등)을 반환하는 HTTP 엔드포인트의 가용성에 기반해요. 이 문서는 HTTP SD의 두 가지 응답 형식(v2와 v1)을 설명해 드려요.

HTTP SD v2는 더 풍부하고 유연한 형식으로, 타깃 중심 그룹핑 형식과 시리즈 중심 형식을 모두 지원해요. 반면 v1은 원래 형식이에요. v1과 v2 사이에는 미묘한 의미 차이가 있어서, 자세한 내용은 각 섹션을 참고해야 해요. Prometheus 3.0부터 v1은 더 이상 권장되지 않고 v2를 사용하는 것이 좋아요.

출처: 문서

본문

HTTP 서비스 디스커버리 (HTTP service discovery)

HTTP 기반 서비스 디스커버리는 Prometheus가 스크랩할 타깃 목록을 얻는 데 사용하는 범용 인터페이스예요. 타깃 목록(예: DNS, Kubernetes 등)을 반환하는 HTTP 엔드포인트의 가용성에 기반해요.

HTTP 기반 서비스 디스커버리는 Prometheus 구성에서 HTTP Service Discovery 구성의 사용을 요구해요.

HTTP 기반 서비스 디스커버리는 service 디스커버리 프로토콜로 서비스를 편리하게 발견하는 데 사용할 수 있어요. HTTP 서비스 디스커버리 엔드포인트의 응답에는 두 가지 형식이 지원돼요.

SD format v2: HTTP SD v2의 타깃 그룹핑 형식에서 사용하는 형식.
SD format v1: 원래 형식.

v1과 v2 형식 사이에는 약간의 미묘한 의미 차이가 있어요. 자세한 내용은 관련 섹션을 참조하세요.

HTTP SD v2 (SD format v2)

HTTP SD v2는 더 풍부하고 유연한 형식으로, 타깃 중심 그룹핑 형식과 시리즈 중심 형식을 모두 지원해요. 최상위 객체 타입은 SD 객체 타입과 target 객체 타입이에요.

HTTP SD v2는 엔드포인트에 Accept HTTP 헤더로 값 application/x.y.z를 사용해 요청해요.

HTTP SD v2 엔드포인트의 응답은 하나 이상의 SD 객체를 포함할 수 있으며, 각각은 SD 객체 타입과 SD 객체 식별자를 가져요.

SD 객체는 특정 공통 속성을 공유하는 타깃의 그룹을 나타내요. SD 객체의 그룹핑은 유연한 타깃 관리를 가능하게 해요.

SD 객체 (SD object)

uid: SD 객체의 고유 문자열 식별자. 특정 Prometheus 인스턴스 내에서 고유할 수 있어요.
target_group (선택): 주어진 SD 객체의 타깃 그룹핑.
maybe_map_keys (선택): 그럴 수 있는 SD 객체의 어떤 엔티티든 maybe_maplabels 배열의 맵 키 타입.
maybe_map_labels (선택): 타깃의 라벨이 될 자격이 있는 맵 키.
series_mapping (선택): 각 series_t 객체에서 시리즈 이름을 메트릭 이름에 매핑하는 선택적 사전.
sparse_histograms_supported (선택): 특정 응답 시리즈에서 네이티브/명시적 히스토그램을 요청. 기본값은 false.
provided_series_primary_timestamp (선택): 주어진 시리즈에 기본 타임스탬프(primary timestamp)가 있으면 true로 설정.
default_tsdb_type (선택): 샘플을 TSDB에 수집할 때 사용할 기본 타입.
native_histogram_support_type (선택): 기본 네이티브 히스토그램 지원 타입.
target_group_reference (선택): 다른 타깃 그룹에 대한 참조.
dns_name (선택): SD 객체와 연관된 DNS 이름.
suggested_ (선택): suggested_로 시작하는 라벨 이름은 SDK가 제안한 라벨.
tsdb_options (선택): 각 객체에 대한 TSDB 옵션.
milestones ...

시리즈 이름은 series_mapping과 metric_name 필드에서 사용돼요.

현재 Prometheus 버전은 1에서 65535 사이의 값을 가진 sd_object uid를 지원해요. 하지만 uuid(RFC 4122)와 콜론, 쉼표, 공백이 없는 임의의 문자열을 사용하는 것이 권장돼요. SD v2 시리즈에 대한 더 많은 내용은 여기에서 읽을 수 있어요.

HTTP SD v2 - 시리즈 쿼리하기 (querying Prometheus for series)

현재 로컬 TSDB 내에서 주어진 메트릭 패밀리에 대한 시리즈 목록(시리즈 중심 모드 또는 SM)을 쿼리하려면 실행하세요:

curl -s -H 'Accept: application/x.y.z; version=2.0' 'http://localhost:9090/api/v1/series?limit=...'

이 엔드포인트는 현재 로컬 TSDB에서 주어진 메트릭 패밀리(들)에 대한 시리즈를 검색해요.

응답은 JSON 배열로, 각 항목은 targets(target 객체 배열)와 다른 필드를 가진 시리즈 객체이며 다음 형식을 취해요:

[
  {
    "targets": [
      {
        "target": "something",
        "labels": {
            "__meta_http_sd_label1": "value1",
            "__meta_http_sd_label2": "value2"
        }
      }
    ]
  }
]

HTTP SD v2는 엔드포인트가 타깃의 대안으로 시리즈를 생성하게 해 줘요. 이는 외부에서 유지보수되는 시리즈의 소비를 단순화할 수 있어요. 하지만 그것이 기본 사용 사례는 아니에요. 대부분의 경우 타깃과 라벨 이름/값 쌍은 외부 시스템에서 오고, Prometheus 타깃과 라벨로 변환돼요.

HTTP SD v2 타깃은 현재 다음 필드를 지원해요.

target: 타깃 주소. IP 또는 호스트네임일 수 있음. 선택적 스킴. 기본값은 http(또는 그룹에 path_prefix가 있으면 https)...
series: 이 타깃에 주어진 시리즈. 지정되면 이 타깃에 대해 생성된 다른 시리즈를 재정의함.
labels: 타깃에 전달되는 추가 메타데이터 라벨. 이 라벨은 http_sd_config 부모로 전달되어 타깃의 라벨 집합에 추가될 수 있음.
action (선택): replace 값만 가질 수 있음.

이 타깃 그룹들은 특정 스키마를 따르며, 여기에 문서화돼 있어요.

기본값 (Defaults)

GOMAXPROCS, GOMEMLIMIT
네트워크 요청: 및 기타 네트워크 쓰기

HTTP SD v1 (SD format v1)

HTTP 기반 서비스 디스커버리 /docs/prometheus/latest/configuration/configuration/#http_sd_config는 스크랩해야 할 타깃 목록을 제공하는 JSON 문서를 반환해요. 이 JSON 문서를 기반으로 다음 객체와 기능이 구축돼요.

응답 형식은 다음과 같아요:

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

targets 속성은 다음 형식을 지원해요.

hostname:port 조합. 예: localhost:9090 또는 db.mycompany.com:9100
scheme://hostname:port 조합. 예: http://localhost:9090

다음은 간단한 데모 응답이에요:

[
  {
    "targets": [
      "192.168.0.1:9100",
      "192.168.0.2:9100"
    ],
    "labels": {
      "env": "prod",
      "job": "myapp"
    }
  }
]

Prometheus 2.40부터 HTTP SD v1 응답의 타깃... v1 응답은 metabdoc 형식일 수 있어요.

Prometheus 2.45부터 HTTP SD v1 응답의 타깃에 HTTPS 스킴이 포함될 수 있어요.

Prometheus 3.0부터 HTTP SD v1 응답의 타깃에 HTTPS 스킴이 포함될 수 있어요. v1 응답은 metabdoc 형식일 수 있어요. 일부 라벨 변경이 있어요.

HTTP SD v1 메타데이터 기반 응답(metabdoc).

폐기와 마이그레이션 (Deprecation and migration)

Prometheus 3.0부터 HTTP SD v1 형식은 더 이상 사용되지 않으며(deprecated), HTTP SD v2를 사용하는 것이 권장돼요. Prometheus 3.0부터 HTTP SD v1 형식은 더 이상 권장되지 않고 v2 사용을 권장해요.

v1 형식은 더 풍부한 기능 때문에 더 이상 사용되지 않고 v2 사용이 권장돼요. 하지만 v1은 여전히 지원되며 제거 계획은 당장 없어요.

예제 (Examples)

v1과 v2 형식 사이에는 미묘한 의미 차이가 있으므로, 자세한 내용은 관련 섹션을 참조하세요.

더 알아보기 (Learn more)

구성 (Configuration) — http_sd_config 옵션
프로메테우스 에이전트 — 에이전트 모드
설치 (Installation) — 설치와 실행
페더레이션 (Federation) — 타임시리즈 공유