スクレイプ設定とリラベリング

한국어 원문으로 표시합니다.

목표

프로메테우스 스크레이프 설정을 처음부터 끝까지 직접 쓰고, 그 설정이 실제 클러스터의 파드를 어떻게 고르는지 확인합니다. 끝나면 남의 prometheus.yml 을 보고 어떤 타깃이 살아남고 어떤 메트릭이 버려지는지 말할 수 있습니다.

왜 중요한가

스크레이프 설정은 프로메테우스에서 유일하게 "무엇을 볼지"를 결정하는 자리입니다. 그 뒤의 모든 쿼리와 알림은 여기서 살아남은 데이터만 다룹니다. 릴레이블링이 어렵게 느껴지는 이유는 문법이 아니라 두 단계가 서로 다른 시점에 동작하기 때문입니다. relabel_configs 는 스크레이프 전에 타깃 목록을 다루고, metric_relabel_configs 는 스크레이프 후에 들어온 메트릭을 다룹니다. 앞 단계에서 버린 타깃은 요청 자체가 나가지 않으므로 비용이 0 이고, 뒤 단계에서 버린 메트릭은 이미 네트워크와 파싱 비용을 치른 뒤입니다. 이 차이가 대규모 클러스터에서 프로메테우스의 생사를 가릅니다. 가드레일도 같은 맥락입니다. sample_limit 이 없으면 카디널리티가 터진 서비스 하나가 전체 모니터링을 멈춥니다.

단계

/root/pca-scrape/prometheus.yml 을 만들고 global 블록을 씁니다. scrape_interval: 15s, evaluation_interval: 30s, scrape_timeout: 10s, 그리고 external_labels 아래 cluster: homelab.
scrape_configs 리스트의 첫 번째 항목에 job_name: prometheus-self 를 만들고 metrics_path: /metrics, static_configs 의 targets 에 localhost:9090 하나를 넣습니다.
두 번째 항목에 job_name: checkout-api 를 만들고 scrape_interval: 30s, scrape_timeout: 20s, sample_limit: 20000, label_limit: 24, label_value_length_limit: 256 을 넣습니다.
세 번째 항목에 job_name: kubernetes-pods 를 만들고 kubernetes_sd_configs 에 role: pod 를 지정한 뒤, namespaces.names 에 pca-scrape 하나만 넣어 감시 범위를 좁힙니다.
세 번째 잡의 relabel_configs 에 규칙 세 개를 넣습니다. (a) action: keep, source_labels: [__meta_kubernetes_pod_annotation_prometheus_io_scrape], regex: "true" (b) action: replace, source_labels: [__meta_kubernetes_pod_ip, __meta_kubernetes_pod_annotation_prometheus_io_port], target_label: __address__, replacement: '$1:$2' (c) action: replace, source_labels: [__meta_kubernetes_namespace], target_label: namespace.
같은 잡에 action: labelmap, regex: __meta_kubernetes_pod_label_(.+) 규칙을 추가하고, metric_relabel_configs 에 두 규칙을 넣습니다. (a) action: drop, source_labels: [__name__], regex: 'go_gc_duration_seconds.*|python_gc_.*' (b) action: replace, source_labels: [__name__], regex: 'http_requests_total', target_label: user_id, replacement: ''.
네임스페이스 pca-scrape 를 만들고, 그 안에 컨피그맵 prometheus-config 을 만듭니다. 키 이름은 prometheus.yml 이고 값은 방금 쓴 파일의 내용입니다.
네임스페이스 pca-scrape 에 파드 checkout-api 를 만듭니다. 레이블 app: checkout-api, 어노테이션 prometheus.io/scrape: "true", prometheus.io/port: "8080", prometheus.io/path: "/metrics", 컨테이너 포트는 이름 metrics 에 containerPort: 8080.

참고

kubectl create configmap prometheus-config -n pca-scrape --from-file=prometheus.yml=/root/pca-scrape/prometheus.yml
파드는 kubectl apply -f 로 매니페스트를 적용하는 편이 어노테이션을 넣기 쉽습니다. 이미지는 아무거나 써도 됩니다.
흔한 실수 1: source_labels 를 문자열 하나로 적는 것. 항상 리스트입니다.
흔한 실수 2: 어노테이션 메타 레이블 이름을 prometheus.io/scrape 그대로 쓰는 것. 점과 슬래시는 밑줄이 됩니다.
흔한 실수 3: 파일만 고치고 컨피그맵을 다시 만들지 않는 것. 7단계 채점은 컨피그맵 안의 내용을 읽습니다.

global 블록 쓰기

/root/pca-scrape/prometheus.yml 을 만들고 global 블록을 씁니다. scrape_interval: 15s, evaluation_interval: 30s, scrape_timeout: 10s, 그리고 external_labels 아래 cluster: homelab.

prometheus.yml 최상위의 global 아래에 scrape_interval, evaluation_interval, scrape_timeout 을 넣습니다. external_labels 는 이 프로메테우스가 내보내는 모든 시계열에 붙는 레이블이라 페더레이션이나 원격 저장소에서 인스턴스를 구분하는 데 씁니다.

