Grafana 완전 가이드

1. Grafana란?

Grafana는 다양한 데이터소스의 시계열/로그/트레이스 데이터를 하나의 대시보드에서 시각화하는 오픈소스 플랫폼입니다. Prometheus, Loki, InfluxDB, MySQL, CloudWatch 등 수십 가지 데이터소스를 지원하며, 관찰 가능성(Observability) 스택의 "화면" 역할을 담당합니다.

2. 설치 (Docker Compose)

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:yaml

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

3. 데이터소스 연결

UI에서 Connections → Data sources → Add data source로 직접 등록하거나, Provisioning으로 코드화할 수 있습니다.

# provisioning/datasources/datasources.yaml
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}"yaml

4. 대시보드 & 패널

대시보드는 여러 Panel의 격자 레이아웃입니다. 대표적인 패널 타입은 다음과 같습니다.

# 패널 JSON 예시 (Panel → Edit → JSON Model 탭에서 확인 가능)
{
  "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 }
}json

5. 변수(Variables) & 템플릿

Variable을 사용하면 하나의 대시보드로 여러 서버·서비스·네임스페이스를 드롭다운으로 전환하며 재사용할 수 있습니다.

# Dashboard Settings → Variables → Add variable
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"promql

6. Alerting

Grafana 9+ 의 Unified Alerting은 Prometheus의 AlertManager와 별개로, Grafana 자체에서 알림 규칙과 발송 채널을 관리합니다.

# Alert Rule (UI: Alerting → Alert rules → New alert rule)
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, clusteryaml

7. Provisioning (Dashboards as Code)

대시보드와 데이터소스를 UI가 아닌 파일로 관리하면 Git으로 버전 관리하고 여러 환경에 동일하게 배포할 수 있습니다.

# provisioning/dashboards/dashboards.yaml
apiVersion: 1
providers:
  - name: default
    folder: "App Dashboards"
    type: file
    updateIntervalSeconds: 30
    options:
      path: /etc/grafana/provisioning/dashboards/json
      foldersFromFilesStructure: true

# 디렉터리 구조
provisioning/
├── datasources/datasources.yaml
└── dashboards/
    ├── dashboards.yaml
    └── json/
        └── api-overview.json   # 대시보드 export한 JSON 그대로 배치yaml

# API로 대시보드 export / import (스크립트 자동화)
curl -s -H "Authorization: Bearer $GRAFANA_API_KEY" \
  http://localhost:3000/api/dashboards/uid/ | jq '.dashboard' > api-overview.json

curl -X POST -H "Authorization: Bearer $GRAFANA_API_KEY" -H "Content-Type: application/json" \
  -d @payload.json http://localhost:3000/api/dashboards/dbbash

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

# 플러그인 설치 (예: Pie Chart, CloudWatch)
grafana-cli plugins install grafana-piechart-panel
# Docker 환경에서는 환경변수로 설치
GF_INSTALL_PLUGINS=grafana-piechart-panel,grafana-clock-panel

# API Key / Service Account 발급 (자동화·Provisioning용)
grafana-cli admin reset-admin-password newpasswordbash

9. 다음 단계