7. PromQL 연동
이미 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에는 없는 편의 기능)
어떤 메트릭이 어떤 의미인지는 OPENMARU APM 사용자 매뉴얼 R2. 차트 지표 레퍼런스와 OPENMARU APM 사용자 매뉴얼 E3. 지표의 의미를 보세요. 콘솔 안에서 차트를 모아 보려면 OPENMARU APM 사용자 매뉴얼 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 + 긴 범위는 부하가 큽니다 |
관련 문서
- OPENMARU APM 사용자 매뉴얼 R2. 차트 지표 레퍼런스 — 메트릭별 의미·문제 신호·임계치
- OPENMARU APM 사용자 매뉴얼 E3. 지표의 의미 — APDEX · 응답시간 · 처리량 개념
- OPENMARU APM 사용자 매뉴얼 H3. 나의 대시보드 — 콘솔 안에서 차트를 모아 보기 (PromQL 불필요)
- OPENMARU APM 사용자 매뉴얼 H18. 사용자·그룹·권한 관리 — API 접근 키 발급 위치