PromQL 쿼리 기초
PromQL 쿼리 기초
수집한 데이터를 "깎아내서" 원하는 값을 뽑으려면 질의가 필요하죠. Prometheus가 제공하는 함수형 질의 언어가 바로 **PromQL(Prometheus Query Language)**이에요. 이 언어로 시계열 데이터를 실시간으로 선택하고 집계할 수 있어요. 이 글에서는 인스턴트 쿼리와 레인지 쿼리의 차이, 시계열 셀렉터, 정규식, 그리고 흔한 함정까지 잡아드릴게요.
인스턴트 쿼리와 레인지 쿼리
Prometheus에 쿼리를 보내면 두 종류가 돼요. **인스턴트 쿼리(instant query)**는 한 시점에서 평가되고, **레인지 쿼리(range query)**는 시작과 끝 시간 사이의 균등한 간격(step)으로 평가돼요. PromQL 자체는 두 경우 완전히 같게 동작해요. 레인지 쿼리는 서로 다른 타임스탬프에서 인스턴트 쿼리를 여러 번 실행한 것과 마찬가지니까요. Prometheus UI에서는 Table 탭이 인스턴트 쿼리용이고, Graph 탭이 레인지 쿼리용이에요. 다른 프로그램은 HTTP API를 통해 PromQL 표현식의 결과를 가져올 수 있어요.
샘플(Samples)에 대해
PromQL 문서에서 "히스토그램 샘플(histogram sample)"은 항상 네이티브 히스토그램을 가리켜요. "클래식 히스토그램(classic histogram)"은 _bucket, _count, _sum 접미사를 가진 부동소수점 샘플 시계열들의 묶음으로 하나의 히스토그램을 표현하는 것을 말해요. 부동소수점 샘플과 히스토그램 샘플 모두 카운터나 게이지 "성격(flavor)"을 가질 수 있어요. 부동소수점의 카운터·게이지는 보통 그냥 "카운터", "게이지"라 부르고, 히스토그램 버전은 "카운터 히스토그램", "게이지 히스토그램"이라 불러요.
시계열 셀렉터
인스턴트 벡터 셀렉터
아래 예제는 http_requests_total이라는 메트릭 이름 중에서 job 라벨이 prometheus이고 group 라벨이 canary인 시계열만 선택해요.
http_requests_total{job="prometheus",group="canary"}
레인지 벡터 셀렉터
다음 예제는 메트릭 이름이 http_requests_total이고 job 라벨이 prometheus인 모든 시계열에서, 5분 전보다 이내에 기록된 모든 값을 선택해요.
http_requests_total{job="prometheus"}[5m]
오프셋(offset) 수정자
오프셋은 레인지 벡터에서도 동일하게 동작해요. 아래는 http_requests_total이 일주일 전에 가졌던 5분 비율을 돌려주는 식이에요.
rate(http_requests_total[5m] offset 1w)
과거의 샘플을 질의할 때, 음수 오프셋을 쓰면 시간상 앞으로의 비교가 가능해져요.
rate(http_requests_total[5m] offset -1w)
정규식
Prometheus의 모든 정규식은 RE2 문법을 따르고, 정규식 매칭은 항상 완전히 고정(fully anchored)돼요.
함정(Gotchas)
스테일니스(Staleness)
Prometheus는 각 관련 시계열에 대해 해당 타임스탬프의 값을 지정해야 해요. 이때 룩백(lookback) 기간보다 과거가 아닌 가장 최신 샘플을 가져다 씁니다. 룩백 기간은 기본이 5분이지만, --query.lookback-delta 플래그로 바꾸거나 개별 쿼리에서 lookback_delta 파라미터로 덮어쓸 수 있어요.
느린 쿼리와 과부하 피하기
쿼리가 상당한 양의 데이터를 다뤄야 하면 그래프로 그릴 때 타임아웃이 나거나 서버·브라우저에 과부하가 걸릴 수 있어요. 그래서 모르는 데이터 위에서 쿼리를 만들 때는 항상 표현식 브라우저의 테이블 뷰에서 시작해서 결과 집합이 합리적이 될 때까지(수백 개, 많아야 수천 개의 시계열) 다듬어야 해요. 충분히 필터링·집계한 뒤에 그래프 모드로 전환하세요. 표현식이 여전히 즉석 그래프로 느리다면 기록 규칙(recording rule)으로 미리 기록해두는 게 좋아요. 특히 PromQL에서 api_http_requests_total 같은 알몸 메트릭 이름 셀렉터는 서로 다른 라벨을 가진 수천 개의 시계열로 확장될 수 있으니 주의해야 해요.