쿼리 예시

쿼리 예시 (Query examples)

PromQL(프로메테우스 쿼리 언어)이 실제로 어떻게 쓰이는지, 대표적인 예시들로 감을 잡아보는 문서예요. 시계열을 선택하는 기초부터 서브쿼리, 함수·연산자 조합, 집계에 이르기까지 자주 쓰는 표현식을 하나씩 코드로 보여주고 있어요. 개념 설명보다는 "이런 걸 하고 싶으면 이렇게 써요"라는 실전 레시피 모음이라고 보면 돼요.

각 예시는 프로메테우스 표현식 브라우저나 HTTP API에 바로 넣어서 실행해 볼 수 있어요. 옆에서 하나씩 따라 치면서 결과가 어떻게 달라지는지 확인해 보세요. 기본적인 시계열 선택부터 배워볼게요.

출처: 문서

본문

간단한 시계열 선택

메트릭이 http_requests_total인 모든 시계열을 반환하려면:

http_requests_total

메트릭이 http_requests_total이고 주어진 job과 handler 레이블을 가진 모든 시계열을 반환하려면:

http_requests_total{job="apiserver", handler="/api/comments"}

같은 벡터에 대해 시간 범위(여기서는 쿼리 시점까지 5분) 전체를 반환하려면, 범위 벡터가 됩니다:

http_requests_total{job="apiserver", handler="/api/comments"}[5m]

범위 벡터를 만드는 표현식은 직접 그래프로 그릴 수 없고, 표현식 브라우저의 테이블("Console") 보기에서만 볼 수 있다는 점에 주의하세요.

정규식을 사용하면 이름이 특정 패턴과 일치하는 job의 시계열만 선택할 수 있어요. 여기서는 server로 끝나는 모든 job을 선택합니다:

http_requests_total{job=~".*server"}

4xx가 아닌 모든 HTTP 상태 코드를 선택하려면 다음처럼 할 수 있어요:

http_requests_total{status!~"4.."}

서브쿼리 (Subquery)

http_requests_total 메트릭의 5분 rate를 지난 30분 동안 1분 해상도로 반환하려면:

rate(http_requests_total[5m])[30m:1m]

이것은 중첩 서브쿼리의 예시예요. deriv 함수의 서브쿼리는 기본 해상도를 사용해요. 서브쿼리를 불필요하게 사용하는 것은 현명하지 않다는 점에 주의하세요.

max_over_time(deriv(rate(distance_covered_total[5s])[30s:5s])[10m:])

함수, 연산자 등 사용하기

메트릭 이름이 http_requests_total인 모든 시계열의 초당 rate를, 지난 5분 동안 측정된 값으로 반환하려면:

rate(http_requests_total[5m])

http_requests_total 시계열이 모두 job(job 이름별 팬아웃)과 instance(job 인스턴스별 팬아웃) 레이블을 갖고 있다고 가정할 때, 모든 인스턴스의 rate를 합산해 출력 시계열 수는 줄이면서 job 차원은 유지하고 싶을 수 있어요:

sum by (job) (
  rate(http_requests_total[5m])
)

동일한 차원 레이블을 가진 두 개의 서로 다른 메트릭이 있으면, 이진 연산자를 적용할 수 있고 양쪽에서 같은 레이블 세트를 가진 요소가 매칭되어 출력으로 전파돼요. 예를 들어 이 표현식은 각 인스턴스의 사용되지 않은 메모리를 MiB 단위로 반환해요(가상의 클러스터 스케줄러가 자기가 실행하는 인스턴스에 대한 이런 메트릭을 노출한다고 가정):

(instance_memory_limit_bytes - instance_memory_usage_bytes) / 1024 / 1024

같은 표현식을 애플리케이션별로 합산하면 다음과 같이 쓸 수 있어요:

sum by (app, proc) (
  instance_memory_limit_bytes - instance_memory_usage_bytes
) / 1024 / 1024

같은 가상의 클러스터 스케줄러가 각 인스턴스에 대해 다음과 같은 CPU 사용 메트릭을 노출한다면:

instance_cpu_time_ns{app="lion", proc="web", rev="34d0f99", env="prod", job="cluster-manager"}
instance_cpu_time_ns{app="elephant", proc="worker", rev="34d0f99", env="prod", job="cluster-manager"}
instance_cpu_time_ns{app="turtle", proc="api", rev="4d3a513", env="prod", job="cluster-manager"}
instance_cpu_time_ns{app="fox", proc="widget", rev="4d3a513", env="prod", job="cluster-manager"}
...

...애플리케이션(app)과 프로세스 타입(proc)별로 그룹화된 CPU 최다 사용 상위 3개를 이렇게 얻을 수 있어요:

topk(3, sum by (app, proc) (rate(instance_cpu_time_ns[5m])))

이 메트릭이 실행 중인 인스턴스마다 하나의 시계열을 포함한다고 가정하면, 애플리케이션별 실행 중인 인스턴스 수를 이렇게 셀 수 있어요:

count by (app) (instance_cpu_time_ns)

어떤 메트릭의 레이블을 탐색해서 그중 일부로 집계하고 싶다면 다음과 같이 할 수 있어요:

limitk(10, app_foo_metric_bar)

또는 반환된 시계열을 더 고르게 샘플링하고 싶다면, 대략 10%를 얻기 위해 다음을 사용할 수 있어요:

limit_ratio(0.1, app_foo_metric_bar)

더 알아보기 (Learn more)

PromQL 기초 — 시계열 셀렉터와 정규식, 범위 벡터의 기본
함수(Functions) — rate, deriv, topk 등 쿼리에서 쓸 수 있는 모든 함수
연산자(Operators) — 산술·비교·집합·논리 연산자와 벡터 매칭
HTTP API — 쿼리를 HTTP 요청으로 실행하는 방법