PromQL 쿼리 작성 시 흔히 발생하는 오류와 그 해결 방법을 학습했습니다. 특히 Grafana에서 PromQL을 올바르게 사용하기 위한 이해와 실제 적용 방안에 초점을 맞추었습니다.

PromQL 쿼리 에러 해결: Grafana에서 PromQL 제대로 사용하는 법

학습 주제

오늘 공부한 주제: PromQL 쿼리 에러 해결 및 Grafana 활용법
대화 제목: PromQL 쿼리 에러 해결
학습 날짜: 2026년 2월 6일

질문과 탐구

주요 질문들은 다음과 같았습니다.

"PromQL 쿼리에서 unexpected identifier "idle" 에러는 왜 발생하는가?"
"Grafana의 빌더 모드가 쿼리에 자동으로 중괄호를 추가하는 이유는 무엇인가?"
"PromQL 쿼리의 각 부분이 정확히 무엇을 의미하는가?"
"그래프에 표시되는 여러 시리즈의 의미와 이름을 어떻게 구분할 수 있는가?"
"메모리, 디스크, 온도 등의 지표를 Grafana에서 어떻게 모니터링할 수 있는가?"
"쿼리는 하나인데 왜 그래프에는 두 개의 시리즈가 나타나는가?"

이러한 질문들을 탐구하며 PromQL의 문법, Grafana의 쿼리 빌더 동작 방식, 그리고 Prometheus 메트릭의 라벨 구조까지 파고들었습니다.

핵심 학습 내용

가장 중요했던 학습 내용은 Grafana에서 PromQL 쿼리를 입력하는 방식에 대한 것이었습니다.

Grafana 쿼리 구조의 이해

ChatGPT는 Grafana가 쿼리를 처리하는 과정을 다음과 같이 설명했습니다.

사용자가 쿼리 입력: Grafana의 Metric 칸에 PromQL 쿼리를 직접 입력합니다.
Grafana의 JSON 감싸기 (Builder 모드): Grafana의 쿼리 빌더 모드에서는 사용자가 입력한 PromQL 쿼리를 내부적으로 JSON 형식으로 감싸서 "Operations" 섹션 등에 보여줍니다.
Prometheus API 전송: Grafana는 이 JSON 형식의 쿼리를 Prometheus API로 전송합니다.
Prometheus의 PromQL 파싱: Prometheus는 전송받은 JSON 내부의 query 값을 PromQL로 파싱하려고 시도합니다.

