Prometheus 리레이블링: 수집 대상과 샘플 선별하기

Prometheus 리레이블링으로 스크레이프 대상을 선택하고 레이블을 정리합니다. Kubernetes 어노테이션, 샤딩, 저장 직전 샘플 제외 예제를 살펴봅니다.

모범 사례
Prometheus 수집 대상 검색과 메트릭 처리 그림

Kubernetes Pod가 /metrics를 노출합니다. Prometheus에서 접속할 수 있지만, 수집을 허용한 Pod만 스크레이프하고 특정 메트릭은 저장하지 않으려면 어떻게 해야 할까요? 수집 대상은 HTTP 요청을 보내기 전에 고르고, 응답에 들어 있는 샘플은 요청이 끝난 뒤에 걸러냅니다.

Prometheus 리레이블링은 처리 단계별로 레이블을 바꾸거나 대상을 걸러내는 기능입니다. 서비스 디스커버리 결과, 로컬 저장소, 원격 전송 데이터 중 어디에서 무엇을 빼야 하는지부터 정하면 설정 위치가 분명해집니다.

어느 단계에 규칙을 적용할까

설정 적용 시점 할 수 있는 일
스크레이프 작업의 relabel_configs 대상을 발견한 뒤, 스크레이프 전 대상 선택, 접속 주소 수정, 발견 메타데이터를 일반 레이블로 복사
metric_relabel_configs 스크레이프 후, 수집 데이터 저장 직전 샘플 필터링과 레이블 변경
write_relabel_configs 외부 레이블을 적용한 뒤, 특정 Remote Write 대상으로 전송하기 전 로컬 저장은 유지하면서 원격으로 보낼 데이터 선택
alert_relabel_configs 외부 레이블을 적용한 뒤, Alertmanager로 보내기 전 알림을 걸러내거나 레이블 정리

metric_relabel_configs로 샘플을 버려도 HTTP 요청과 응답 파싱은 이미 이루어졌습니다. up처럼 Prometheus가 자동으로 생성하는 시계열에도 이 규칙이 적용되지 않습니다. 따라서 up이 1이어도 찾는 메트릭이 저장되었는지는 별도로 확인해야 합니다. Prometheus 구성 문서(영어)

대상 하나를 따라가며 레이블 확인하기

규칙은 작성한 순서대로 적용됩니다. Kubernetes Pod를 발견하는 작업에서 __address__는 접속 주소, __scheme__과 __metrics_path__는 프로토콜과 경로입니다. __meta_kubernetes_namespace 같은 값은 서비스 디스커버리가 제공합니다. 쿼리에서 쓸 메타데이터는 일반 레이블로 복사합니다. 대상 리레이블링이 끝나면 디스커버리 메타데이터는 제거됩니다. 접속 주소 같은 내부 필드 __*는 공개 대상 레이블에 포함되지 않습니다. 중간 결과는 __tmp 접두사를 붙여 보관할 수 있습니다. instance를 설정하지 않으면 최종 __address__가 사용됩니다. 샘플 리레이블링에서는 __name__으로 메트릭 이름을 참조할 수 있습니다.

relabel_configs:
  - source_labels: [__meta_kubernetes_namespace]
    separator: ';'
    regex: '(production|staging)'
    replacement: '$1'
    target_label: env
    action: replace

이 규칙은 네임스페이스가 production 또는 staging과 완전히 일치할 때만 env에 값을 씁니다. 다른 대상은 그대로 통과합니다. Prometheus는 RE2 정규식으로 입력 전체를 비교합니다. 없는 레이블은 빈 문자열로 처리하고, 여러 값은 기본적으로 세미콜론으로 연결합니다. 기본 동작은 replace, 기본 패턴은 (.*), 기본 치환 값은 $1입니다. 리레이블링 설정(영어)

작업에 맞는 동작 고르기

동작 적용 방식
keep / drop 연결한 값이 정규식과 일치하는지 확인합니다. keep은 불일치, drop은 일치하는 항목을 제외합니다.
replace 정규식이 일치하면 치환 결과를 대상 레이블에 씁니다.
labelkeep / labeldrop 레이블 이름을 비교합니다. 일치하는 이름만 남기거나, 일치하는 이름을 지웁니다.
labelmap 이름이 일치하는 레이블 값을 새 이름으로 복사합니다. 이 단계에서 원본은 남습니다.
hashmod 연결한 값을 해시한 뒤, 양수로 나눈 나머지를 대상 레이블에 씁니다.
keepequal / dropequal source_labels를 연결한 값과 target_label의 현재 값을 비교해, 정확히 같을 때 남기거나 제외합니다.
lowercase / uppercase 연결한 값을 소문자 또는 대문자로 바꾸고 대상 레이블에 씁니다.

production 대상만 수집하려면 다음 규칙을 씁니다. 이 규칙은 레이블 값을 바꾸지 않습니다.

- source_labels: [__meta_kubernetes_namespace]
  regex: 'production'
  action: keep

Pod 이름이 쿼리에 필요하면 pod에 복사합니다. Pod 하나에 메트릭을 내보내는 엔드포인트가 여러 개라면 instance를 모두 Pod 이름으로 바꿨을 때 서로 다른 대상을 구분하지 못할 수 있습니다.

