PromQL

PromQL은 "메트릭 타입의 의미를 이해하지 않으면 결과가 잘못 나온다"는 점이 핵심이다. Counter를 그대로 쓰면 누적값만 보이므로 rate()가 필수이고, Histogram 퍼센타일은 histogram_quantile 없이는 구할 수 없다. 따라서 PromQL 작성 전에 "이 메트릭이 Counter/Gauge/Histogram 중 무엇인가?"를 먼저 확인하는 습관이 안전하다고 보인다.

메트릭 타입마다 쿼리 패턴이 갈린다

PromQL의 기본 단위는 메트릭 시계열이다. 메트릭 타입: Counter(단조 증가 누적 값), Gauge(현재 값, 오르내림), Histogram/Summary(분포)이며, 선택자는 metric{label="v",label!=...} 형태다.^[1]

선택자, 범위 벡터, 집계, 퍼센타일

• 범위 벡터는 metric[5m]로 최근 5분 구간을 가져오고, 증분/속도는 rate(counter[5m]), irate(counter[1m]), increase(counter[1h])로 계산한다.^[1:1]
• 집계 함수 sum(), avg(), max(), min()에 by(...)로 그룹 라벨을 지정한다.^[1:2]
• 퍼센타일은 histogram_quantile(0.95, sum by (le)(rate(<*_bucket>[5m]))) 패턴으로 구한다.^[1:3]
• 선택자 필터 예: 정규식 매칭 device=~"enp.*|eth.*", 라벨 제외 fstype!~"tmpfs|overlay".^[2]

벡터 매칭·라벨 조작·시간 윈도우·부재 감지

• 벡터 매칭(조인): sum(rate(a_total[5m])) by (instance) * on(instance) group_left(job) max(up) by (instance, job).^[3]
• 라벨 조작: label_replace(http_requests_total, "new_path", "$1", "path", "^/api/(.*)").^[4]
• 시간 윈도우 함수: max_over_time(node_load1[1h]), avg_over_time(probe_duration_seconds[30m]), increase(http_requests_total[24h]).^[5]
• 부재 감지: absent(up{job="host"})로 메트릭이 사라졌는지(수집 실패) 감지한다.^[6]

자주 쓰는 스니펫

호스트 메트릭 (node-exporter)

# CPU 사용률 (%)
100 - (avg by (instance)(rate(node_cpu_seconds_total{mode="idle"}[5m])) * 100)

# 메모리 사용률 (%)
(1 - (node_memory_MemAvailable_bytes / node_memory_MemTotal_bytes)) * 100

# 디스크 사용률 (%)
(1 - node_filesystem_avail_bytes{fstype!~"tmpfs|overlay"}
      / node_filesystem_size_bytes{fstype!~"tmpfs|overlay"}) * 100

# NIC 수신/송신 (bytes/s)
sum by(instance)(rate(node_network_receive_bytes_total{device!~"lo"}[5m]))

컨테이너 메트릭 (cAdvisor)

# 컨테이너 CPU (% of 1 CPU)
sum by (container)(rate(container_cpu_usage_seconds_total{container!=""}[5m])) * 100

# 컨테이너 메모리 (MiB)
container_memory_working_set_bytes{container!=""} / 1024^2

API 가용성 및 레이턴시 (blackbox + app)

# API 가용성 (1/0)
probe_success{instance="api"}

# API P95 레이턴시 (Histogram)
histogram_quantile(0.95, sum by (le)(
  rate(http_request_duration_seconds_bucket[5m])
))

실전 팁

• Counter는 반드시 rate()/increase()와 함께 — 누적치를 속도로 변환해야 의미 있는 값이 나온다.
• 윈도우 선택: 1m(민감), 5m(안정), 15m(완만) — 대시보드인지 알람인지에 따라 조절.
• 라벨 cardinality 관리: path 등 고유값이 많은 라벨은 대시보드/알람에서 제한하지 않으면 메모리·쿼리 비용이 폭발한다.
• Blackbox: metrics_path: /probe + relabel_configs 패턴이 필수다.^[7]

쿼리 예시의 경계

• 각 snippet은 source에 나온 metric name과 label 구조를 전제로 한다. exporter·application이 달라지면 같은 query를 그대로 쓸 수 없다.
• Grafana panel query와 alert rule query는 모두 PromQL을 쓰지만, 전자는 탐색용이고 후자는 지속 조건과 notification을 위한 판단용이다.

실패 모드

• Counter를 그대로 쓰거나 rate() 없이 평균을 내는 경우.
• Histogram인데 histogram_quantile 없이 bucket 값을 그대로 표시하는 경우.
• rate() 범위를 너무 짧게(예: 30s) 잡아 노이즈가 큰 알람이 발생하는 경우.
• High-cardinality 라벨을 필터 없이 그대로 쿼리해 시계열이 폭발하는 경우.
• 부재 시나리오를 무시해 메트릭이 사라졌을 때 알람이 안 울리는 경우 (absent() 패턴 미사용).

관련

• Prometheus: PromQL이 동작하는 시계열 DB. prometheus.yml이 수집 대상을 정의하면 PromQL은 그 위에서 값을 추출한다.
• Grafana: 각 Panel 쿼리가 PromQL로 작성된다.

출처

테스트 질문

• Counter, Gauge, Histogram 메트릭 타입별로 PromQL 쿼리 패턴이 어떻게 달라지는가?
• rate()/irate()/increase()의 차이와 사용 시점은 무엇인가?
• histogram_quantile(0.95, ...) 패턴에서 sum by (le)가 왜 필요한가?
• 알람에서 부재 시나리오(메트릭이 수집 자체가 안 됨)를 어떻게 감지하는가?