Prometheus 쿼리 에디터

Prometheus 쿼리 에디터 (Prometheus query editor)

Prometheus 쿼리 에디터는 Prometheus 호환 데이터 소스에 PromQL 쿼리를 작성하게 해줘요. PromQL을 직접 쓰지 않고 쿼리를 구성할 수 있는 시각적 쿼리 빌더, 자동 완성과 구문 강조가 있는 코드 에디터, 그리고 다양한 시각화 유형에 맞는 구성 가능한 출력 형식을 포함하고 있어요. Explore 페이지나 대시보드 패널에서 패널 제목을 클릭하고 Edit을 선택해 접근할 수 있어요.

출처: 문서

본문

쿼리 에디터는 두 가지 모드가 있어요. Grafana는 두 모드를 동기화해서 서로 전환할 수 있게 해주고, 모드를 전환할 때 쿼리에서 문제를 감지하면 경고 메시지도 표시해요.

쿼리 옵션 (Query options)

다음 옵션은 Builder와 Code 모드 모두에서 사용할 수 있어요. 쿼리가 어떻게 실행되고 결과가 어떻게 표시되는지 제어해요.

Legend: 패널 범례에서 타임시리즈의 표시 이름을 제어해요.
Min step: 쿼리가 반환하는 데이터 포인트 사이의 최소 간격을 설정해요. 예를 들어 1h로 설정하면 최소 1시간 간격으로 데이터가 반환돼요. $__interval과 $__rate_interval 매크로를 지원해요.

참고: 쿼리의 시간 범위는 스텝 크기에 맞춰 정렬되므로, 반환 데이터의 실제 시작·종료 시간이 조정될 수 있어요.
Format: 쿼리 결과를 패널에서 어떻게 해석하고 표시할지 결정해요.
Type: 쿼리 유형을 결정해요. 쿼리 유형은 집계(aggregation) 계산 방식을 바꾸지 않아요. 두 유형 모두 sum, avg, count 같은 집계 연산자를 포함해 같은 PromQL 표현식을 평가해요. 유형은 Grafana가 평가하는 시점의 개수만 제어해요. 두 유형 모두 각 평가 타임스탬프에서 같은 집계를 실행하므로, Instant 쿼리는 동등한 Range 쿼리의 가장 최근 데이터 포인트와 같은 값을 반환해요. 예를 들어 sum(rate(http_requests_total[5m]))는 Instant 쿼리로는 값 하나를, Range 쿼리로는 그 값의 전체 이력을 반환하며 최종 Range 데이터 포인트가 Instant 결과와 일치해요.

참고: Grafana는 동적으로 계산된 스텝 간격에 맞춰 쿼리 시간 범위를 조정해요. 이렇게 하면 일관된 메트릭 시각화와 Prometheus 결과 캐싱이 가능해지지만, 그래프 오른쪽 가장자리에 미세한 간격이 생기거나 시작 시간이 이동하는 등 약간의 시각적 차이가 발생할 수 있어요. 예를 들어 15s 스텝은 15초로 나누어떨어지는 Unix 시간에 타임스탬프를 맞추고, 1w Min step은 주 시작(Prometheus 기준 목요일 00:00 UTC)에 맞춥니다.
Exemplars: 켜면 그래프에 exemplar를 포함해요. Exemplar는 집계된 메트릭 데이터를 특정 트레이스 예시에 연결해서, 스파이크에서 바로 관련 트레이스로 이동할 수 있게 해줘요.

참고: Exemplar는 Instant 쿼리 유형에서는 사용할 수 없어요.

Builder 모드

Builder 모드는 시각적 인터페이스로 쿼리를 구성하게 해줘요. PromQL 경험이 적은 사용자에게 가장 좋아요.

Builder 모드에는 다음 구성 요소가 있어요:

