PromQL Reference

Q: PromQL이란 무엇이고 어디에 사용하나요?

PromQL(Prometheus Query Language)은 인기 있는 오픈소스 모니터링 및 알림 시스템인 Prometheus의 함수형 쿼리 언어입니다. 시계열 메트릭을 실시간으로 선택하고 집계하거나, 알림 규칙(예: 오류율이 5%를 초과하면 알림 발송)을 작성하거나, 시스템 상태, 레이턴시, 처리량, 리소스 사용량을 시각화하는 Grafana 대시보드 패널을 구축하는 데 사용됩니다.

Q: PromQL에서 rate()와 irate()의 차이는?

rate(v[t])는 지정된 시간 윈도우에 걸친 평균 초당 증가율을 계산하여 스파이크를 완화합니다. irate(v[t])는 범위의 마지막 두 데이터 포인트를 기반으로 순간 비율을 계산하여 급격한 스파이크에 더 민감합니다. 알림 및 추세 분석에는 rate()를, 급격한 변동을 보고 싶은 대시보드에는 irate()를 사용하세요.

Q: rate()와 increase()와 delta()를 언제 각각 사용해야 하나요?

카운터(http_requests_total 같이 단조 증가하는 메트릭)에서 초당 처리량을 원할 때는 rate()를 사용합니다. 카운터에서 시간 윈도우의 총 횟수를 원할 때는 increase()를 사용합니다. 게이지(온도나 메모리처럼 오르내리는 메트릭)에서 시간 윈도우의 변화량을 원할 때는 delta()를 사용합니다. 카운터에는 절대 delta()를 사용하지 마세요.

Q: histogram_quantile로 p99 레이턴시를 계산하는 방법은?

histogram_quantile(0.99, rate(http_request_duration_seconds_bucket[5m]))을 사용합니다. 0.99는 분위수(99번째 백분위수)입니다. 버킷 메트릭은 _bucket으로 끝나야 하며 히스토그램 타입이어야 합니다. 라이브 데이터에서 분위수를 계산할 때는 항상 rate()로 시간 윈도우를 감쌉니다. p95는 0.95, 중앙값은 0.50으로 변경하세요.

Q: 특정 레이블은 유지하면서 모든 인스턴스에 걸쳐 메트릭을 합산하는 방법은?

by()와 함께 sum()을 사용합니다: `sum(rate(http_requests_total[5m])) by (method, status)`. 이렇게 하면 모든 인스턴스, 파드 등의 차원에 걸쳐 합산하면서 method와 status 레이블은 유지됩니다. without()으로 특정 레이블을 제외하고 나머지를 유지할 수도 있습니다: `sum(rate(http_requests_total[5m])) without (instance, pod)`.

Q: PromQL에서 범위 벡터란 무엇이고 rate()에 왜 필요한가요?

범위 벡터는 단일 시점이 아닌 시간 윈도우에 걸친 샘플을 선택합니다. metric[5m](최근 5분의 샘플)과 같이 작성합니다. rate(), irate(), increase(), delta() 같은 함수는 비율이나 델타를 계산하기 위해 여러 데이터 포인트가 필요하므로 범위 벡터를 요구합니다. [t] 없는 인스턴트 벡터 셀렉터는 시계열당 단일 샘플을 반환합니다.

Q: 현재 메트릭과 1시간 전 데이터를 비교하는 방법은?

offset 수정자를 사용합니다: `rate(http_requests_total[5m] offset 1h)`는 1시간 전의 비율을 반환합니다. 현재 비율에서 빼면 변화를 계산할 수 있습니다: `rate(http_requests_total[5m]) - rate(http_requests_total[5m] offset 1h)`. @ 수정자로 특정 Unix 타임스탬프에서 쿼리할 수도 있습니다: `metric @ 1609459200`.

Q: PromQL로 디스크 용량이 언제 부족해질지 예측하는 방법은?

