Prometheus HTTP API — 추출 가능 데이터 리스트

1. API 개요

항목 내용
Base Path /api/v1
응답 형식 JSON
인증 별도 설정 시 Basic Auth / TLS 지원

2. 전체 엔드포인트 목록

카테고리 엔드포인트 메서드 설명
쿼리 /api/v1/query GET/POST 특정 시점의 Instant 쿼리
/api/v1/query_range GET/POST 시간 범위의 Range 쿼리
/api/v1/format_query GET/POST PromQL 표현식 포맷팅
메타데이터 /api/v1/series GET/POST 라벨 매처로 시계열 검색
/api/v1/labels GET/POST 라벨 이름 목록 조회
/api/v1/label/<name>/values GET 특정 라벨의 값 목록 조회
/api/v1/metadata GET 메트릭 메타데이터 조회
타겟 /api/v1/targets GET 스크래핑 타겟 상태 조회
/api/v1/targets/metadata GET 타겟의 메트릭 메타데이터 조회
/api/v1/scrape_pools GET 스크래핑 풀 목록 조회
규칙/알림 /api/v1/rules GET 알림/레코딩 규칙 목록 조회
/api/v1/alerts GET 현재 활성 알림 목록 조회
/api/v1/alertmanagers GET Alertmanager 상태 조회
상태 /api/v1/status/config GET 현재 로드된 설정 파일
/api/v1/status/flags GET 실행 플래그 값
/api/v1/status/runtimeinfo GET 런타임 정보
/api/v1/status/buildinfo GET 빌드 정보
/api/v1/status/tsdb GET TSDB 카디널리티 통계
/api/v1/status/tsdb/blocks GET TSDB 블록 목록 (실험적)
Exemplar /api/v1/query_exemplars GET/POST Exemplar 조회 (실험적)
Admin (TSDB) /api/v1/admin/tsdb/snapshot POST TSDB 스냅샷 생성
/api/v1/admin/tsdb/delete_series POST 시계열 삭제
/api/v1/admin/tsdb/clean_tombstones POST 삭제 마커 정리
Remote Write /api/v1/write POST Remote Write 수신

Admin API는 --web.enable-admin-api 플래그를 활성화해야 사용할 수 있습니다.

3. Expression 쿼리 (데이터 조회의 핵심)

3-1. Instant Query — /api/v1/query

특정 시점에 PromQL 표현식을 평가합니다.

파라미터 필수 설명
query ✅ PromQL 쿼리 문자열
time 평가 시점 (RFC3339 또는 Unix 타임스탬프). 생략 시 현재 시간
timeout 쿼리 타임아웃
limit 반환할 최대 시계열 수
lookback_delta Lookback 기간 오버라이드
stats all 설정 시 쿼리 통계 포함

응답 resultType: vector, matrix, scalar, string

3-2. Range Query — /api/v1/query_range

시간 범위에 걸쳐 PromQL 표현식을 평가합니다.

파라미터 필수 설명
query ✅ PromQL 쿼리 문자열
start ✅ 시작 타임스탬프 (inclusive)
end ✅ 종료 타임스탬프 (inclusive)
step ✅ 쿼리 해상도 간격 (예: 15s, 1m, 5m)
timeout 쿼리 타임아웃
limit 반환할 최대 시계열 수
lookback_delta Lookback 기간 오버라이드
stats all 설정 시 쿼리 통계 포함

응답 resultType: 항상 matrix

4. 응답 결과 형식 (Result Formats)

resultType 설명 데이터 구조
vector (Instant Vector) 특정 시점의 시계열 목록 metric (라벨셋) + value [타임스탬프, 값]
matrix (Range Vector) 시간 범위의 시계열 목록 metric (라벨셋) + values [[타임스탬프, 값], ...]
scalar 단일 숫자 값 [타임스탬프, 값]
string 단일 문자열 값 [타임스탬프, 문자열]
histogram (Native) 네이티브 히스토그램 count, sum, buckets [[boundary_rule, left, right, count], ...]

5. 메타데이터 쿼리

5-1. 시계열 검색 — /api/v1/series

