Grafana 가이드 | AI DevOps Korea

목차 10개 섹션

가이드 사용법
구조 다이어그램
Grafana란?
설치 (Docker Compose)
데이터소스 연결
대시보드 & 패널
변수(Variables) & 템플릿
Unified Alerting
플러그인 & 사용자/조직 관리
다음 단계

가이드 사용법

읽는 방향

Grafana를 실무 흐름으로 이해하기

Grafana로 메트릭·로그·트레이스를 하나의 대시보드에서 시각화하세요. 데이터소스 연결, 패널 제작, 변수, Unified Alerting, Provisioning(Dashboards as Code)까지 실무 예제로 학습합니다. 이 가이드는 개념을 나열하기보다, 실제 프로젝트에서 판단해야 하는 순서대로 내용을 따라갈 수 있게 구성했습니다.

핵심 관점

인프라 / 운영

설치 명령을 외우기보다 트래픽, 런타임, 관측, 장애 대응이 어떤 순서로 이어지는지 파악합니다.

대시보드 & 패널 제작데이터소스 Provisioning변수 기반 대시보드 템플릿Unified Alerting사용자/조직 권한 관리

구조 다이어그램

글로 읽은 내용을 머릿속에 오래 남기려면 먼저 흐름을 그림으로 잡는 편이 좋습니다. 아래 두 그림은 Grafana를 학습할 때 계속 되돌아볼 수 있는 기준 지도입니다.

학습 흐름

다이어그램 렌더링 중…

아키텍처 관점

다이어그램 렌더링 중…

Grafana란?

Grafana를 처음 펼칠 때는 세부 명령보다 큰 그림이 먼저입니다. 이 섹션에서는 앞으로 배울 개념들이 어떤 문제를 풀기 위해 등장했는지부터 잡아봅니다.

Grafana는 데이터를 저장하지 않는 순수 시각화 계층입니다. Prometheus(메트릭), Loki(로그), Tempo(트레이스), MySQL 등 수십 가지 데이터소스에 실시간으로 쿼리를 날려 하나의 대시보드에서 보여주는 역할만 담당하므로, 데이터 저장·수집 책임은 항상 백엔드 데이터소스 쪽에 있다는 전제를 먼저 이해해야 합니다.

구성 요소	역할
Dashboard	여러 Panel을 격자로 배치한 시각화 화면. JSON으로 정의되어 버전 관리 가능
Panel	단일 그래프/표/게이지 등 시각화 단위
Data Source	Grafana가 쿼리를 실행할 외부 시스템 연결 (Prometheus, Loki, MySQL 등)
Alert Rule	쿼리 결과 기반 임계치 감시 및 알림 발송 (Unified Alerting)
Organization / Team	대시보드·데이터소스·권한을 그룹 단위로 격리

설치 (Docker Compose)

여기서는 설치 (Docker Compose)을 실제 코드와 함께 확인합니다. 예제를 그대로 따라 하기보다, 입력과 출력, 그리고 바뀌기 쉬운 부분이 어디인지 보면서 읽어보세요.

Grafana 단독으로도 실행되지만, provisioning 볼륨을 함께 마운트해두면 컨테이너가 재생성되어도 데이터소스와 대시보드가 자동으로 복원됩니다. 최초 로그인 비밀번호는 반드시 변경하도록 강제하는 것이 안전합니다.

docker-compose.ymlYAML

services:
  grafana:
    image: grafana/grafana-oss:11.0.0
    ports: ["3000:3000"]
    environment:
      - GF_SECURITY_ADMIN_USER=admin
      - GF_SECURITY_ADMIN_PASSWORD=admin
      - GF_USERS_ALLOW_SIGN_UP=false
    volumes:
      - grafana-data:/var/lib/grafana
      - ./provisioning:/etc/grafana/provisioning   # 데이터소스·대시보드 자동 등록

volumes:
  grafana-data:

BASH

docker compose up -d
# http://localhost:3000 접속 (초기 admin/admin, 최초 로그인 시 비밀번호 변경 요구)

데이터소스 연결

여기서는 데이터소스 연결을 실제 코드와 함께 확인합니다. 예제를 그대로 따라 하기보다, 입력과 출력, 그리고 바뀌기 쉬운 부분이 어디인지 보면서 읽어보세요.

