다중 대상 계측하기: 여러 스크레이프를 하나의 엔드포인트로

다중 대상 계측하기: 여러 스크레이프를 하나의 엔드포인트로 (Instrumenting many targets: single scrape endpoint)

이 문서는 하나의 Prometheus 스크레이프 엔드포인트로 여러 대상을 수집하는 패턴, 즉 "다중 대상 엑스포터(multi-target exporter)" 패턴을 보여줘요. 대표적인 예가 blackbox exporter입니다. Prometheus가 단일 엑스포터에 스크레이프 요청을 보내면, 엑스포터가 쿼리 문자열의 매개변수(예: target)를 보고 실제 측정하려는 대상에 대한 메트릭을 반환합니다.

이 패턴은 스크레이프할 엔드포인트 수가 많거나, 대상이 Prometheus에서 직접 접근할 수 없는 위치에 있을 때(예: 각 라우터의 SNMP, 각 웹사이트의 HTTP) 유용해요. params와 relabel_configs를 조합해 각 대상별로 고유한 라벨과 매개변수를 넣습니다.

출처: 문서

본문

패턴의 작동 방식

일반적으로 http_2xx 같은 프로브 결과를 노출하는 blackbox exporter를 예로 들어 보겠습니다. Prometheus는 엑스포터에 ?target=example.com 같은 쿼리 매개변수와 함께 요청을 보내고, 엑스포터는 그 대상으로 실제 조사를 수행한 뒤 결과 메트릭(probe_success 등)을 반환합니다.

스크레이프 설정에서 각 스크레이프 대상이 곧 "조사할 대상"이 되는 것이 아니라, 하나의 엑스포터라는 점이 핵심입니다. Prometheus 설정은 다음과 같이 구성합니다:

scrape_configs:
  - job_name: 'blackbox'
    metrics_path: /probe
    params:
      module: [http_2xx]
    static_configs:
      - targets:
          - example.com
          - prometheus.io
    relabel_configs:
      - source_labels: [__address__]
        target_label: __param_target
      - source_labels: [__param_target]
        target_label: target
      - target_label: __address__
        replacement: 127.0.0.1:9115

단계별 설명

  • metrics_path: /probe — blackbox exporter의 프로브 엔드포인트를 호출합니다.
  • params: { module: [http_2xx] } — 프로브에 사용할 모듈을 쿼리 매개변수로 전달합니다.
  • static_configs.targets — 실제 조사할 대상 목록(예: 검사할 웹사이트/호스트).
  • relabel_configs:
    • __address__를 __param_target으로 복사 → 엑스포터가 ?target= 매개변수로 이 값을 받습니다.
    • __param_target을 target 라벨로 저장 → 메트릭에서 어떤 대상을 조사했는지 식별.
    • __address__를 엑스포터 주소(127.0.0.1:9115)로 교체 → 요청이 항상 엑스포터로 감.

이렇게 하면 하나의 blackbox exporter 인스턴스로 수백 개의 대상(웹사이트, TCP 엔드포인트 등)을 조사할 수 있습니다. 결과 메트릭에는 target 라벨이 붙어 대상별로 구분됩니다.

주의할 점

  • 엑스포터 쪽에서 비동기 조사(스크레이프와 조사를 분리)를 지원하면 부하를 줄일 수 있습니다.
  • params의 module은 대상별로 다르게 하고 싶으면 relabel_configs에서 __param_module을 조작해 대상마다 다른 모듈을 지정할 수도 있습니다.

더 알아보기 (Learn more)