파라미터 필수 설명
match[] ✅ 시계열 셀렉터 (반복 가능)
start 시작 타임스탬프
end 종료 타임스탬프
limit 반환할 최대 시계열 수

반환: 매칭되는 시계열의 라벨 이름/값 쌍 목록

5-2. 라벨 이름 목록 — /api/v1/labels

파라미터 필수 설명
start 시작 타임스탬프
end 종료 타임스탬프
match[] 시계열 셀렉터 (반복 가능)
limit 반환할 최대 수

반환: 라벨 이름 문자열 배열

5-3. 라벨 값 목록 — /api/v1/label/<label_name>/values

파라미터 필수 설명
start 시작 타임스탬프
end 종료 타임스탬프
match[] 시계열 셀렉터 (반복 가능)
limit 반환할 최대 수

반환: 해당 라벨의 값 문자열 배열

5-4. 메트릭 메타데이터 — /api/v1/metadata

파라미터 필수 설명
metric 특정 메트릭 이름으로 필터
limit 반환할 최대 메트릭 수
limit_per_metric 메트릭당 반환할 최대 메타데이터 수

반환 데이터:

필드 설명
type 메트릭 유형 (counter, gauge, histogram, summary)
help 메트릭 설명
unit 단위

6. 타겟(Target) 정보

6-1. 타겟 상태 — /api/v1/targets

파라미터 필수 설명
state active, dropped, any로 필터
scrapePool 스크래핑 풀 이름으로 필터

Active Target 반환 데이터:

필드 설명
discoveredLabels 서비스 디스커버리에서 가져온 원본 라벨
labels 리라벨링 후 최종 라벨
scrapePool 스크래핑 풀 이름
scrapeUrl 스크래핑 URL
lastError 마지막 에러 메시지
lastScrape 마지막 스크래핑 시간
lastScrapeDuration 마지막 스크래핑 소요 시간 (초)
health 타겟 상태 (up / down)
scrapeInterval 스크래핑 주기
scrapeTimeout 스크래핑 타임아웃

6-2. 타겟 메트릭 메타데이터 — /api/v1/targets/metadata

파라미터 필수 설명
match_target 라벨 셀렉터로 타겟 필터
metric 특정 메트릭 이름으로 필터
limit 반환할 최대 타겟 수

반환: 타겟별 메트릭의 type, help, unit

7. 규칙 및 알림

7-1. 규칙 목록 — /api/v1/rules

파라미터 필수 설명
type alert 또는 record로 필터
rule_name[] 규칙 이름으로 필터
rule_group[] 규칙 그룹 이름으로 필터
file[] 파일 경로로 필터
exclude_alerts true 시 활성 알림 제외
match[] 라벨 셀렉터로 필터

반환 데이터 (Alerting Rule):

필드 설명
name 규칙 이름
query PromQL 쿼리
duration 알림 대기 시간 (초)
labels 규칙 라벨
annotations 규칙 어노테이션
health 규칙 상태
alerts 현재 활성 알림 목록
type alerting 또는 recording

7-2. 활성 알림 — /api/v1/alerts

반환 데이터:

필드 설명
activeAt 알림 활성화 시간
annotations 어노테이션
labels 알림 라벨 (alertname 포함)
state 상태 (firing, pending)
value 현재 값

7-3. Alertmanager 상태 — /api/v1/alertmanagers

반환: activeAlertmanagers와 droppedAlertmanagers의 URL 목록

8. 서버 상태 정보

8-1. 설정 — /api/v1/status/config

반환: 현재 로드된 설정 파일 (YAML 문자열)

8-2. 실행 플래그 — /api/v1/status/flags

반환: Prometheus 실행 시 설정된 플래그 key-value 쌍

8-3. 런타임 정보 — /api/v1/status/runtimeinfo

필드 설명
startTime 서버 시작 시간
CWD 현재 작업 디렉토리
hostname 호스트명
serverTime 현재 서버 시간
reloadConfigSuccess 마지막 설정 리로드 성공 여부
lastConfigTime 마지막 설정 리로드 시간
timeSeriesCount 현재 시계열 수
corruptionCount 손상 카운트
goroutineCount 고루틴 수
GOMAXPROCS Go 최대 프로세서 수
storageRetention 스토리지 보존 기간