UI에서 Connections → Data sources → Add data source로 직접 등록할 수도 있지만, Provisioning으로 YAML에 선언해두면 여러 환경에 동일한 구성을 반복 배포할 수 있고 Git으로 변경 이력을 추적할 수 있습니다.

provisioning/datasources/datasources.ymlYAML

apiVersion: 1
datasources:
  - name: Prometheus
    type: prometheus
    access: proxy
    url: http://prometheus:9090
    isDefault: true
    jsonData:
      timeInterval: 15s

  - name: Loki
    type: loki
    access: proxy
    url: http://loki:3100

  - name: MySQL
    type: mysql
    url: mysql:3306
    database: appdb
    user: readonly
    secureJsonData:
      password: "${MYSQL_PASSWORD}"

대시보드 & 패널

여기서는 대시보드 & 패널을 실제 코드와 함께 확인합니다. 예제를 그대로 따라 하기보다, 입력과 출력, 그리고 바뀌기 쉬운 부분이 어디인지 보면서 읽어보세요.

대시보드는 여러 Panel의 격자 레이아웃입니다. 패널 타입 선택이 데이터의 의미를 얼마나 잘 전달하는지를 좌우하므로, 추세를 보여줄지 현재 값을 강조할지 먼저 정하고 타입을 고르는 것이 좋습니다.

패널 JSON (Panel → Edit → JSON Model)JSON

{
  "type": "timeseries",
  "title": "요청 수 (분당)",
  "targets": [
    { "expr": "sum(rate(http_requests_total[1m])) by (status)", "legendFormat": "{{status}}" }
  ],
  "fieldConfig": {
    "defaults": { "unit": "reqps", "custom": { "drawStyle": "line", "fillOpacity": 15 } }
  },
  "gridPos": { "h": 8, "w": 12, "x": 0, "y": 0 }
}

패널 타입	용도
Time series	시간축 그래프 — CPU, 요청 수 등 추세 확인
Stat	단일 값 강조 표시 (현재 접속자 수 등)
Gauge / Bar gauge	임계치 대비 현재 값 (디스크 사용률 등)
Table	로그·집계 결과를 표 형태로
Heatmap	응답 시간 분포처럼 값의 밀도 시각화

변수(Variables) & 템플릿

여기서는 변수(Variables) & 템플릿을 실제 코드와 함께 확인합니다. 예제를 그대로 따라 하기보다, 입력과 출력, 그리고 바뀌기 쉬운 부분이 어디인지 보면서 읽어보세요.

Variable을 사용하면 하나의 대시보드로 여러 서버·서비스·네임스페이스를 드롭다운으로 전환하며 재사용할 수 있습니다. 변수를 도입하기 전에는 동일한 대시보드를 서버 수만큼 복제해야 했다는 점을 생각하면, 유지보수 비용을 크게 줄여주는 핵심 기능입니다.

Dashboard Settings → VariablesTEXT

Name: instance
Type: Query
Data source: Prometheus
Query: label_values(up, instance)
Multi-value: true
Include All option: true

# 패널 쿼리에서 변수 사용
sum(rate(http_requests_total{instance=~"$instance"}[5m]))

# 변수를 대시보드 제목에도 활용 가능
title: "요청 현황 — $instance"

Unified Alerting

여기서는 Unified Alerting을 실제 코드와 함께 확인합니다. 예제를 그대로 따라 하기보다, 입력과 출력, 그리고 바뀌기 쉬운 부분이 어디인지 보면서 읽어보세요.

Grafana 9+ 의 Unified Alerting은 Prometheus AlertManager와 별개로, Grafana 자체에서 알림 규칙과 발송 채널을 관리합니다. Contact point(발송 채널)와 Notification policy(라벨 기반 라우팅)를 분리해두면, 알림 내용 변경과 수신자 변경을 서로 독립적으로 관리할 수 있습니다.

Alert rule (Alerting → Alert rules → New)YAML

Query: sum(rate(http_requests_total{status=~"5.."}[5m])) / sum(rate(http_requests_total[5m]))
Condition: WHEN last() OF query IS ABOVE 0.05
Evaluate every: 1m   For: 5m   # 5분간 지속되면 Firing

# Contact point — Slack
Type: Slack
Webhook URL: https://hooks.slack.com/services/xxx/yyy/zzz

