R7. PromQL 연동 레퍼런스
Diátaxis: Reference · 대상: 운영자 / 관리자 (PromQL · Grafana 경험자) ← 목차로
이미 Grafana 대시보드나 PromQL에 익숙하다면, OPENMARU APM이 수집한 WAS · JVM · 시스템 · WEB · DBMS 메트릭을 표준 PromQL 호환 쿼리로 그대로 조회할 수 있습니다. 별도의 Prometheus 서버나 익스포터·스크레이프 설정 없이 APM 한 곳에서 수집·저장·질의·시각화가 끝나고, 기존 Grafana 대시보드 자산도 재사용할 수 있습니다.
- APM의 세밀한 메트릭을 그대로 — JVM·GC·스레드·DB 커넥션풀·트랜잭션 메트릭에 표준 PromQL로 접근
- 풍부한 라벨 —
instance_id,ip_addr,agent_type같은 APM 컨텍스트로 정밀 필터·집계 - rate/increase가 빠르고 정확 — 수집 시점에 변화량(delta)으로 저장돼 쿼리 시 단순 합산만 수행
- 상대 시간 표현 —
now,now-1h같은 직관적 표현 지원 (표준 Prometheus에는 없는 편의 기능)
어떤 메트릭이 어떤 의미인지는 R2. 차트 지표 레퍼런스와 E3. 지표의 의미를 보세요. 콘솔 안에서 차트를 모아 보려면 H3. 나의 대시보드로도 충분합니다 — PromQL은 외부 연동·자동화가 필요할 때의 도구입니다.
여는 법 — 브라우저에서 http://{apm-server}/monitoring/api/v1/metric-explorer
(Metric Explorer UI). 로그인에는 API 접근 키를 사용합니다 — 좌측 메뉴 ▸ 설정 ▸
사용자에서 사용자 수정 버튼을 눌러 키를 생성·복사하세요.
5분 만에 시작하기
가장 단순한 쿼리 — 한 줄이면 모든 WAS 인스턴스의 JVM 힙 사용량(현재값)이 나옵니다.
jvm_heap_heapUsed
특정 인스턴스만, 또는 특정 IP 대역만(정규식) 보고 싶을 때:
jvm_heap_heapUsed{instance_id="apm-was-01"}
jvm_heap_heapUsed{ip_addr=~"192\\.168\\.80\\..*"}
시간 함수를 적용해 지난 1시간 최댓값, 5분 평균 GC 빈도를 구합니다:
max_over_time(jvm_heap_heapUsed[1h])
rate(jvm_gc_gcCount[5m])
참고 정확한 메트릭 이름은 Metric Explorer의 드롭다운에서 고르거나
GET /api/v1/label/__name__/values로 확인하세요 (약 250개).
기간을 지정해 조회하기
범위 조회(/api/v1/query_range)는 시작/종료 시각과 step(데이터 간격)을 받습니다.
네 가지 시간 형식을 지원합니다.
| 형식 | 예시 | 비고 |
|---|---|---|
| 상대 시간 | now, now-1h, now-30m, now-1d | 가장 편리 — 단위 s/m/h/d |
| Unix epoch (초) | 1704067200 | shell date +%s |
| Unix epoch + 소수 | 1704067200.123 | 밀리초 정밀도 |
| RFC3339 | 2026-05-10T09:00:00+09:00 | 타임존 포함 가능 |
자주 쓰는 호출 예시:
# 최근 1시간 — 가장 흔한 케이스 (step 자동 15s)
curl -G "http://{apm-server}/monitoring/api/v1/query_range" \
--data-urlencode "query=jvm_heap_heapUsed" \
--data-urlencode "start=now-1h" \
--data-urlencode "end=now"
# 최근 7일 주간 추세 (step 자동 5m)
curl -G "http://{apm-server}/monitoring/api/v1/query_range" \
--data-urlencode "query=max_over_time(cpu_usage_cpuUsage[1h])" \
--data-urlencode "start=now-7d" \
--data-urlencode "end=now"
# step 직접 지정 (15초 간격)
curl -G "http://{apm-server}/monitoring/api/v1/query_range" \
--data-urlencode "query=rate(jvm_gc_gcCount[5m])" \
--data-urlencode "start=now-30m" \
--data-urlencode "end=now" \
--data-urlencode "step=15s"
# 특정 날짜 범위 (KST)
curl -G "http://{apm-server}/monitoring/api/v1/query_range" \
--data-urlencode "query=jvm_heap_heapUsed{agent_type=\"WAS\"}" \
--data-urlencode "start=2026-05-10T09:00:00+09:00" \
--data-urlencode "end=2026-05-11T18:00:00+09:00"
step을 지정하지 않으면 조회 범위에 따라 자동 계산됩니다:
| 조회 범위 | 자동 step | 데이터 포인트 수 (예) | 권장 용도 |
|---|---|---|---|
| 12시간 이하 | 15s | 1시간 ≈ 240 | 실시간 · 표준 대시보드 |
| 12시간 ~ 2일 | 1m | 24시간 ≈ 1,440 | 일별 비교 |
| 2일 ~ 8일 | 5m | 7일 ≈ 2,016 | 주간 추세 |
| 8일 ~ 21일 | 10m | 격주 추세 | |
| 21일 이상 | 30m | 30일 ≈ 1,440 | 월간 비교 |
참고 원본 데이터는 2초 주기로 저장됩니다. step을 작게 하면 더 촘촘하지만 서버 부하가 커집니다 — 큰 step으로 시작해 필요할 때 줄여 가세요.
단일 시점의 값 하나만 필요하면 instant 쿼리(/api/v1/query)를 씁니다:
# 현재 / 1시간 전 시점의 힙 사용량
curl -G "http://{apm-server}/monitoring/api/v1/query" \
--data-urlencode "query=jvm_heap_heapUsed"
curl -G "http://{apm-server}/monitoring/api/v1/query" \
--data-urlencode "query=jvm_heap_heapUsed" \
--data-urlencode "time=now-1h"
메트릭 이름과 라벨
APM 메트릭은 다섯 개 라벨 차원으로 구분됩니다. 쿼리의 필터·집계에 그대로 씁니다.
| Label | 의미 | 예시 값 |
|---|---|---|
__name__ | 메트릭 이름 — {nameSpace}_{metricName}_{field} 형식 | jvm_heap_heapUsed, cpu_usage_cpuUsage |
ip_addr | 에이전트가 설치된 호스트 IP | 192.168.80.190 |
agent_type | 에이전트 종류 | WAS, SYS, DBMS, WEB |
instance_id | 인스턴스 식별자 (호스트 안에서 유일) | apm-was-01, nginx-1 |
namespace | 메트릭 그룹 | jvm, transaction, cpu, memory |
Prometheus 표준 호환 라벨도 자동 생성됩니다 — instance(= {ip_addr}:{instance_id}),
job(= agent_type).
메트릭 이름은 {nameSpace}_{metricName}_{field} 한 가지 형식만 알면 됩니다
(마지막 _field는 생략 가능 — 생략하면 기본 field가 선택됩니다).
| 예시 | 의미 |
|---|---|
jvm_heap_heapUsed | JVM 힙의 사용량 field |
jvm_heap_heapMax | 같은 메트릭의 최대치 field |
cpu_usage_cpuUsage | CPU 사용률 |
cpu_usage_systemCpuUsage | 시스템 전체 CPU 사용률 |
라벨 matcher는 표준 네 가지를 모두 지원하고, 여러 조건을 쉼표로 결합합니다:
metric{label="value"} # 일치
metric{label!="value"} # 불일치
metric{label=~"regex"} # 정규식 일치
metric{label!~"regex"} # 정규식 불일치
jvm_heap_heapUsed{ip_addr="192.168.80.190", instance_id=~"apm-was-.*", agent_type="WAS"}
Prometheus와 다른 점
거의 모든 문법이 동일하지만, Counter 저장 방식 한 가지가 다릅니다.
| 구분 | Prometheus | OPENMARU APM |
|---|---|---|
| Counter 저장값 | 단조 증가 누적값 (총 요청 수 1, 2, 3 …) | 단위 시간당 변화량(delta) (2초 동안 17건) |
rate() 계산 | (마지막값 − 첫값) ÷ 기간 | delta 합계 ÷ 기간 |
increase() 계산 | 마지막값 − 첫값 | delta 합계 |
| counter reset 보정 | 필요 | 불필요 (delta라 리셋 개념 없음) |
사용자가 보는 결과는 동일합니다 — rate(jvm_gc_gcCount[5m])는 양쪽 모두 "초당 평균
GC 횟수"입니다. 내부 계산만 다르고, delta 사전 저장 덕분에 더 빠르고 정확합니다.
다음은 100% 호환됩니다 — 라벨 matcher, 집계 연산자(sum by 등)와
topk/bottomk/quantile, rate/irate/increase, *_over_time 함수군, 수학 함수,
산술·비교 연산, HTTP API 스펙.
미지원·제한 사항:
| 항목 | 상태 |
|---|---|
histogram_quantile() | 미지원 — APM은 분위수를 직접 저장하므로 avgRT · minRT · maxRT 같은 field를 바로 사용 |
| Recording / Alerting rules | 미지원 |
Subquery (<expr>[<range>:<step>]) | 제한적 지원 |
predict_linear(), holt_winters() | 미지원 |
| 장기간 조회 자동 롤업 | 미적용 — 수 주 이상 조회는 step을 크게 지정 권장 |
참고 함수 없이
metric{...}만 조회하면 step 구간의 마지막 샘플이 반환됩니다. 구간의 정확한 합계·평균이 필요하면sum_over_time(...)·avg_over_time(...)을 명시적으로 쓰세요.
지원 함수
표준 4가지 데이터 형(instant vector · range vector · scalar · string)을 모두 지원합니다.
Rate / Counter 함수 — range vector → instant vector:
rate(metric[5m]) # 초당 평균 변화율
irate(metric[5m]) # 마지막 두 샘플 기반 순간 변화율
increase(metric[5m]) # 구간 전체 증가량
over_time 함수군 — 구간 통계:
avg_over_time(metric[1h]) min_over_time(metric[1h]) max_over_time(metric[1h])
sum_over_time(metric[1h]) count_over_time(metric[1h]) last_over_time(metric[1h])
집계 연산자 — sum · avg · min · max · count · stddev · stdvar ·
topk(N, …) · bottomk(N, …) · quantile(0.95, …) · count_values · group.
by / without 절로 그룹화합니다:
avg by (instance) (jvm_heap_heapUsed) # 인스턴스별 평균
sum without (user_key) (jvm_heap_heapUsed) # user_key 만 제외하고 그룹화
topk(5, rate(jvm_gc_gcCount[5m])) # GC 빈도 상위 5개 인스턴스
수학·산술·비교:
abs(metric) ceil(metric) floor(metric) round(metric)
metric_a + metric_b
rate(metric[5m]) / 60
jvm_heap_heapUsed > 1024 * 1024 * 1024 # 1GB 초과 시리즈만 반환
Metric Explorer
브라우저에서 PromQL을 인터랙티브하게 실행하는 UI입니다 — 위 여는 법의 주소로 접속합니다.
| 영역 | 기능 |
|---|---|
| 메트릭 선택 드롭다운 | 등록된 메트릭 자동 발견 (__name__ 기준) |
| PromQL 쿼리 입력 | 직접 입력 — 드롭다운에서 고르면 자동으로 채워짐 |
| Label 필터 패널 | ip_addr · agent_type · instance_id · namespace 별 드롭다운 |
| 집계 함수 선택 | sum · avg · topk · quantile 등 |
| 시간 범위 | 최근 5m ~ 7d 빠른 버튼 + 커스텀 범위 |
| Step | Auto / 15s / 1m / 5m / 10m / 30m / 1h |
| 결과 시각화 | line / area / bar 차트 + raw 값 테이블 |
| API URL 복사 | 현재 쿼리를 /api/v1/query_range URL로 복사 — Grafana 등 외부 연동용 |
30초 만에 첫 차트를 만들어 봅니다:
- 메트릭 드롭다운에서
jvm_heap_heapUsed선택 - Label 필터에서
agent_type=WAS선택 - 시간 범위 1h 클릭, Step은 Auto 유지
- Run 클릭 → WAS 인스턴스들의 1시간 힙 사용량 그래프가 표시됩니다
참고 Step은 보통 Auto면 충분합니다. 작은 step + 긴 범위는 서버 부하가 커집니다.
Grafana 연동 — 같은 API를 Grafana의 Prometheus 데 이터소스로 연결할 수 있습니다:
URL: http://{apm-server}/monitoring
Access: Server (default)
Grafana가 /api/v1/query, /api/v1/query_range, /api/v1/labels 등을 자동으로
호출합니다 — 기존 대시보드·알림 자산을 그대로 재사용하세요.
HTTP API 요약
| Method | Path | 용도 |
|---|---|---|
| GET / POST | /api/v1/query | 단일 시점(instant) 쿼리 |
| GET / POST | /api/v1/query_range | 시간 범위(range) 쿼리 |
| GET | /api/v1/series | series 메타데이터 |
| GET | /api/v1/labels | label 이름 목록 |
| GET | /api/v1/label/{name}/values | 특정 label의 값 목록 |
| GET | /api/v1/metadata | 메트릭 메타데이터 |
| GET | /api/v1/metric-explorer | Metric Explorer UI |
파라미터 — query(필수), instant는 time, range는 start · end · step(생략 시
자동 계산). 탐색용 호출:
# 사용 가능한 메트릭 전체 목록 (~250개)
curl "http://{apm-server}/monitoring/api/v1/label/__name__/values"
# label 이름 목록 / 특정 label 의 값
curl "http://{apm-server}/monitoring/api/v1/labels"
curl "http://{apm-server}/monitoring/api/v1/label/agent_type/values"
자주 쓰는 쿼리 모음
메트릭 이름은 일반 패턴 기준 예시입니다 — 운영 환경의 정확한 이름은 Metric Explorer로 확인하세요.
JVM / WAS:
jvm_heap_heapUsed{agent_type="WAS"} # 전체 WAS 의 현재 힙 사용량
avg_over_time(jvm_heap_heapUsed[5m]) # 힙 사용량 5분 평균
topk(5, jvm_heap_heapUsed) # 힙 사용 상위 5개 인스턴스
(jvm_heap_heapUsed / jvm_heap_heapMax) > 0.8 # 힙 사용률 80% 초과
sum_over_time(jvm_gc_gcTime[1h]) # GC 시간 합계 (1시간)
rate(jvm_gc_gcCount[5m]) # 초당 GC 횟수
datasource_pool_active{agent_type="WAS"} # 사용 중 DataSource 연결 수
시스템:
topk(10, cpu_usage_cpuUsage{agent_type="SYS"}) # CPU 상위 10개 호스트
cpu_usage_systemCpuUsage # 시스템 전체 CPU
avg_over_time(cpu_usage_cpuUsage[1h]) # 인스턴스별 1시간 평균 CPU
호스트 단위 집계:
avg by (ip_addr) (jvm_heap_heapUsed) # 호스트별 평균 힙
count by (agent_type) (jvm_heap_heapUsed) # agent_type 별 인스턴스 수
{ip_addr="192.168.80.190"} # 특정 IP 의 모든 시리즈
잘 안될 때
| 증상 | 점검 |
|---|---|
| 메트릭 이름을 모르겠음 | Metric Explorer 드롭다운 또는 /api/v1/label/__name__/values에서 실제 이름 확인 |
| 결과가 비어 있음 | label 값 오타 — /api/v1/label/{name}/values로 가능한 값 확인, agent_type 대소문자 확인 |
| Metric Explorer 로그인이 안 됨 | API 접근 키 필요 — 설정 ▸ 사용자에서 키 생성·복사 |
rate() 값이 예상과 다름 | APM은 delta 저장이라 reset 보정이 없습니다 — 함수 없이 조회한 값과 혼동하지 않았는지 확인 |
| 합계·평균이 안 맞음 | 함수 없는 조회는 마지막 샘플 — sum_over_time / avg_over_time을 명시 |
histogram_quantile이 안 됨 | 미지원 — avgRT · maxRT 같은 분위수 field를 직접 조회 |
| 장기간 조회가 느림 | step을 크게(30m~1h) 지정 — 작은 step + 긴 범위는 부하가 큽니다 |
관련 문서
- R2. 차트 지표 레퍼런스 — 메트릭별 의미·문제 신호·임계치
- E3. 지표의 의미 — APDEX · 응답시간 · 처리량 개념
- H3. 나의 대시보드 — 콘솔 안에서 차트를 모아 보기 (PromQL 불필요)
- H18. 사용자·그룹·권한 관리 — API 접근 키 발급 위치
이 장은 OPENMARU APM API 연동 가이드 7장에도 같은 내용으로 실려 있습니다. 세션 쿠키를 쓰는 JSON API(그래프 데이터·구성 정보·사용자 관리)와 함께 보려면 그 가이드를 보십시오.