8-4. 빌드 정보 — /api/v1/status/buildinfo

필드 설명
version Prometheus 버전
revision Git 리비전
branch Git 브랜치
buildUser 빌드 사용자
buildDate 빌드 일시
goVersion Go 버전

8-5. TSDB 통계 — /api/v1/status/tsdb

필드 설명
headStats.numSeries 현재 시계열 수
headStats.chunkCount 청크 수
headStats.minTime 최소 타임스탬프 (ms)
headStats.maxTime 최대 타임스탬프 (ms)
seriesCountByMetricName 메트릭 이름별 시계열 수
labelValueCountByLabelName 라벨 이름별 값 개수
memoryInBytesByLabelName 라벨 이름별 메모리 사용량 (bytes)
seriesCountByLabelValuePair 라벨 값 쌍별 시계열 수

8-6. TSDB 블록 — /api/v1/status/tsdb/blocks (실험적)

필드 설명
ulid 블록 고유 ID
minTime 블록 최소 타임스탬프 (ms)
maxTime 블록 최대 타임스탬프 (ms)
stats.numSeries 블록 내 시계열 수
stats.numSamples 블록 내 샘플 수
stats.numChunks 블록 내 청크 수
compaction.level 컴팩션 레벨

9. Admin API (TSDB 관리)

--web.enable-admin-api 플래그 필요

엔드포인트 메서드 설명 주요 파라미터
/api/v1/admin/tsdb/snapshot POST TSDB 스냅샷 생성 —
/api/v1/admin/tsdb/delete_series POST 시계열 데이터 삭제 match[] (필수), start, end
/api/v1/admin/tsdb/clean_tombstones POST 삭제 마커(tombstone) 정리 —

10. PromQL 주요 함수 (쿼리 시 활용)

Prometheus는 Langfuse와 달리 미리 정의된 metric/dimension이 아니라, PromQL 함수를 조합하여 지표를 산출합니다.

10-1. 집계 함수

함수 설명
sum() 합계
avg() 평균
min() 최솟값
max() 최댓값
count() 시계열 수
stddev() 표준편차
stdvar() 분산
topk(k, ...) 상위 k개
bottomk(k, ...) 하위 k개
quantile(φ, ...) φ 분위수 (0~1)
count_values() 값별 시계열 수
group() 그룹핑 (값 = 1)

모든 집계 함수에 by (label) 또는 without (label)로 그룹핑 차원 지정 가능

10-2. 변환/비율 함수

함수 설명
rate(v[d]) 초당 평균 증가율 (counter용)
irate(v[d]) 순간 증가율 (마지막 두 샘플 기반)
increase(v[d]) 구간 내 총 증가량
delta(v[d]) 구간 내 변화량 (gauge용)
deriv(v[d]) 선형 회귀 기반 초당 변화율
predict_linear(v[d], t) t초 후 예측값
histogram_quantile(φ, v) 히스토그램에서 φ 분위수 계산
changes(v[d]) 구간 내 값 변경 횟수
resets(v[d]) 구간 내 counter 리셋 횟수

10-3. 시간 관련 함수

함수 설명
time() 현재 Unix 타임스탬프
timestamp(v) 샘플의 타임스탬프
day_of_week() 요일 (0=일요일)
hour() 시간 (0~23)

10-4. 수학/변환 함수

함수 설명
abs() 절대값
ceil() 올림
floor() 내림
round() 반올림
ln() / log2() / log10() 로그 함수
exp() 지수 함수
sqrt() 제곱근
clamp(v, min, max) 값 범위 제한
label_replace() 라벨 값 치환
label_join() 라벨 값 결합

11. 위 데이터로 뽑을 수 있는 지표 정리

11-1. 인프라/시스템 모니터링