# Notification policy — 라벨 매칭으로 라우팅
Matching labels: severity=critical
Contact point: slack-oncall
Group by: alertname, cluster

플러그인 & 사용자/조직 관리

여기서는 플러그인 & 사용자/조직 관리을 실제 코드와 함께 확인합니다. 예제를 그대로 따라 하기보다, 입력과 출력, 그리고 바뀌기 쉬운 부분이 어디인지 보면서 읽어보세요.

조직(Organization)은 대시보드·데이터소스가 완전히 격리되는 최상위 단위이고, 팀(Team)은 조직 내부에서 폴더·대시보드 권한을 그룹 단위로 나눠 부여하는 단위입니다. 서비스가 늘어날수록 폴더 권한을 팀 단위로 설계해두는 편이 나중에 권한 이슈를 훨씬 줄여줍니다.

플러그인 설치BASH

# 플러그인 설치 (예: Pie Chart)
grafana-cli plugins install grafana-piechart-panel

# Docker 환경에서는 환경변수로 설치
GF_INSTALL_PLUGINS=grafana-piechart-panel,grafana-clock-panel

권한 범위	설명
Organization	대시보드·데이터소스가 속한 최상위 격리 단위
Team	조직 내 사용자 그룹. 폴더/대시보드 권한을 팀 단위로 부여
Role (Viewer/Editor/Admin)	사용자별 기본 권한 등급
Folder permissions	폴더 단위로 팀/사용자별 조회·편집 권한 세분화

다음 단계

이 섹션은 다음 단계을 실무 관점에서 정리합니다. 개념을 외우기보다, 어떤 상황에서 이 기준을 꺼내 쓸지에 초점을 맞춰보세요.

🚀

Grafana 심화 로드맵

• Grafana Loki: 로그 수집·검색 — Prometheus와 동일한 라벨 모델
• Grafana Tempo: 분산 트레이싱, Jaeger/Zipkin 호환
• Grafana Cloud: 관리형 Prometheus + Loki + Tempo + Grafana 통합 SaaS
• Terraform Provider: 대시보드/데이터소스/알림 규칙을 IaC로 관리

연계 가이드: Prometheus 가이드 · Kubernetes 가이드 · Docker 가이드

목차 10개 섹션

가이드 사용법
구조 다이어그램
Grafana란?
설치 (Docker Compose)
데이터소스 연결
대시보드 & 패널
변수(Variables) & 템플릿
Unified Alerting
플러그인 & 사용자/조직 관리
다음 단계

가이드 사용법

읽는 방향

Grafana를 실무 흐름으로 이해하기

핵심 관점

인프라 / 운영

설치 명령을 외우기보다 트래픽, 런타임, 관측, 장애 대응이 어떤 순서로 이어지는지 파악합니다.

대시보드 & 패널 제작데이터소스 Provisioning변수 기반 대시보드 템플릿Unified Alerting사용자/조직 권한 관리

구조 다이어그램

학습 흐름

다이어그램 렌더링 중…

아키텍처 관점

다이어그램 렌더링 중…

Grafana란?

구성 요소	역할
Dashboard	여러 Panel을 격자로 배치한 시각화 화면. JSON으로 정의되어 버전 관리 가능
Panel	단일 그래프/표/게이지 등 시각화 단위
Data Source	Grafana가 쿼리를 실행할 외부 시스템 연결 (Prometheus, Loki, MySQL 등)
Alert Rule	쿼리 결과 기반 임계치 감시 및 알림 발송 (Unified Alerting)
Organization / Team	대시보드·데이터소스·권한을 그룹 단위로 격리

설치 (Docker Compose)

docker-compose.ymlYAML

services:
  grafana:
    image: grafana/grafana-oss:11.0.0
    ports: ["3000:3000"]
    environment:
      - GF_SECURITY_ADMIN_USER=admin
      - GF_SECURITY_ADMIN_PASSWORD=admin
      - GF_USERS_ALLOW_SIGN_UP=false
    volumes:
      - grafana-data:/var/lib/grafana
      - ./provisioning:/etc/grafana/provisioning   # 데이터소스·대시보드 자동 등록

volumes:
  grafana-data:

BASH