이 과정에서 문제가 발생하는 이유는, 사용자가 이미 PromQL 쿼리를 입력했음에도 불구하고 Grafana가 이를 다시 JSON으로 감싸면서 불필요한 중괄호({})나 따옴표(")가 추가되어 PromQL 파서가 이를 잘못 해석하게 되기 때문입니다.

문제의 핵심: Grafana의 빌더 모드에서 Operations 섹션에 표시되는 { \"...\" } 형태는 참고용일 뿐, 실제 쿼리 입력칸(Metric)에는 순수한 PromQL 쿼리만 들어가야 합니다.

정석 PromQL 쿼리

Grafana 쿼리 창에 그대로 입력해야 하는 올바른 PromQL 쿼리 예시는 다음과 같습니다.

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

이 쿼리는 서버의 CPU 사용률을 계산하는 표준적인 방법입니다.

쿼리의 각 부분별 의미

node_cpu_seconds_total{mode="idle"}: CPU가 아무 작업도 하지 않고 쉬고 있는 시간의 누적 카운트.
rate(...[5m]): 최근 5분 동안의 초당 idle 시간 증가율 (즉, idle 비율).
avg by (instance)(...): 각 서버(instance)별 코어들의 idle 비율을 평균.
* 100: 소수점 비율을 퍼센트로 변환.
100 - ...: 전체 시간(100%)에서 idle 비율을 빼서 실제 CPU 사용률 계산.

라벨(Label)의 중요성과 시리즈 분리

Prometheus 메트릭은 instance, mountpoint, device 등 다양한 라벨을 가질 수 있습니다. avg by (instance)와 같은 집계 함수를 사용해도, 메트릭 자체에 여러 라벨 조합이 존재하면 Grafana는 이를 별개의 시리즈로 구분하여 표시합니다. 예를 들어, 디스크 사용률의 경우 mountpoint 라벨(/, /tmp 등)에 따라 여러 개의 시리즈가 나타날 수 있습니다.

해결 방법 요약

Code 모드 사용: Grafana에서 쿼리를 작성할 때는 반드시 Code 모드를 사용하여 빌더의 자동 변환을 피해야 합니다.
정확한 PromQL 입력: Metric 칸에만 순수한 PromQL 쿼리를 입력합니다.
라벨 이해: Prometheus 메트릭의 라벨 구조를 이해하고, 필요한 경우 mountpoint="/" 와 같이 특정 라벨을 필터링하거나 avg by (instance) 등으로 집계하여 원하는 시리즈만 표시합니다.
레전드 템플릿 활용: {{instance}} {{mountpoint}}와 같이 레전드 템플릿을 설정하여 각 시리즈가 어떤 데이터를 의미하는지 명확하게 구분합니다.

이해한 내용

이번 학습을 통해 PromQL 쿼리 자체의 문법만큼이나, **쿼리가 실행되는 환경(Grafana)과 메트릭의 구조(라벨)**를 이해하는 것이 중요함을 깨달았습니다. 특히 Grafana의 빌더 모드가 사용자에게 편리함을 제공하지만, 복잡한 쿼리에서는 오히려 혼란을 야기할 수 있다는 점을 명확히 이해했습니다.

또한, CPU 사용률 뿐만 아니라 메모리, 디스크, 라즈베리파이 온도까지 다양한 시스템 지표를 PromQL로 어떻게 조회하고 Grafana에서 시각화할 수 있는지 구체적인 예시를 통해 배웠습니다. node_filesystem_free_bytes와 node_filesystem_size_bytes를 이용한 디스크 사용률 계산 시, /와 /tmp (tmpfs)를 구분하여 /만 정확히 모니터링하는 방법을 알게 된 것이 큰 수확입니다.

실전 적용

이 지식을 활용하여 제 서버(라즈베리파이)의 시스템 상태를 더욱 효과적으로 모니터링할 계획입니다.

실습 계획:
- Grafana 대시보드에서 CPU, 메모리, 디스크 사용률, 그리고 라즈베리파이 CPU 온도를 한 패널에 통합하여 표시합니다.
- 각 지표별로 {{instance}} 또는 {{instance}} {{mountpoint}}와 같은 직관적인 레전드 템플릿을 적용하여 어떤 서버의 어떤 자원인지 명확히 구분합니다.
- 디스크 사용률 쿼리 시, tmpfs인 /tmp를 제외하고 루트 파일 시스템(/)만 정확히 모니터링하도록 PromQL을 수정합니다.
- 네트워크 트래픽, 로드 애버리지 등 추가적인 지표도 점진적으로 대시보드에 추가하여 시스템 전반을 종합적으로 파악합니다.
응용 아이디어:
- 각 자원의 임계치를 설정하여 Grafana 알림 기능을 활용합니다. (예: CPU 사용률 90% 초과 시 알림)
- 다양한 라즈베리파이 인스턴스들의 성능을 비교 분석하는 대시보드를 구성합니다.
- 컨테이너 환경에서도 동일한 원리가 적용되는지 테스트해봅니다.

추가 학습 계획

이번 학습을 통해 PromQL의 기본기를 다질 수 있었지만, 더 깊이 공부하고 싶은 부분들이 생겼습니다.

PromQL 함수 및 연산자 탐구: sum, count, avg_over_time 등 다양한 PromQL 함수와 연산자의 활용법을 익히고 싶습니다.
Alertmanager 연동: Prometheus의 Alertmanager를 설정하여 특정 조건 발생 시 알림을 받는 방법을 공부할 예정입니다.
Exporter 종류별 메트릭 이해: node_exporter 외에 다른 Exporter(예: redis_exporter, kube-state-metrics)들이 제공하는 메트릭들을 이해하고 활용하는 방법을 배우고 싶습니다.
Grafana 시각화 옵션 심화: 히트맵, 그래프의 상관관계 분석 등 Grafana의 고급 시각화 기능을 탐구할 예정입니다.

참고 자료

Prometheus 공식 문서: PromQL 함수, 메트릭, 라벨 등에 대한 심도 있는 정보를 얻을 수 있습니다.
Grafana 공식 문서: 대시보드 구성, 패널 편집, 변수 활용 등에 대한 자세한 가이드라인을 제공합니다.
node_exporter GitHub 저장소: node_exporter가 수집하는 메트릭 종류와 옵션에 대한 정보를 얻을 수 있습니다. (특히 --collector.thermal_zone 옵션 등)