Prometheus 메트릭으로 Grafana 대시보드 만들기
Grafana와 Prometheus를 연결하고 Linux 호스트의 CPU·메모리를 시각화합니다. 인스턴스 변수, 커뮤니티 템플릿, 컨테이너 네트워크·영속화와 프로비저닝의 전제도 설명합니다.
쿼리가 정상 실행돼도 대시보드가 잘못된 의미를 전달할 수 있습니다. 코어별 유휴 시간은 호스트 CPU 사용률과 다르고, 구간 평균으로 설정한 게이지는 최신 값을 보여 주는 것이 아닙니다. 여기서는 Prometheus 메트릭을 바탕으로 Grafana 실행부터 데이터 소스, 패널, 변수, 템플릿 활용까지 진행합니다.
1. 네트워크와 데이터 볼륨을 준비해 Grafana 실행하기
아래 예시는 prometheus라는 컨테이너가 이미 실행 중이며 같은 네트워크의 다른 컨테이너가 9090 포트에 접근할 수 있다고 가정합니다. 새 metrics 네트워크를 만든 뒤 Grafana를 실행합니다. 같은 이름의 네트워크나 컨테이너가 있다면 기존 구성에 맞게 조정해야 합니다.
docker network create metrics
docker network connect metrics prometheus
docker volume create grafana-data
docker run -d --name grafana --network metrics \
-p 127.0.0.1:3000:3000 \
--mount source=grafana-data,target=/var/lib/grafana \
grafana/grafana:13.3.0-ubuntu
2026년 11월 5일 공식 다운로드 페이지(영문)에 명시된 13.3.0 Ubuntu 이미지를 예시로 고정했습니다. 배포할 때는 검증한 버전을 선택하고, 이미지 내용까지 고정하려면 digest를 사용할 수 있습니다. 바뀔 수 있는 latest 태그는 고정 버전이 아닙니다.
사용자 정의 네트워크에서는 컨테이너 이름을 해석할 수 있습니다. 기본 bridge에 각각 실행한 컨테이너가 prometheus라는 DNS 이름을 자동으로 얻지는 않습니다. 볼륨은 /var/lib/grafana의 Grafana 데이터베이스 등을 보존하므로 컨테이너를 재생성할 때도 재사용합니다. Prometheus 메트릭을 영속화하는 설정은 아닙니다. Grafana Docker 설치(영문) · Docker 네트워크(영문)
http://localhost:3000을 엽니다. 관리자 설정을 바꾸지 않은 새 인스턴스는 기본값이 admin/admin이며 보통 암호 변경을 요청합니다. 기존 볼륨, 미리 지정한 자격 증명, 다른 인증 방식을 사용하면 실제 설정을 따라야 합니다. 예시는 호스트 루프백 주소에만 포트를 게시하므로 원격 접속에는 별도 진입점이 필요합니다.
2. Prometheus 데이터 소스 연결하기
Connections → Data sources → Add data source → Prometheus로 이동합니다. 메뉴 이름은 버전에 따라 다를 수 있습니다.
- URL:
http://prometheus:9090은 앞의 공유 네트워크에서 해당 엔드포인트가 HTTP를 제공할 때 쓰는 주소입니다. 다른 배포에서는 Grafana 서버가 실제로 접근할 수 있는 주소를 넣습니다. Grafana 컨테이너 안의localhost는 그 컨테이너 자신이지 Docker 호스트나 사용자의 브라우저가 아닙니다. - 인증과 TLS: 인증이 없는 로컬 엔드포인트에서만 자격 증명을 비워 둘 수 있습니다. Basic Auth, 토큰 헤더, TLS가 필요하다면 요구되는 계정 정보, CA, 서버 이름 등을 설정합니다. 연결 테스트를 통과하려고 인증서 검증을 끄는 방식은 피해야 합니다.
- Save & Test: 연결을 확인한 다음 Prometheus가 필요한 메트릭을 수집하는지도 확인합니다. 데이터 소스 연결 성공이 호스트 데이터의 존재까지 뜻하지는 않습니다. 데이터 소스 설정(영문)
3. CPU와 메모리 패널 만들기
Dashboards → New → Add visualization에서 데이터 소스를 선택합니다. 다음 예시에는 Linux node_exporter, 해당 collector, 정상적인 Prometheus 스크레이프가 필요합니다. Grafana나 Prometheus만 설치한다고 생기는 범용 메트릭은 아닙니다.
Time series 패널에 CPU 사용률을 표시합니다.
100 - avg by (instance) (rate(node_cpu_seconds_total{mode="idle"}[5m])) * 100
각 코어의 유휴 시간 증가율을 구한 뒤 인스턴스별로 평균을 내고 100%에서 뺍니다. 결과는 코어마다 그린 유휴 곡선이 아니라 호스트의 평균 비유휴 비율입니다. 5m은 예시 조회 구간이며 충분한 스크레이프 샘플이 있어야 합니다. 여러 job이 같은 instance를 사용한다면 집계 전에 수집 원본을 한정해 섞이지 않게 합니다. Prometheus rate(영문) · node_exporter(영문)
- 쿼리 유형은 Range로 설정해 선택한 시간 범위의 추세를 봅니다.
- Legend에
{{instance}}를 넣어 인스턴스를 구분합니다. - Unit은 **Percent (0-100)**입니다. 쿼리 결과가 이미 이 척도의 백분율입니다.
- 'CPU 사용률 — 운영 클러스터'처럼 측정값과 범위를 제목에 적습니다. 제목 자체가 운영 데이터만 필터링하지는 않습니다.
Gauge에는 Linux 가용 메모리 비율의 보수를 사용할 수 있습니다.
(1 - node_memory_MemAvailable_bytes / node_memory_MemTotal_bytes) * 100
호스트 메모리 지표이며 특정 프로세스나 컨테이너의 사용률은 아닙니다. Instant는 선택한 시간 범위의 끝에서 인스턴스별 값을 한 번 계산합니다. 과거 범위를 보고 있다면 현재 값이 아닙니다. Range를 사용한다면 Last, Last not null 등의 축약 방식을 명시합니다. Mean은 구간 평균을 뜻합니다. 샘플 수집 시각과 누락 여부도 최신성에 영향을 줍니다.
단위는 백분율로, 필요하면 Min/Max는 0/100으로 고정합니다. 예시 임계값은 Base가 녹색, 70부터 노란색, 90부터 빨간색입니다. 각각 70 미만, 70 이상 90 미만, 90 이상이며 모든 워크로드에 통하는 장애 기준은 아닙니다. 게이지와 값 축약(영문)
4. 변수로 인스턴스 필터링하기
대시보드 편집 모드에서 변수를 추가합니다. 이전 버전의 경로는 Settings → Variables → New이며 현재 편집기에도 변수 추가 기능이 있습니다.
- Name:
instance - Type: Query, Prometheus 데이터 소스 선택
- Query type: Label values
- Label:
instance, Metric:node_cpu_seconds_total
사용이 권장되지 않는 기존 Classic query의 label_values(node_cpu_seconds_total, instance)는 Grafana 변수 편집기의 구문입니다. Prometheus에 직접 보낼 수 있는 PromQL 함수가 아닙니다. 새 변수에는 Label values 편집기를 사용합니다.
패널 쿼리에서 $instance를 참조합니다. 다음 식은 앞서 정의한 평균 CPU 사용률을 유지합니다.
100 - avg by (instance) (rate(node_cpu_seconds_total{mode="idle", instance=~"$instance"}[$__rate_interval])) * 100
Multi-value나 Include All을 활성화하면 변수가 정규식 형태로 치환되므로 정확히 일치하는 = 대신 =~를 씁니다. $__rate_interval도 요청 전에 Grafana가 치환합니다. 쿼리 간격과 설정된 스크레이프 간격으로 계산하며, 스크레이프 간격은 쿼리의 Min step이 있으면 그 값을, 없으면 데이터 소스 설정을 사용합니다. 패널의 Min interval과는 다릅니다. 설정이 실제와 다르거나 수집이 중단되면 여전히 샘플이 부족할 수 있습니다.
변수를 참조한 쿼리만 선택값에 따라 필터링됩니다. 메모리 게이지도 함께 바꾸려면 분자와 분모 양쪽 메트릭 선택자에 instance=~"$instance"를 추가합니다. 드롭다운 하나가 모든 패널을 자동으로 제한하지는 않습니다. Prometheus 변수(영문)
5. 커뮤니티 대시보드 가져오기
Grafana 대시보드 카탈로그(영문)는 가져올 수 있는 템플릿을 제공합니다. 예를 들어 Import에서 **Node Exporter Full, ID 1860(영문)**을 입력하고 revision과 데이터 소스를 선택한 뒤 패널을 확인합니다.
가져오기가 성공했다는 것은 설정을 불러왔다는 뜻이지 메트릭이 모두 있다는 뜻은 아닙니다. 선택한 revision의 node_exporter 버전, job 이름, 레이블, collector를 확인합니다. 배포 페이지에서는 일부 그래프가 사용하는 systemd, processes 활성화를 권장합니다. Grafana와 플러그인의 호환성도 표시 결과에 영향을 줄 수 있습니다. 빈 그래프는 패널 쿼리와 수집 설정부터 조사한 뒤 필요한 부분을 바꿉니다.
읽기 편하고 쿼리 부담이 적은 화면으로 정리하기
- 독자에 따라 나누기: 첫 화면에는 가용성·오류율 등 SLO 관점의 개요를 두고 상세 내용은 드릴다운 페이지에 둡니다. 200개 그래프를 한 화면에 쌓지 않습니다.
- 시간 설정 구분하기: 대시보드 범위, 새로 고침 주기, Prometheus 수집 주기,
rate의 조회 구간은 서로 다릅니다. '최근 1시간, 30초마다 새로 고침'은 예시이며 데이터 갱신 속도와 쿼리 부하를 보고 정합니다. - 배포 시점 표시하기: Annotation을 겹치면 지표 변화와 배포의 시간 관계를 확인할 수 있습니다. 시간상 상관관계만으로 원인이 입증되지는 않습니다.
- 읽을 양과 로딩 비용으로 나누기: 그래프 6~8개라는 보편적인 한도는 없습니다. 읽어야 할 정보와 쿼리 처리량을 기준으로 분리합니다.
자주 묻는 질문
대시보드 쿼리가 Prometheus에 부하를 주나요? 그렇습니다. 잦은 새로 고침, 긴 시간 범위, 높은 카디널리티, 복잡한 표현식은 부하를 늘립니다. 모든 운영 환경에 '최소 30초 간격'이라는 규칙이 있는 것은 아닙니다. 반복되는 비싼 표현식은 recording rules로 미리 계산할 수 있지만, Prometheus가 고정 PromQL을 주기적으로 평가하므로 Grafana의 $instance나 $__rate_interval을 직접 사용할 수 없습니다. 계산·저장 비용도 추가되므로 모든 장기 조회에 필요한 것은 아닙니다. Recording rules(영문)
Grafana와 Kibana는 어떻게 다른가요? Grafana는 데이터 소스를 통해 메트릭, 로그, 트레이스 등을 표시합니다. Kibana는 Elasticsearch를 중심으로 문서 검색, 메트릭과 시계열 분석 등을 제공합니다. 하나는 메트릭, 하나는 로그라고만 구분하기에는 범위가 넓습니다. Guance의 대시보드(영문)에서도 수집한 데이터의 시각화를 구성해 추세와 조사 진입점을 함께 둘 수 있습니다. 데이터 수집, 쿼리, 관련 필드는 설정해야 하며 대시보드를 추가한다고 데이터가 생기지는 않습니다. Grafana 개요(영문) · Kibana 분석(영문)
설정을 버전 관리하려면 어떻게 하나요? JSON 내보내기·가져오기 또는 파일 provisioning을 사용합니다. 후자는 대시보드 JSON과 함께 /etc/grafana/provisioning/dashboards의 provider YAML이 필요합니다. type: file을 지정하고 options.path를 Grafana 서버나 컨테이너가 실제로 읽을 수 있는 JSON 디렉터리로 설정합니다. 마운트, 권한, 데이터 소스 UID도 확인합니다. 폴더를 마운트하는 것만으로 provider가 생기지는 않습니다. Git에 저장한 뒤 통제된 동기화·배포 과정이 있어야 GitOps 흐름이 됩니다. 파일이 UI 변경을 덮어쓸 수 있으므로 어느 쪽을 기준으로 삼을지도 정합니다. Grafana provisioning(영문)
