10.2. Cache PromQL 쿼리 가이드
커스텀 대시보드·보고서 패널에서 사용하는 PromQL 쿼리 문법과 지원 범위를 안내합니다.
개요
Cache PromQL은 커스텀 대시보드와 SRE 보고서의 커스텀 보고서에서 패널이 표시할 지표를 기술하는 데 쓰는 Prometheus 호환 쿼리 언어입니다. 표준 PromQL의 널리 쓰이는 하위 집합을 지원하며, 제품이 미리 계산해 둔 지표 캐시를 대상으로 평가합니다.
다음 세 곳에서 이 쿼리를 작성합니다.
- 커스텀 대시보드 패널의 PromQL 쿼리
- 커스텀 보고서의 PromQL 패널
- 변수(Variable) 의
query유형 쿼리(label_values(...))
이 문서는 패널을 직접 만드는 사용자를 위한 참고서입니다. 어떤 연산자·함수를 쓸 수 있는지, 무엇이 지원되지 않는지, 그리고 자주 겪는 함정을 정리합니다.
참고: PromQL 문법 자체를 몰라도 커스텀 대시보드·SRE 보고서의 템플릿으로 시작하면 대부분의 화면을 만들 수 있습니다. 이 문서는 템플릿을 수정하거나 직접 지표를 조합할 때 참고하세요.
어떻게 동작하나
Cache PromQL은 일반 Prometheus 서버가 아니라, 제품이 수집·집계해 캐시에 저장한 지표를 대상으로 쿼리를 평가합니다. 이 때문에 몇 가지 실용적인 특성이 있습니다.
- 시계열 중심: 결과는 시간 범위에 대한 시계열입니다. 단일 값(stat)·표(table) 패 널은 시계열의 가장 최근 값을 사용합니다.
- 캐시 해상도: 값은 캐시에 저장된 간격(스텝)의 해상도를 따릅니다. 원시(raw) 샘플 단위가 아닙니다.
Metric Explorer — 어떤 지표가 있는지 찾기
쿼리를 쓰려면 먼저 어떤 지표(metric)가 있는지 알아야 합니다. 지표 이름을 외울 필요는 없습니다. 아래 방법으로 캐시에 저장된 지표를 직접 탐색하세요.
Metric Explorer(주소창
/api/v1/metrics-explorer)는 캐시에 저장된 전체 지표를 탐색하는 전용 화면입니다. 좌측에서 지표를 검색·선택하면 우측에 해당 지표의 라벨(차원) 과 각 라벨의 값 개수, 집계(Aggregation) 옵션, 시계열 차트, 그리고 개별 시리즈 목록이 표시됩니다. 지표 이름을 외우지 않고도 어떤 지표가 있고 어떤 라벨로 좁힐 수 있는지 한눈에 확인할 수 있습니다.
지표 이름을 목록으로 확인하기
캐시에는 표준 Prometheus 의 메타 레이블 __name__(지표 이름)이 그대로 들어 있습니다. 이를 이용하면 사용 가능한 모든 지표 이름을 값 목록으로 뽑을 수 있습니다.
- 커스텀 대시보드에서 변수(Variable) 를 하나 만들고, 유형을 query, 쿼리를
label_values(__name__)로 지정합니다. - 저장하면 헤더의 변수 콤보에 캐시의 전체 지표 이름 목록이 드롭다운으로 나타납니다. 여기서 이름을 훑어보며 원하는 지표를 찾습니다.
- 특정 접두만 보고 싶으면 콤보에 검색어를 입력해 좁힙니다(예:
container_http,node_,kube_).
이 변수는 탐색 전용입니다. 원하는 지표를 확인한 뒤에는 삭제해도 됩니다. 변수 만드는 방법은 커스텀 대시보드의 "변수로 필터링하기" 절을 참고하세요.
지표의 레이블(차원) 확인하기
지표를 골랐다면, 그 지표가 어떤 레이블(예: namespace·pod·app_id)을 갖는지 확인해 매처·집계 기준으로 씁니다.
- 미리보기로 확인: 커스텀 대시보드의 패널 편집 다이얼로그에서 지표 이름만 입력하고 미리보기를 누르면, 결과 시계열의 범례에 레이블이 표시됩니다.
- 레이블 값 열거:
label_values(<지표>, <레이블>)로 특정 레이블의 값 목록을 뽑습니다. 예)label_values(container_http_requests_count, namespace)— 이 지표가 존재하는 네임스페이스 목록.
주요 지표 카탈로그
자주 쓰는 지표를 범주별로 정리했습니다. 전체 목록은 위의 label_values(__name__) 로 확인하세요.
노드(호스트) — node_*
| 지표 | 설명 |
|---|---|
node_cpu_usage_percent · node_cpu_used · node_cpu_cores | CPU 사용률(%)·사용 코어·전체 코어 |
node_memory_usage_bytes · node_memory_usage_percent · node_memory_available_bytes | 메모리 사용량·사용률·가용량 |
node_disk_read_bytes · node_disk_written_bytes · node_disk_space_bytes · node_disk_io_time | 디스크 읽기·쓰기·용량·I/O 시간 |
node_net_rx_bytes · node_net_tx_bytes · node_net_rx_dropped · node_net_tx_dropped | 네트워크 수신·송신 바이트·드롭 |
node_load_average_1m · node_load_average_5m · node_load_average_15m | 부하 평균 |
node_gpu_utilization_percent_avg · node_gpu_memory_used_bytes · node_gpu_power_usage_watts · node_gpu_temperature_celsius | GPU 사용률·메모리·전력·온도 |
node_uptime_seconds · node_info | 가동 시간·노드 메타 |
컨테이너·애플리케이션 리소스 — container_*
| 지표 | 설명 |
|---|---|
container_cpu_usage · container_cpu_limit · container_throttled_time | CPU 사용·한도·스로틀 시간 |
container_memory_rss · container_memory_cache · container_memory_limit | 메모리 RSS·캐시·한도 |
container_restarts · container_oom_kills_total | 재시작 횟수·OOM Kill |
container_net_tcp_bytes_sent · container_net_tcp_bytes_received · container_net_tcp_active_connections · container_net_latency | TCP 송·수신 바이트·활성 연결·지연 |
container_volume_used · container_volume_size | 볼륨 사용·전체 용량 |
container_log_messages | 로그 메시지 수(레벨 레이블 포함) |
container_info · container_application_type | 컨테이너·앱 유형 메타 |
L7 요청·쿼리(프로토콜별) — container_<프로토콜>_*
eBPF 로 계측한 애플리케이션 트래픽입니다. 프로토콜별로 같은 이름 패턴을 씁니다.
| 지표 패턴 | 설명 |
|---|---|
container_http_requests_count | HTTP 요청률(초당, 이미 rate 반영 — 감싸지 말 것) |
container_http_requests_total | HTTP 요청 누적 수 |
container_http_requests_histogram · ..._duration_seconds_total_bucket | 응답시간 히스토그램(분위수 계산용) |
container_http_requests_latency_total | 요청-초 합계(평균 지연 근사용) |
container_http_security_events_count · container_http_geo_country_pct | 보안 이벤트 수·요청 지역 분포 |
HTTP 외에 데이터베이스·메시징 프로토콜은 각각 _requests_ 또는 _queries_ 계열로 동일 패턴을 따릅니다.
- 요청형(
_requests_):container_kafka_requests_*·container_zookeeper_requests_* - 쿼리형(
_queries_):container_postgres_queries_*·container_mysql_queries_*·container_mongo_queries_*·container_oracle_queries_*·container_cassandra_queries_*·container_clickhouse_queries_*·container_memcached_queries_* - 기타:
container_dns_requests_total·container_dns_requests_latency·container_nats_messages_total
접미어 규칙: 같은 계열에서
_count(초당 비율, rate 반영) ·_total(누적 수) ·_histogram/_bucket(분위수용) ·_latency_total(요청-초 합계) 로 나뉩니다._count계열에는 rate 가 이미 반영되어 있으므로rate()/increase()로 감싸지 마세요(아래 주의점 참조).
언어 런타임 — container_jvm_* · container_dotnet_* · container_python_*
| 지표(예) | 설명 |
|---|---|
container_jvm_heap_used_bytes · container_jvm_heap_size_bytes · container_jvm_gc_time_seconds · container_jvm_threads_live | JVM 힙·GC·스레드 |
container_dotnet_memory_heap_size_bytes · container_dotnet_gc_count_total · container_dotnet_thread_pool_size | .NET 힙·GC·스레드풀 |
container_python_thread_lock_wait_time_seconds | Python 스레드 락 대기 |
Kubernetes 상태(kube-state) — kube_* · pod_*
| 지표 | 설명 |
|---|---|
kube_pod_info · kube_pod_status_phase · kube_pod_container_status_ready | Pod 메타·상태·컨테이너 준비 |
kube_pod_container_resource_limits · kube_pod_container_resource_requests | 컨테이너 요청·한도(CPU·메모리) |
kube_deployment_spec_replicas · kube_statefulset_replicas · kube_daemonset_status_desired_number_scheduled | 워크로드 레플리카 |
pod_count · pod_pending · pod_failed | Pod 수·대기·실패 |
kube_node_info · kube_service_info | 노드·서비스 메타 |
참고: 위 표는 대표 지표만 추린 것입니다. 언어·프로토콜·GPU 등 세부 지표는 환경에 따라 존재 여부가 다르므로, 실제 사용 가능한 목록은 항상
label_values(__name__)로 확 인하는 것이 정확합니다.
지원하는 문법
아래 항목은 기본 설정에서 사용할 수 있습니다. 일부 고급 함수는 관리자가 서버 옵션으로 끌 수 있습니다(아래 참고 참조).
지표 셀렉터와 레이블 매처
지표 이름 뒤에 중괄호로 레이블 조건을 붙여 대상을 좁힙니다.
| 매처 | 의미 | 예 |
|---|---|---|
label="value" | 정확히 일치 | {namespace="prod"} |
label!="value" | 일치하지 않음 | {namespace!="kube-system"} |
label=~"regex" | 정규식 일치 | {pod=~"web-.*"} |
label!~"regex" | 정규식 불일치 | {pod!~"canary-.*"} |
변수를 함께 쓸 수 있습니다: {namespace="{{namespace}}"}. 다중 선택 변수는 namespace=~"a|b" 형태로 자동 치환됩니다.
집계 연산자
여러 시계열을 하나로 묶습니다. by(...)로 묶을 기준을, without(...)로 제외할 레이블을 지정합니다.
| 연산자 | 설명 |
|---|---|
sum | 합계 |
avg | 평균 |
min / max | 최소 / 최대 |
count | 시계열 개수 |
topk(k, ...) / bottomk(k, ...) | 상위 / 하위 k개 |
quantile(φ, ...) | 분위수 |
stddev / stdvar | 표준편차 / 분산 |
group | 그룹 존재 여부(모든 값을 1로) |
예) sum by(namespace)(container_memory_rss) — 네임스페이스별 메모리 합계.
이항 연산과 비교
- 산술:
+-*/% - 비교:
><>=<===!=— 조건을 만족하는 시계열만 남깁니다.bool수식자를 붙이면 참/거짓을 0/1 값으로 바꿉니다. - 논리·집합:
andorunless
예) sum(rate_metric) / sum(total_metric) * 100 — 비율(%) 계산.
벡터 매칭
서로 다른 지표를 레이블로 짝지어 연산합니다.
| 수식자 | 설명 |
|---|---|
on(labels) | 나열한 레이블만으로 매칭 |
ignoring(labels) | 나열한 레이블을 제외하고 매칭 |
group_left(labels) | 왼쪽이 다대일(오른쪽에서 레이블 가져오기) |
group_right(labels) | 오른쪽이 다대일 |
예) pod_metric * on(node) group_left(role) node_meta.
함수
수학 함수
abs · ceil · floor · round · exp · ln · log2 · log10 · sqrt · sgn · clamp(v, min, max) · clamp_min(v, min) · clamp_max(v, max)
레이블 함수
label_replace(v, dst, replacement, src, regex)— 정규식으로 레이블 값을 바꾸거나 새 레이블 생성label_join(v, dst, sep, src1, src2, ...)— 여러 레이블을 합쳐 새 레이블 생성
시간·날짜 함수
time()— 각 시점의 시각(초)timestamp(v)— 샘플의 타임스탬프hour(v)·minute(v)·day_of_week(v)·day_of_month(v)·days_in_month(v)·month(v)·year(v)— 인자를 주면 그 값을, 인자를 생략하면 각 시점을 기준으로 계산(한국 표준시)
범위 집계(_over_time)
지정한 시간 창 안의 값을 집계합니다. 예) avg_over_time(metric[5m]).
avg_over_time · sum_over_time · min_over_time · max_over_time · count_over_time · last_over_time · present_over_time · stddev_over_time · stdvar_over_time · quantile_over_time
참고: 범위 창(예:
[5m])은 조회 간격(스텝)보다 같거나 커야 합니다. 창이 스텝보다 짧으면 값이 부정확해지므로 오류로 처리됩니다.
기타 함수
histogram_quantile(φ, ...)— 히스토그램에서 분위수(예: P95) 계산vector(s)— 스칼라를 레이블 없는 시계열로scalar(v)— 단일 시계열을 스칼라로absent(v)·absent_over_time(m[5m])— 값이 없으면 1을 반환(누락 감지)sort·sort_desc·sort_by_label— 시간 범위 쿼리에서는 정렬이 의미가 없어 그대로 통과합니다
기간 대비(offset)
offset으로 과거 같은 구간의 값을 가져와 비교합니다.
예) metric / (metric offset 1d) — 하루 전 대비 비율.
자주 쓰는 패턴과 주의점
요청률·처리량은 rate()로 감싸지 마세요
가장 흔한 함정입니다. 요청 수 같은 누적 성격의 지표 별칭에는 비율(rate) 계산이 이미 반영되어 있습니다. 따라서 이런 지표를 다시 rate()나 increase() 로 감싸면 안 됩니다.
- ✅ 올바른 예:
sum by(app_id)(container_http_requests_count{namespace="{{namespace}}"}) - ❌ 잘못된 예:
rate(container_http_requests_count[5m])
바깥에는 sum by(...) 같은 집계만 적용하세요.
네임스페이스로 좁히기
대부분의 지표는 {namespace="{{namespace}}"} 매처로 네임스페이스를 좁힐 수 있습니다. 변수를 사용하면 헤더 콤보에서 네임스페이스를 바꿀 때 패널이 자동으로 다시 조회됩니다.
응답시간 분위수
지연(latency) 분위수는 히스토그램 기반 지표에 histogram_quantile을 적용하거나, 부하 가중 합계 계열(예: 요청-초 합계)을 요청 수로 나눠 근사합니다. 템플릿의 SLO·RED 예시를 참고하세요.
팁: 새 패널을 만들 때는 커스텀 대시보드의 패널 편집 다이얼로그에서 미리보기 버튼으로 쿼리를 먼저 확인하세요. 오류나 빈 결과가 있으면 안내 메시지로 알려 줍니다.
미지원 항목
다음은 현재 지원되지 않습니다.
| 항목 | 대안 |
|---|---|
rate() · increase() | 지표 별칭에 이미 반영됨 — 감싸지 말고 그대로 사용 |
@ 수식자(고정 시점) | 오류 없이 무시됨 (offset만 반영) |
count_values | 지원하지 않음 |
서브쿼리 [5m:1m] | 지원하지 않음 |
predict_linear · holt_winters | SRE 보고서의 자원 예측(Forecast) 사용 |
삼각함수(sin·cos 등) | 지원하지 않음 |
시각 마스킹 metric and hour() >= 9 | 지원하지 않음(시간 함수는 레이블이 없어 마스킹 불가) |
지원되지 않는 문법은 대부분 미리보기·출력 시 오류로 안내되며, 일부(@ 수식자 등)는 오류 없이 무시됩니다.
변수와 함께 쓰기
변수는 여러 패널에 공통으로 적용되는 필터 값입니다. 쿼리 안에서 {{변수이름}}으로 참조합니다.
- query 유형 변수는
label_values(지표, 레이블)로 값 목록을 조회합니다. 예)label_values(namespace). - 종속 변수는 상위 변수를 매처에 넣어 하위 목록을 좁힙니다. 예)
label_values(container_info{namespace="{{namespace}}"}, pod).
변수의 정의·선택 방법은 커스텀 대시보드의 "변수로 필터링하기" 절을 참고하세요.
참고: 일부 특수 지표(예: 복합 키로 저장되는 사용자 추정 지표)는
label_values()의 소스로 적합하지 않을 수 있습니다. 변수 목록이 비면container_http_requests_count처럼 일반적인 지표로 네임스페이스를 열거하세요.
자주 묻는 질문
쿼리가 빈 결과를 반환합니다
- 지표 이름이나 레이블 값에 오타가 없는지 확인하세요.
- 매처가 너무 좁지 않은지(
{namespace="..."}값이 실제로 존재하는지) 확인하세요. - 종속 변수를 쓰는 경우 상위 변수를 먼저 선택해야 합니다.
- 미리보기 버튼으로 조회 결과와 오류 메시지를 확인하세요.
요청률이 이상하게 높거나 낮게 나옵니다
요청 수 지표를 rate()로 감쌌을 가능성이 큽니다. 해당 지표에는 비율 계산이 이미 반영되어 있으므로, rate() 없이 sum by(...)만 적용하세요.
예측(predict_linear)을 쓰고 싶습니다
Cache PromQL은 예측 함수를 지원하지 않습니다. 미래 사용량 예측은 SRE 보고서의 자원 예측(Forecast) 탭을 사용하세요. 선형회귀·Holt-Winters·ARIMA·SARIMA 알고리즘을 제공합니다.
고급 함수가 동작하지 않습니다
수학 함수·범위 집계 등 고급 함수는 기본적으로 켜져 있지만, 관리자가 서버 옵션으로 비활성화한 환경에서는 "함수가 비활성화되어 있습니다"라는 오류가 날 수 있습니다. 이 경우 관리자에게 문의하세요.