메트릭 선택 (Select a metric): 쿼리할 메트릭을 선택해요.
연산 추가 (Add operations): + Operations를 클릭해 쿼리에 연산을 추가해요. 쿼리 에디터는 연산을 카테고리로 그룹화해요. 모든 연산은 연산 헤더 아래에 함수 파라미터를 표시해요. 일부 연산은 특정 라벨을 적용할 수 있어요(예: by 또는 without 절). 유효하지 않은 쿼리가 되는 방식으로 연산을 추가하면, 쿼리 에디터가 유효한 쿼리 구조를 유지하도록 자동으로 올바른 위치에 배치해요.
힌트 (Hints): 쿼리 에디터는 선택한 특정 메트릭에 가장 적합한 연산을 감지할 수 있어요. 감지하면 + Operations 버튼 옆에 힌트를 표시하고, 클릭하면 제안된 연산을 추가해요.
메트릭 탐색기 (Metrics explorer): 메트릭 선택기 옆의 책 아이콘을 클릭하면 엽니다. 모든 메트릭을 이름·유형·설명과 함께 페이지네이션된 목록으로 보여줘요.

참고: 메트릭 탐색기(Builder 모드)와 메트릭 브라우저(Code 모드)는 별개의 구성 요소예요. 메트릭 탐색기는 라벨을 탐색하지 않지만, 메트릭 브라우저는 메트릭의 모든 라벨을 표시할 수 있어요.

Code 모드

Code 모드는 PromQL을 직접 작성하는 것을 선호하는 경험 많은 Prometheus 사용자용이에요. 자동 완성, 구문 강조, 그리고 메트릭 브라우저를 제공해요.

메트릭 브라우저 (Metrics browser): 사용 가능한 메트릭과 라벨을 탐색해 기본 쿼리를 작성하는 데 도움을 줘요. 메트릭 이름이 정확히 기억나지 않으면 라벨 몇 개를 선택해 목록을 필터링하고 옵션을 좁혀 보세요. 모든 목록에는 검색 필드가 있고, Values 섹션에서는 단일 검색 필드가 선택한 모든 라벨에 걸쳐 필터링해요.

일반적인 쿼리 패턴 (Common query patterns)

자주 쓰는 PromQL 패턴 예시들이에요. 각 예시는 PromQL 표현식과 사용할 쿼리 옵션에 대한 안내를 포함해요.

서비스별 요청 속도 (Request rate per service)

서비스별로 HTTP 요청의 초당 속도 계산:

sum(rate(http_requests_total[$__rate_interval])) by (service)

옵션	설정
Legend	`{{service}}` (Custom)
Type	Range
Min step	비워 둠 (`$__interval` 사용)

Builder 모드 단계: http_requests_total 선택 → Range functions > Rate 연산 추가 → Aggregations > Sum 연산 추가 → by 라벨을 service로 설정.

오류율 백분율 (Error rate percentage)

5xx 오류를 반환한 요청의 백분율 계산:

sum(rate(http_requests_total{status=~"5.."}[$__rate_interval])) / sum(rate(http_requests_total[$__rate_interval])) * 100

옵션	설정
Legend	`Error rate %` (Custom)
Type	Range
Format	Time series

히스토그램 분위수 (Histogram quantile, p95 지연 시간)

히스토그램 메트릭에서 95번째 백분위 요청 지속 시간 계산:

histogram_quantile(0.95, sum(rate(http_request_duration_seconds_bucket[$__rate_interval])) by (le))

옵션	설정
Legend	`p95 latency` (Custom)
Type	Range

Builder 모드 단계: http_request_duration_seconds_bucket 선택 → Range functions > Rate 추가 → Aggregations > Sum(by label le) 추가 → Functions > Histogram quantile(값 0.95) 추가.

라벨별 집계 (인스턴스별 CPU 사용량)

인스턴스별로 그룹화한 평균 CPU 사용량 백분율 계산:

100 - (avg by (instance) (rate(node_cpu_seconds_total{mode="idle"}[$__rate_interval])) * 100)

옵션	설정
Legend	`{{instance}}` (Custom)
Type	Range
Min step	15s (스크레이프 간격에 맞춤)

다중 쿼리 표현식 (사용 가능한 메모리 백분율)

파생 값을 계산하려면 여러 쿼리와 표현식을 사용해요. 쿼리 에디터에서 여러 쿼리(A, B)와 수학 표현식(C)을 추가해요:

Query A (총 메모리):

node_memory_MemTotal_bytes

Query B (사용 가능한 메모리):

node_memory_MemAvailable_bytes