docker compose up -d
# http://localhost:3000 접속 (초기 admin/admin, 최초 로그인 시 비밀번호 변경 요구)

데이터소스 연결

provisioning/datasources/datasources.ymlYAML

apiVersion: 1
datasources:
  - name: Prometheus
    type: prometheus
    access: proxy
    url: http://prometheus:9090
    isDefault: true
    jsonData:
      timeInterval: 15s

  - name: Loki
    type: loki
    access: proxy
    url: http://loki:3100

  - name: MySQL
    type: mysql
    url: mysql:3306
    database: appdb
    user: readonly
    secureJsonData:
      password: "${MYSQL_PASSWORD}"

대시보드 & 패널

패널 JSON (Panel → Edit → JSON Model)JSON

{
  "type": "timeseries",
  "title": "요청 수 (분당)",
  "targets": [
    { "expr": "sum(rate(http_requests_total[1m])) by (status)", "legendFormat": "{{status}}" }
  ],
  "fieldConfig": {
    "defaults": { "unit": "reqps", "custom": { "drawStyle": "line", "fillOpacity": 15 } }
  },
  "gridPos": { "h": 8, "w": 12, "x": 0, "y": 0 }
}

패널 타입	용도
Time series	시간축 그래프 — CPU, 요청 수 등 추세 확인
Stat	단일 값 강조 표시 (현재 접속자 수 등)
Gauge / Bar gauge	임계치 대비 현재 값 (디스크 사용률 등)
Table	로그·집계 결과를 표 형태로
Heatmap	응답 시간 분포처럼 값의 밀도 시각화

변수(Variables) & 템플릿

Dashboard Settings → VariablesTEXT

Name: instance
Type: Query
Data source: Prometheus
Query: label_values(up, instance)
Multi-value: true
Include All option: true

# 패널 쿼리에서 변수 사용
sum(rate(http_requests_total{instance=~"$instance"}[5m]))

# 변수를 대시보드 제목에도 활용 가능
title: "요청 현황 — $instance"

Unified Alerting

Alert rule (Alerting → Alert rules → New)YAML

Query: sum(rate(http_requests_total{status=~"5.."}[5m])) / sum(rate(http_requests_total[5m]))
Condition: WHEN last() OF query IS ABOVE 0.05
Evaluate every: 1m   For: 5m   # 5분간 지속되면 Firing

# Contact point — Slack
Type: Slack
Webhook URL: https://hooks.slack.com/services/xxx/yyy/zzz

# Notification policy — 라벨 매칭으로 라우팅
Matching labels: severity=critical
Contact point: slack-oncall
Group by: alertname, cluster

플러그인 & 사용자/조직 관리

플러그인 설치BASH

# 플러그인 설치 (예: Pie Chart)
grafana-cli plugins install grafana-piechart-panel

# Docker 환경에서는 환경변수로 설치
GF_INSTALL_PLUGINS=grafana-piechart-panel,grafana-clock-panel

권한 범위	설명
Organization	대시보드·데이터소스가 속한 최상위 격리 단위
Team	조직 내 사용자 그룹. 폴더/대시보드 권한을 팀 단위로 부여
Role (Viewer/Editor/Admin)	사용자별 기본 권한 등급
Folder permissions	폴더 단위로 팀/사용자별 조회·편집 권한 세분화

다음 단계

이 섹션은 다음 단계을 실무 관점에서 정리합니다. 개념을 외우기보다, 어떤 상황에서 이 기준을 꺼내 쓸지에 초점을 맞춰보세요.

🚀

📈 Grafana 완전 가이드

가이드 사용법

Grafana를 실무 흐름으로 이해하기

인프라 / 운영

구조 다이어그램

학습 흐름

아키텍처 관점

Grafana란?

설치 (Docker Compose)

데이터소스 연결

대시보드 & 패널

변수(Variables) & 템플릿

Unified Alerting

플러그인 & 사용자/조직 관리

다음 단계

📈 Grafana 완전 가이드

가이드 사용법

Grafana를 실무 흐름으로 이해하기

인프라 / 운영

구조 다이어그램

학습 흐름

아키텍처 관점

Grafana란?

설치 (Docker Compose)

데이터소스 연결

대시보드 & 패널

변수(Variables) & 템플릿

Unified Alerting

플러그인 & 사용자/조직 관리

다음 단계