- source_labels: [__meta_kubernetes_pod_name]
  target_label: pod
  regex: '(.*)'
  replacement: '$1'
  action: replace

Kubernetes에서 발견한 레이블은 실제로 조회에 사용할 이름만 복사합니다.

- regex: '__meta_kubernetes_pod_label_(app|team)'
  replacement: '$1'
  action: labelmap

내부 레이블이 제거된 뒤에도 app과 team이 남습니다. 정규식을 넓게 쓰면 자주 바뀌는 빌드 ID까지 복사하거나 기존 레이블을 덮어쓸 수 있습니다. 아래 규칙을 적용하기 전에는 레이블을 지운 뒤에도 메트릭 이름과 나머지 레이블로 각 시계열을 구분할 수 있는지 확인합니다.

- regex: 'build_sha|request_id'
  action: labeldrop

두 샤드에 수집 작업 나누기

같은 후보를 두 샤드로 나누려면 한쪽에서 나머지 0, 다른 쪽에서 1을 남깁니다. 대상은 어느 한쪽에 속하지만 샤드별 개수가 같다는 보장은 없습니다.

- source_labels: [__address__]
  modulus: 2
  target_label: __tmp_hash
  action: hashmod
- source_labels: [__tmp_hash]
  regex: '0'
  action: keep

앞에 적용하는 규칙을 두 샤드에서 동일하게 유지해야 같은 값을 해시합니다. 두 복제본이 같은 나머지를 선택하면 같은 대상을 수집합니다. 고가용성이 필요해 겹쳐 수집하는 경우와 작업을 분할하는 경우에 이 차이가 중요합니다.

어노테이션으로 대상과 포트 선택하기

Kubernetes Pod 디스커버리를 쓰는 작업에 다음 규칙을 넣습니다. 첫 번째 규칙은 수집을 허용한 Pod만 남깁니다. 두 번째 규칙은 포트 어노테이션이 숫자이고 주소가 예상한 호스트명, IPv4 또는 대괄호로 감싼 IPv6 형식일 때 포트를 바꿉니다. 일치하지 않으면 원래 주소를 사용합니다.

- source_labels: [__meta_kubernetes_pod_annotation_prometheus_io_scrape]
  regex: 'true'
  action: keep
- source_labels: [__meta_kubernetes_pod_annotation_prometheus_io_port, __address__]
  regex: '([0-9]+);(\[[^]]+\]|[^:]+)(:[0-9]+)?'
  replacement: '${2}:${1}'
  target_label: __address__

Guance에도 메트릭을 전송하는 경우 DataKit의 KubernetesPrometheus 수집기(영어)를 별도로 설정합니다. 어노테이션 기반 검색을 사용할 때는 해당 옵션을 활성화하고 수집기가 요구하는 어노테이션과 선택 조건을 확인합니다.

샘플을 제외하고 결과 확인하기

저장하지 않아도 되는 메트릭을 먼저 특정하고 정확한 이름으로 필터링합니다. 다음 예시는 http_request_debug_total 샘플을 제외합니다.

metric_relabel_configs:
  - source_labels: [__name__]
    regex: 'http_request_debug_total'
    action: drop

설정을 다시 불러오기 전에 검사합니다. 두 번째 명령은 지정한 작업의 디스커버리를 실행합니다. 발견 소스에 접근할 수 있는 환경에서 실제 작업 이름을 사용합니다. promtool 문서(영어)

promtool check config prometheus.yml
promtool check service-discovery prometheus.yml kubernetes-pods

Prometheus UI에서 Service Discovery와 Targets를 비교합니다. 대상이 있고 up이 1이면 남겨 둔 메트릭과 걸러낸 메트릭을 각각 조회합니다. SIGHUP을 보내거나, 라이프사이클 API를 활성화한 서버에 HTTP POST /-/reload를 호출하면 구성을 다시 불러올 수 있습니다.

자주 묻는 질문

정규식과 일치하지 않는 이유는 무엇인가요? 실제로 연결된 값을 확인합니다. 문자열 전체와 비교하므로 부분 일치가 필요하면 앞뒤에 .*를 명시합니다.

$1이 빈 값이 되는 이유는 무엇인가요? 정규식에 해당 캡처 그룹이 있어야 합니다. 그룹 번호 뒤에 문자를 이어 붙일 때는 ${1}, 달러 기호 자체를 넣을 때는 $$를 사용합니다.

이미 저장된 데이터도 바뀌나요? 기존 시계열의 레이블은 그대로입니다. 다음 스크레이프부터 새 레이블 조합으로 시계열이 만들어질 수 있고, 변경 전후를 포함하는 쿼리에는 두 조합이 모두 나타날 수 있습니다.

관련 글 · Helm으로 Kubernetes에 Prometheus 배포하기 · Prometheus 모니터링 가이드

맞춤형 플랜 상담

문의하기

커뮤니티 가입

WeChat으로 스캔하여
커뮤니티에 가입하세요

Guance 사용해 보기

온라인에서 바로 시작하고 사용한 만큼만 결제하세요.

시작하기

Guance 요금제 선택

코드 저장소