Expression C (사용 가능한 백분율). + Expression을 클릭하고 Math를 선택해 추가:

$B / $A * 100

쿼리 A와 B를 Type: Instant로 설정하고 시각화에서 숨깁니다(눈 아이콘 클릭). 표현식 C만 표시해요.

알림 호환 쿼리 (타깃 다운)

스크레이프 타깃이 다운됐을 때 트리거되는 간단한 알림 쿼리:

up{job="my-service"} == 0

옵션	설정
Type	Both
Format	Time series

참고: 알림 쿼리는 템플릿 변수($variable)를 지원하지 않아요. 알림 규칙용 쿼리를 작성할 때는 고정 라벨 값을 사용하세요.

쿼리 인스펙터 사용하기 (Use the query inspector)

쿼리 인스펙터는 예상치 못한 결과나 데이터가 없는 쿼리를 디버깅하는 데 도움을 줘요. 쿼리 에디터에서 쿼리 인스펙터 아이콘을 클릭해 열 수 있어요. 일반적인 디버깅 단계로는 요청 시점 확인, 원시 데이터 확인, 오류 메시지 검토 등이 있어요.

고카디널리티 데이터 쿼리 (Query high-cardinality data)

고카디널리티 메트릭(고유 라벨 조합이 많은 메트릭)은 긴 시간 범위를 조회하면 타임아웃이 되거나 메모리 한도를 초과할 수 있어요. 효과적으로 쿼리하려면 다음을 권장해요: 시간 범위를 제한하고, 집계를 사용하며, 필요한 라벨만 유지하세요. 메모리나 샘플 한도에 도달하면 "고카디널리티 쿼리 메모리 한도 초과" 문서를 참고하세요.

기대되는 PromQL 동작 (Expected PromQL behaviors)

버그로 오해받기 쉽지만 실제로는 기대되는 Prometheus 동작들이에요.

increase()가 정수 카운터에서 분수 값을 반환

increase()는 지정된 시간 창 동안의 증가량을 추정하기 위해 선형 보간을 사용해요. 스크레이프 타임스탬프가 창 경계와 정확히 일치하는 경우가 드물기 때문에 결과가 보간되어 정수 카운터에서도 분수 값이 생성돼요. 이는 정상이에요. 정수 결과가 필요하면 표현식을 ceil()이나 floor()로 감싸면 돼요:

ceil(increase(http_requests_total[5m]))

rate()가 시간이 지나며 계속 늘어나는 것처럼 보임

rate()가 안정적인 초당 속도 대신 계속 증가하는 값으로 보이면, 가장 흔한 원인은 고유한 구분 라벨 없이 여러 인스턴스가 같은 타임시리즈에 쓰는 경우예요. Prometheus는 이를 인위적으로 증가하는 카운터가 있는 단일 시리즈로 병합해요. 이를 고치려면 모든 스크레이프 타깃이 고유 라벨(예: instance, pod, node)을 갖도록 하고, 명시적으로 집계하세요:

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

배포나 스케일링 이벤트 후에 이런 현상이 보이면, 서비스 디스커버리가 각 타깃에 고유한 instance 라벨을 할당하는지 확인하세요.

Pod 재시작 후 카운터 리셋 스파이크

모니터링되는 프로세스가 재시작되면 카운터가 0으로 리셋돼요. Prometheus는 카운터 리셋 감지로 이를 처리해서, rate()와 increase()가 리셋을 반영하고 음수 값을 생성하지 않아요. 하지만 재시작 후 첫 스크레이프가 재시작 이후 누적된 전체 카운터 값을 보고하므로 리셋 지점에 짧은 스파이크가 보일 수 있어요.

라벨 카디널리티로 "too many time series" 오류 발생

라벨 필터를 추가해도 결과 수가 줄지 않으면 메트릭에 고카디널리티 라벨(예: request_id, user_id)이 있을 수 있어요. Prometheus TSDB 상태 페이지(/tsdb-status)나 Grafana 메트릭 탐색기로 고카디널리티 라벨 조합을 식별한 뒤, 스크레이프 시 불필요한 라벨을 제거하거나 쿼리에서 집계를 사용하세요.

Prometheus 쿼리 에디터