static_configs 잡 추가

scrape_configs 리스트의 첫 번째 항목에 job_name: prometheus-self 를 만들고 metrics_path: /metrics, static_configs 의 targets 에 localhost:9090 하나를 넣습니다.

scrape_configs 는 리스트입니다. 첫 항목에 job_name 과 static_configs 를 넣으세요. static_configs 는 targets 리스트를 갖는 항목들의 리스트라 대괄호가 두 번 들어갑니다. metrics_path 는 기본값이 있지만 여기서는 명시합니다.

가드레일 거는 잡

두 번째 항목에 job_name: checkout-api 를 만들고 scrape_interval: 30s, scrape_timeout: 20s, sample_limit: 20000, label_limit: 24, label_value_length_limit: 256 을 넣습니다.

sample_limit 은 한 타깃이 주는 샘플 수의 상한이고, 넘으면 그 스크레이프가 통째로 실패합니다. label_limit 과 label_value_length_limit 도 같은 계열의 방어선입니다. scrape_timeout 은 scrape_interval 보다 클 수 없다는 제약을 기억하세요.

kubernetes_sd 로 파드 찾기

세 번째 항목에 job_name: kubernetes-pods 를 만들고 kubernetes_sd_configs 에 role: pod 를 지정한 뒤, namespaces.names 에 pca-scrape 하나만 넣어 감시 범위를 좁힙니다.

kubernetes_sd_configs 도 리스트입니다. role 은 node/service/pod/endpoints/endpointslice/ingress 중 하나이고, 파드의 컨테이너 포트를 직접 긁으려면 pod 입니다. namespaces.names 로 감시 범위를 좁히면 대규모 클러스터에서 SD 부하가 크게 줄어듭니다.

keep 으로 고르고 주소를 재조립

세 번째 잡의 relabel_configs 에 규칙 세 개를 넣습니다. (a) action: keep, source_labels: [__meta_kubernetes_pod_annotation_prometheus_io_scrape], regex: "true" (b) action: replace, source_labels: [__meta_kubernetes_pod_ip, __meta_kubernetes_pod_annotation_prometheus_io_port], target_label: __address__, replacement: '$1:$2' (c) action: replace, source_labels: [__meta_kubernetes_namespace], target_label: namespace.

keep 은 정규식에 매칭되지 '않는' 타깃을 버립니다. 어노테이션 메타 레이블 이름은 점과 슬래시가 밑줄로 바뀐다는 규칙을 기억하세요. 소스 레이블 두 개를 쓰면 값이 세미콜론으로 이어져 정규식에 들어오고, replacement 에서 캡처 그룹으로 다시 조립합니다.

labelmap 과 metric_relabel_configs

같은 잡에 action: labelmap, regex: __meta_kubernetes_pod_label_(.+) 규칙을 추가하고, metric_relabel_configs 에 두 규칙을 넣습니다. (a) action: drop, source_labels: [__name__], regex: 'go_gc_duration_seconds.*|python_gc_.*' (b) action: replace, source_labels: [__name__], regex: 'http_requests_total', target_label: user_id, replacement: ''.

relabel_configs 는 스크레이프 전에 타깃을 다루고, metric_relabel_configs 는 스크레이프 후에 메트릭을 다룹니다. labeldrop 은 레이블 '이름'만 보고 매칭해서 그 잡의 모든 메트릭에서 지워 버리므로, 특정 메트릭에서만 지우려면 replace 로 빈 값을 넣습니다. 빈 값 레이블은 없는 레이블과 같습니다.

설정을 ConfigMap 으로 올리기

네임스페이스 pca-scrape 를 만들고, 그 안에 컨피그맵 prometheus-config 을 만듭니다. 키 이름은 prometheus.yml 이고 값은 방금 쓴 파일의 내용입니다.

kubectl create configmap 의 --from-file 은 키=경로 형태로 키 이름을 지정할 수 있습니다. 파일을 고친 뒤에는 컨피그맵을 다시 만들어야 반영됩니다. 실제 운영에서는 config-reloader 사이드카가 이 갱신을 감지해 프로메테우스에 리로드를 트리거합니다.

keep 규칙이 살려 낼 파드 만들기

네임스페이스 pca-scrape 에 파드 checkout-api 를 만듭니다. 레이블 app: checkout-api, 어노테이션 prometheus.io/scrape: "true", prometheus.io/port: "8080", prometheus.io/path: "/metrics", 컨테이너 포트는 이름 metrics 에 containerPort: 8080.

앞에서 쓴 keep 규칙과 address 재조립 규칙이 이 파드를 통과시키는지 생각하면서 어노테이션 값을 정하세요. 값이 문자열 true 와 정확히 같아야 하고, 포트 어노테이션 값이 컨테이너 포트와 일치해야 합니다. labelmap 규칙이 옮길 파드 레이블도 하나 붙입니다.