지표 사용 메트릭 (예시) PromQL 예시
CPU 사용률 node_cpu_seconds_total 1 - avg by(instance)(rate(node_cpu_seconds_total{mode="idle"}[5m]))
메모리 사용률 node_memory_MemTotal_bytes, node_memory_MemAvailable_bytes 1 - (node_memory_MemAvailable_bytes / node_memory_MemTotal_bytes)
디스크 사용률 node_filesystem_avail_bytes, node_filesystem_size_bytes 1 - (node_filesystem_avail_bytes / node_filesystem_size_bytes)
네트워크 트래픽 node_network_receive_bytes_total rate(node_network_receive_bytes_total[5m])
시스템 로드 node_load1, node_load5, node_load15 직접 조회

11-2. 애플리케이션 성능 (RED Method)

지표 사용 메트릭 (예시) PromQL 예시
요청률 (Rate) http_requests_total sum(rate(http_requests_total[5m])) by (service)
에러율 (Errors) http_requests_total sum(rate(http_requests_total{status=~"5.."}[5m])) / sum(rate(http_requests_total[5m]))
응답 시간 (Duration) http_request_duration_seconds_bucket histogram_quantile(0.95, sum(rate(http_request_duration_seconds_bucket[5m])) by (le))
P99 지연시간 http_request_duration_seconds_bucket histogram_quantile(0.99, sum(rate(http_request_duration_seconds_bucket[5m])) by (le))
초당 처리량 (TPS) http_requests_total sum(rate(http_requests_total[1m]))

11-3. 컨테이너/쿠버네티스 모니터링

지표 사용 메트릭 (예시) PromQL 예시
컨테이너 CPU 사용률 container_cpu_usage_seconds_total rate(container_cpu_usage_seconds_total[5m]) by (pod)
컨테이너 메모리 사용량 container_memory_usage_bytes 직접 조회, by (pod) 그룹핑
Pod 재시작 횟수 kube_pod_container_status_restarts_total increase(kube_pod_container_status_restarts_total[1h])
노드별 Pod 수 kube_pod_info count by (node)(kube_pod_info)
Deployment 가용 레플리카 kube_deployment_status_replicas_available 직접 조회

11-4. Prometheus 자체 모니터링

지표 사용 메트릭 (예시) PromQL 예시
스크래핑 성공률 up avg(up) by (job)
스크래핑 소요 시간 scrape_duration_seconds avg(scrape_duration_seconds) by (job)
활성 시계열 수 /api/v1/status/tsdb headStats.numSeries (API 직접 조회)
알림 발화 중 수 ALERTS count(ALERTS{alertstate="firing"})
규칙 평가 소요 시간 prometheus_rule_group_duration_seconds avg(prometheus_rule_group_duration_seconds)
쿼리 지연 시간 prometheus_engine_query_duration_seconds histogram_quantile(0.99, rate(prometheus_engine_query_duration_seconds_bucket[5m]))

11-5. 알림 관련

지표 사용 데이터 산출 방법
현재 활성 알림 목록 /api/v1/alerts 직접 조회하여 firing/pending 상태별 확인
알림 규칙별 상태 /api/v1/rules?type=alert 규칙별 health, alerts 수 확인
Alertmanager 연결 상태 /api/v1/alertmanagers active/dropped 목록 확인

11-6. 복합 지표 (여러 메트릭 조합)

지표 사용 메트릭 PromQL 예시
에러 예산 소진율 (SLO) http_requests_total 1 - (sum(rate(http_requests_total{status!~"5.."}[30d])) / sum(rate(http_requests_total[30d])))
리소스 포화도 CPU + Memory + Disk 각각 사용률을 계산 후 종합 판단
트래픽 이상 탐지 http_requests_total rate(http_requests_total[5m]) > 2 * avg_over_time(rate(http_requests_total[5m])[1h:])
용량 예측 (디스크) node_filesystem_avail_bytes predict_linear(node_filesystem_avail_bytes[7d], 30*24*3600)
Apdex 점수 http_request_duration_seconds_bucket 만족/허용/불만족 기준으로 bucket 비율 계산

results matching ""

    No results matching ""

    results matching ""

      No results matching ""