predict_linear()를 사용합니다: `predict_linear(node_filesystem_free_bytes[1h], 4*3600)`은 최근 1시간 데이터의 선형 회귀를 기반으로 4시간 후의 디스크 여유 공간을 예측합니다. 일반적인 알림 규칙은 predict_linear(disk_free[6h], 24*3600) < 0일 때 발동하여 24시간 이내에 디스크가 가득 찰 것을 경고합니다.

Prometheus 쿼리 언어 레퍼런스

33개 결과

PromQL Reference 소개

PromQL 레퍼런스는 Prometheus 시계열 모니터링과 Grafana 시각화에 사용되는 Prometheus Query Language(PromQL)의 모든 필수 구문과 함수를 체계적으로 정리한 검색 가능한 가이드입니다. 셀렉터(메트릭 이름 선택, =, =~, !=, !~와 __name__ 정규식을 이용한 레이블 매칭), 연산자(산술 +/-/*//, 비교 ==/>/< , 논리 and/or/unless, 레이블 매칭 수정자 on()/ignoring(), 다대일 조인을 위한 group_left/group_right), 함수(rate, irate, increase, histogram_quantile, delta, deriv, predict_linear, 수학 함수, label_replace), 집계(sum, avg, count, min/max, topk, quantile), 범위 벡터([5m] 표기법, offset, @ 타임스탬프, 서브쿼리), 레이블(by(), without(), label_join()) 6개 카테고리로 구성됩니다.

SRE, 플랫폼 엔지니어, DevOps 팀들이 Prometheus 알림 규칙 작성, Grafana 대시보드 구축, SLO 모니터링 설정, 인프라 성능 문제 진단 시 이 레퍼런스를 활용합니다. PromQL의 함수형 쿼리 모델은 SQL과 다르며, 인스턴트 벡터, 범위 벡터의 개념과 카운터(rate/increase)와 게이지(delta/deriv)의 구분을 이해해야 합니다. 이 레퍼런스는 구체적인 예제로 이를 명확히 설명합니다.

각 항목은 `http_requests_total`, `node_memory_MemAvailable_bytes`, `http_request_duration_seconds_bucket` 같은 일반적인 Prometheus 메트릭을 사용한 실제적인 쿼리 예제와 함께 정확한 PromQL 구문을 보여줍니다. 레이턴시 백분위수(p99, p95)를 위한 히스토그램 분위수 계산, 디스크 용량 예측을 위한 predict_linear, rate의 rate를 계산하는 서브쿼리, 현재와 과거 데이터 비교를 위한 시간 오프셋 쿼리 등 고급 사용 사례도 다룹니다.

주요 기능

레이블 셀렉터 구문: 정확 매칭 {label="value"}, 정규식 =~, 부정 !=와 !~, {__name__=~"pattern"}으로 메트릭 이름 정규식 매칭
산술 연산자(+, -, *, /, %, ^)로 전체 메모리에서 사용 가능 메모리를 빼는 것과 같은 메트릭 수학
필터링 및 알림 임계값 표현을 위한 비교 연산자(==, !=, >, <, >=, <=)
on()/ignoring() 레이블 매칭 수정자와 group_left/group_right 조인을 포함한 논리 연산자(and, or, unless)
비율 함수: 초당 카운터 비율 rate(), 순간 비율 irate(), 범위 내 총 증가량 increase()
히스토그램 분위수: p99 레이턴시 계산을 위한 histogram_quantile(0.99, rate(duration_bucket[5m]))
by()와 without() 레이블 그룹화를 포함한 집계 연산자: sum(), avg(), count(), min(), max(), topk(), quantile()
범위 벡터 기능: [5m] 윈도우 표기법, 시간 이동을 위한 offset 1h, @ 타임스탬프, 중첩 평가를 위한 서브쿼리

자주 묻는 질문

PromQL이란 무엇이고 어디에 사용하나요?

PromQL(Prometheus Query Language)은 인기 있는 오픈소스 모니터링 및 알림 시스템인 Prometheus의 함수형 쿼리 언어입니다. 시계열 메트릭을 실시간으로 선택하고 집계하거나, 알림 규칙(예: 오류율이 5%를 초과하면 알림 발송)을 작성하거나, 시스템 상태, 레이턴시, 처리량, 리소스 사용량을 시각화하는 Grafana 대시보드 패널을 구축하는 데 사용됩니다.

PromQL에서 rate()와 irate()의 차이는?

rate(v[t])는 지정된 시간 윈도우에 걸친 평균 초당 증가율을 계산하여 스파이크를 완화합니다. irate(v[t])는 범위의 마지막 두 데이터 포인트를 기반으로 순간 비율을 계산하여 급격한 스파이크에 더 민감합니다. 알림 및 추세 분석에는 rate()를, 급격한 변동을 보고 싶은 대시보드에는 irate()를 사용하세요.

rate()와 increase()와 delta()를 언제 각각 사용해야 하나요?

카운터(http_requests_total 같이 단조 증가하는 메트릭)에서 초당 처리량을 원할 때는 rate()를 사용합니다. 카운터에서 시간 윈도우의 총 횟수를 원할 때는 increase()를 사용합니다. 게이지(온도나 메모리처럼 오르내리는 메트릭)에서 시간 윈도우의 변화량을 원할 때는 delta()를 사용합니다. 카운터에는 절대 delta()를 사용하지 마세요.

histogram_quantile로 p99 레이턴시를 계산하는 방법은?

histogram_quantile(0.99, rate(http_request_duration_seconds_bucket[5m]))을 사용합니다. 0.99는 분위수(99번째 백분위수)입니다. 버킷 메트릭은 _bucket으로 끝나야 하며 히스토그램 타입이어야 합니다. 라이브 데이터에서 분위수를 계산할 때는 항상 rate()로 시간 윈도우를 감쌉니다. p95는 0.95, 중앙값은 0.50으로 변경하세요.

특정 레이블은 유지하면서 모든 인스턴스에 걸쳐 메트릭을 합산하는 방법은?

by()와 함께 sum()을 사용합니다: `sum(rate(http_requests_total[5m])) by (method, status)`. 이렇게 하면 모든 인스턴스, 파드 등의 차원에 걸쳐 합산하면서 method와 status 레이블은 유지됩니다. without()으로 특정 레이블을 제외하고 나머지를 유지할 수도 있습니다: `sum(rate(http_requests_total[5m])) without (instance, pod)`.

PromQL에서 범위 벡터란 무엇이고 rate()에 왜 필요한가요?

범위 벡터는 단일 시점이 아닌 시간 윈도우에 걸친 샘플을 선택합니다. metric[5m](최근 5분의 샘플)과 같이 작성합니다. rate(), irate(), increase(), delta() 같은 함수는 비율이나 델타를 계산하기 위해 여러 데이터 포인트가 필요하므로 범위 벡터를 요구합니다. [t] 없는 인스턴트 벡터 셀렉터는 시계열당 단일 샘플을 반환합니다.

현재 메트릭과 1시간 전 데이터를 비교하는 방법은?

offset 수정자를 사용합니다: `rate(http_requests_total[5m] offset 1h)`는 1시간 전의 비율을 반환합니다. 현재 비율에서 빼면 변화를 계산할 수 있습니다: `rate(http_requests_total[5m]) - rate(http_requests_total[5m] offset 1h)`. @ 수정자로 특정 Unix 타임스탬프에서 쿼리할 수도 있습니다: `metric @ 1609459200`.

PromQL로 디스크 용량이 언제 부족해질지 예측하는 방법은?

predict_linear()를 사용합니다: `predict_linear(node_filesystem_free_bytes[1h], 4*3600)`은 최근 1시간 데이터의 선형 회귀를 기반으로 4시간 후의 디스크 여유 공간을 예측합니다. 일반적인 알림 규칙은 predict_linear(disk_free[6h], 24*3600) < 0일 때 발동하여 24시간 이내에 디스크가 가득 찰 것을 경고합니다.