# 메트릭 개요 > 검토: 2026년 9월 13일. 예제는 Prometheus 3.14.0 도구로 로컬 검증했으며 클러스터·클라우드 배포는 수행하지 않았습니다. ## 목차 - [메트릭 기본 개념](#메트릭-기본-개념) - [메트릭 유형](#메트릭-유형) - [Pull vs Push 모델](#pull-vs-push-모델) - [카디널리티와 메트릭 설계](#카디널리티와-메트릭-설계) - [장기 저장소 필요성](#장기-저장소-필요성) - [솔루션 비교](#솔루션-비교) - [메트릭 수집 아키텍처](#메트릭-수집-아키텍처) ## 메트릭 기본 개념 메트릭은 시스템의 상태와 동작을 수치로 표현합니다. 메트릭 이름과 전체 레이블 집합이 시계열을 식별하고, 각 샘플에는 값과 타임스탬프가 있습니다. 알림·장애 분석·용량 계획·성능 분석에 활용하지만 샘플링된 측정값이 개별 이벤트를 모두 보존하는 것은 아닙니다. 예를 들어 `http_requests_total`은 요청 Counter의 이름이고, `method="GET"`, `status="200"`은 측정 대상을 구분합니다. 샘플 값은 누적 횟수입니다. `job`, `instance` 같은 대상 레이블은 보통 scrape 과정에서 추가됩니다. 타임스탬프 단위는 형식에 따라 다릅니다. 기존 Prometheus text exposition에 명시하는 Unix timestamp는 **밀리초**, OpenMetrics는 **초**입니다. 일반적인 exporter는 타임스탬프를 생략하고 Prometheus가 scrape 시각을 부여하게 합니다. 하나의 단위를 모든 텔레메트리 프로토콜에 적용하면 안 됩니다. ### 이름과 단위 | 예시 | 의미 | |---|---| | `http_requests_total` | Counter이며 `_total`은 누적 횟수 표시이지 물리 단위가 아님 | | `http_request_duration_seconds` | 기본 단위를 사용하는 지연 시간 | | `node_memory_MemAvailable_bytes` | node-exporter의 실제 메트릭 이름; 공개된 표기를 유지 | | `requests` | 새 애플리케이션 메트릭 이름으로는 문맥이 부족 | | `httpRequestDurationMs` | 단위는 있지만 camelCase와 밀리초를 사용해 일반적인 Prometheus 이름·기본 단위 관례와 다름 | 새 메트릭은 의미 있는 접두사, 소문자와 언더스코어, `_seconds`·`_bytes` 같은 단위를 사용하는 것이 좋습니다. 이름 관례를 이유로 exporter의 기존 API 이름을 임의로 바꾸지는 않습니다. 아래 `text` 블록은 합성 **Prometheus text exposition**이며 YAML이 아닙니다. 조회 식은 별도 `promql` 블록으로 분리했습니다. 쿼리의 scrape job 이름은 예제 기준이므로 실제 대상 레이블에 맞춰야 합니다. ## 메트릭 유형 Prometheus client library에서 흔히 사용하는 유형은 Counter, Gauge, Histogram, Summary입니다. 어떤 쿼리가 샘플을 받아들인다는 이유보다 측정값의 의미에 맞춰 유형을 선택합니다. ### 1. Counter Counter는 요청·오류·완료 작업 수처럼 음수가 아닌 증가량을 누적합니다. 측정하는 프로세스나 상태가 다시 만들어지면 리셋될 수 있지만, exporter 재시작마다 원래 Counter가 반드시 리셋되는 것은 아닙니다. ```text # TYPE http_requests_total counter http_requests_total{method="GET",endpoint="/api/users",status="200"} 12345 http_requests_total{method="POST",endpoint="/api/users",status="500"} 23 ``` 시계열별 변화율, 서비스 전체 변화율, 기간 증가량 예시입니다. ```promql rate(http_requests_total{job="example-app"}[5m]) ``` ```promql sum(rate(http_requests_total{job="example-app"}[5m])) ``` ```promql increase(http_requests_total{job="example-app"}[1h]) ``` `rate()`는 관측된 Counter 리셋을 처리하고 조회 구간으로 외삽합니다. 관측 사이에 잃어버린 증가량을 복원하는 것은 아닙니다. 따라서 정수 Counter라도 `increase()`의 추정 결과는 소수일 수 있습니다. 한 인스턴스의 리셋이 다른 인스턴스의 증가에 가려지지 않도록 **`rate()`를 먼저 적용한 뒤 집계**합니다. ### 2. Gauge Gauge는 현재 상태이며 증가·감소할 수 있습니다. 다음 합성 값은 node-exporter·kube-state-metrics의 실제 이름과 애플리케이션에서 정의한 온도 메트릭을 함께 보여줍니다. ```text # TYPE node_memory_MemAvailable_bytes gauge node_memory_MemAvailable_bytes 8589934592 # TYPE node_memory_MemTotal_bytes gauge node_memory_MemTotal_bytes 17179869184 # TYPE kube_pod_status_ready gauge kube_pod_status_ready{namespace="example-app",pod="example-0",uid="00000000-0000-4000-8000-000000000001",condition="true"} 1 # TYPE temperature_celsius gauge temperature_celsius{location="datacenter-1"} 23.5 ``` ```promql 100 * (1 - node_memory_MemAvailable_bytes{job="node-exporter"} / node_memory_MemTotal_bytes{job="node-exporter"}) ``` ```promql max_over_time(temperature_celsius{job="example-app"}[1h]) ``` 메모리 식은 `MemAvailable`로 보고되지 않은 비율이며 특정 애플리케이션의 상주 메모리 사용률과 같지 않습니다. Pod readiness는 `condition`별 시계열입니다. `condition="false"`의 값 1과 `condition="true"`의 값 1은 의미가 다릅니다. ### 3. Histogram **Classic histogram**은 계측한 애플리케이션·exporter에서 관측값을 누적 버킷으로 집계합니다. Prometheus가 나중에 분위수를 계산합니다. `le`는 해당 값을 포함하는 상한이고, `+Inf` 버킷은 `_count`와 같습니다. ```text # TYPE http_request_duration_seconds histogram http_request_duration_seconds_bucket{le="0.005"} 24054 http_request_duration_seconds_bucket{le="0.01"} 33444 http_request_duration_seconds_bucket{le="0.025"} 100392 http_request_duration_seconds_bucket{le="0.05"} 129389 http_request_duration_seconds_bucket{le="0.1"} 133988 http_request_duration_seconds_bucket{le="0.25"} 144320 http_request_duration_seconds_bucket{le="+Inf"} 144320 http_request_duration_seconds_sum 4800.8625 http_request_duration_seconds_count 144320 ``` 이 값은 벤치마크가 아닌 설명용 분포입니다. 144,320개 관측의 합계는 **4,800.8625초**입니다. 기존 합계 53.42초는 버킷 개수만으로 계산한 하한이 2,704초를 넘는다는 점과 모순됐습니다. 0.25초 버킷도 추가해 이 예제의 p95가 무한대 버킷에만 속하지 않게 했습니다. 버킷 구성이 일치하는 여러 인스턴스의 전체 p95와 평균은 다음과 같이 구합니다. ```promql histogram_quantile(0.95, sum by (le) (rate(http_request_duration_seconds_bucket{job="example-app"}[5m]))) ``` ```promql sum(rate(http_request_duration_seconds_sum{job="example-app"}[5m])) / sum(rate(http_request_duration_seconds_count{job="example-app"}[5m])) ``` Classic 버킷을 집계할 때는 `le`를 유지합니다. 분위수는 버킷 내부를 보간하므로 분포와 버킷 해상도에 따라 정확도가 달라집니다. Classic 버킷 경계를 바꾸는 것은 쿼리만의 수정이 아니라 계측 설정 변경입니다. Native histogram은 분포 표현 방식이 다릅니다. 현재 Prometheus 가이드는 client·scrape protocol·저장·조회 경로가 지원하면 native histogram을 우선 고려하도록 안내합니다. 전체 경로의 호환성과 설정을 확인해야 하며, 이 장의 classic 예제를 native histogram wire 출력으로 해석하면 안 됩니다. ### 4. Summary Summary는 client에서 설정한 시간 구간의 분위수를 계산할 수 있습니다. 이 값은 일반적으로 **알고리즘·구간 설정에 따른 오차가 있는 근사값**이지 정확한 분위수가 아닙니다. Library마다 지원이 달라 Summary가 sum/count만 제공할 수도 있습니다. ```text # TYPE rpc_request_duration_seconds summary rpc_request_duration_seconds{quantile="0.5"} 0.052 rpc_request_duration_seconds{quantile="0.9"} 0.089 rpc_request_duration_seconds{quantile="0.99"} 0.245 rpc_request_duration_seconds_sum 29969.50 rpc_request_duration_seconds_count 562887 ``` ```promql rpc_request_duration_seconds{job="example-app",quantile="0.99"} ``` ```promql sum(rate(rpc_request_duration_seconds_sum{job="example-app"}[5m])) / sum(rate(rpc_request_duration_seconds_count{job="example-app"}[5m])) ``` 첫 식은 일치하는 인스턴스가 보고한 p99를 각각 반환합니다. 여러 p99의 평균이나 합계는 전체 p99가 아닙니다. 반면 두 번째 식처럼 음수가 아닌 지연 시간의 `_sum`·`_count` 변화율을 합쳐 전체 평균을 계산하는 것은 가능합니다. | 질문 | Classic Histogram | 분위수를 제공하는 Summary | |---|---|---| | 어디에서 처리하는가? | 계측 시 버킷 집계, 조회 시 분위수 계산 | 계측 시 분위수 계산 | | 여러 인스턴스를 결합할 수 있는가? | 호환되는 버킷을 집계 가능 | 분위수는 불가, sum/count는 가능 | | 오차의 기준 | 버킷 해상도와 관측 분포 | Client 알고리즘·오차 목표·시간 구간 | | 나중에 다른 분위수·구간을 조회할 수 있는가? | 보존한 버킷 샘플에서 계산 | 미리 계산된 분위수만으로는 불가 | 트래픽이 0이면 평균이 `NaN`일 수 있고, 시계열이 없으면 빈 결과가 나올 수 있습니다. 어느 경우도 정상 트래픽의 증거로 조용히 바꾸면 안 됩니다. ## Pull vs Push 모델 ![수집기가 요청을 시작하는 Pull과 생산자가 전송을 시작하는 Push의 연결 방향을 비교합니다.](https://raw.githubusercontent.com/Atom-oh/kubernetes-docs/main/ko/.gitbook/assets/ko-observability-metrics-readme-0.png) [인터랙티브 다이어그램](https://www.atomai.click/kubernetes-docs/archmaps/ko-observability-metrics-readme-0.html) 그림은 연결을 시작하는 방향을 설명합니다. 실제로는 agent가 endpoint를 scrape한 뒤 결과를 전송하는 등 두 방식을 혼합할 수 있습니다. 제품 이름만으로 모든 통합 경로가 한 방식이라고 판단하지 않습니다. ### Pull과 Kubernetes discovery Pull 수집은 중앙에서 대상·주기를 제어하고 endpoint를 직접 확인하기 쉽습니다. 수집기의 outbound 연결과 대상의 허용된 inbound 접근, 라우팅·TLS·인증이 모두 필요합니다. NAT가 대상 접근을 자동으로 해결하지는 않습니다. Prometheus의 `up`은 scrape 성공 여부이지 애플리케이션 가용성 SLO가 아닙니다. 다음 Prometheus 설정 조각은 **`example-app` namespace의 Running Pod 중 수집을 허용하고 TCP `metrics` container port를 선언한 대상**을 선택합니다. IPv4 전용 정규식으로 주소를 다시 만들지 않고 discovery가 제공한 주소를 사용합니다. ```yaml # pod-scrape.yaml scrape_configs: - job_name: example-app kubernetes_sd_configs: - role: pod namespaces: names: - example-app relabel_configs: - source_labels: - __meta_kubernetes_pod_annotation_prometheus_io_scrape action: keep regex: 'true' - source_labels: - __meta_kubernetes_pod_phase action: keep regex: Running - source_labels: - __meta_kubernetes_pod_container_port_name action: keep regex: metrics - source_labels: - __meta_kubernetes_pod_container_port_protocol action: keep regex: TCP - source_labels: - __meta_kubernetes_pod_annotation_prometheus_io_path action: replace target_label: __metrics_path__ regex: (.+) - source_labels: - __meta_kubernetes_namespace target_label: namespace - source_labels: - __meta_kubernetes_pod_name target_label: pod ``` 전제 조건은 Pod의 `prometheus.io/scrape: "true"` annotation, 이름이 `metrics`인 포트 선언, 선택적인 `prometheus.io/path`, 해당 Pod를 discovery할 Prometheus의 Kubernetes API 인증·RBAC입니다. 지정한 포트·경로가 실제 메트릭을 제공해야 합니다. 이 조각은 클러스터 설치 예제나 연결 가능성의 증거가 아닙니다. ### Push와 서비스 단위 배치 Push는 outbound 연결이 가능한 생산자와 일부 짧은 작업에 적합할 수 있습니다. 그래도 수신 용량·인증·timeout·재시도·생산자 누락 탐지가 필요합니다. 수신기 상태가 정상이라고 배치 실행을 증명하지는 못합니다. Prometheus는 Pushgateway를 모든 짧은 Pod의 기본 수집기가 아니라 제한적인 **서비스 단위 배치**에 권장합니다. 전송한 그룹은 자동 만료되지 않습니다. Pod별 `HOSTNAME`을 grouping key로 넣어 고아 그룹을 만들지 말고, 안정적인 작업 식별자와 소유자·폐기 시 정리 절차를 정합니다. 다음은 하나의 논리적 배치가 **성공한 뒤 실행하는 통합 조각**이며 완성된 Kubernetes Job이 아닙니다. 접근 권한이 있는 Pushgateway와 `sh`·`awk`·`curl`이 필요합니다. 배치가 실제 실행 시간·처리 건수·원래 완료 시각을 제공해야 하며 전송을 재시도해도 완료 시각을 새로 만들지 않습니다. 환경에 필요한 TLS·인증은 설정하되 예제에 비밀값을 포함하지 않습니다. ```sh set -eu : "${PUSHGATEWAY_URL:?Set the reachable authorized Pushgateway base URL}" : "${DURATION_SECONDS:?Set the measured duration of the successful batch}" : "${RECORDS_PROCESSED:?Set the number of records processed by that batch}" : "${COMPLETED_AT_SECONDS:?Set its original Unix completion time in seconds}" # Reject nonnumeric metric values before sending anything. awk -v n="$DURATION_SECONDS" 'BEGIN { exit !(n ~ /^[0-9]+([.][0-9]+)?$/) }' case "$RECORDS_PROCESSED" in *[!0-9]*|'') exit 2;; esac case "$COMPLETED_AT_SECONDS" in *[!0-9]*|'') exit 2;; esac cat <