Grafana

학습 목표

Grafana가 Prometheus 등 데이터 소스를 시각화·알람하는 역할임을 설명할 수 있다.

대시보드 패널·변수·시간 범위로 RED 지표를 구성할 수 있다.

Grafana unified alerting의 contact point·alert rule 개념을 설명할 수 있다.

SLO 패널(에러율·burn rate)을 PromQL과 연결해 설명할 수 있다.

문제 상황

• PromQL은 되는데 그래프를 매번 Explore에서만 본다
  • 팀 대시보드가 없어 온콜마다 쿼리를 다시 짠다
• 알람이 Prometheus rule·스크립트·채팅봇에 흩어져 있다
  • 한 UI에서 rule·라우팅·silence가 필요하다
• staging과 prod를 패널 복사로 나눴더니 수정이 2배다
  • 변수 $env 하나로 필터링하고 싶다
• SLA 99.9%인데 지금 얼마나 태웠는지 한 패널로 안 보인다
  • error rate + burn rate 뷰가 필요하다

Prometheus에서 scrape·PromQL을 봤다. Grafana는 그 결과를 보여주고 깨우는 계층이다.

1. Grafana란

Grafana — 여러 데이터 소스를 붙여 대시보드·Explore·알람을 제공하는 OSS UI.

기능	설명
Dashboard	패널 모음 — RED, 인프라, SLO 보드
Explore	ad-hoc PromQL·LogQL — 장애 조사
Alerting	rule → contact point (Slack, PagerDuty 등)
Provisioning	YAML/JSON으로 datasource·dashboard 코드화

데이터 소스	신호
Prometheus	메트릭 (앞서 Prometheus)
Loki	로그 (앞서 로그 수집 파이프라인)
Tempo/Jaeger	트레이스 (이후 편)

• Prometheus Alertmanager와 Grafana alerting은 역할이 겹칠 수 있다 — 팀에서 하나를 primary로 정한다
• Loki·로그는 같은 Grafana에서 메트릭·로그 한 화면 (앞서 ELK vs Loki)

2. Prometheus 데이터 소스

Grafana는 Prometheus HTTP API (/api/v1/query, query_range)로 PromQL을 실행한다.

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

설정	의미
access: proxy	브라우저 → Grafana → Prometheus (CORS·인증 중앙)
timeInterval	scrape 간격 힌트 — 그래프 step
isDefault	새 패널 기본 소스

• url은 Grafana 컨테이너 기준 네트워크 (K8s Service 이름 등)
• 전체 provisioning 예시는 code/grafana-provisioning.yaml 참고

3. 대시보드와 패널

개념	설명
Dashboard	JSON/YAML로 export·Git 관리
Row	패널 그룹 (Overview, RED, …)
Panel	단일 시각화 — Time series, Stat, Gauge, Table
Variable	$job, $env — 쿼리·패널에서 {job="$job"}
Time range	Last 1h, Last 24h — 우측 상단

RED 패널 예시 (PromQL)

R — Request rate (Stat / Time series)

sum(rate(http_requests_total{job="$job", env="$env"}[5m]))

E — Error rate (Gauge, 0~1)

sum(rate(http_requests_total{job="$job", env="$env", status=~"5.."}[5m]))
/
sum(rate(http_requests_total{job="$job", env="$env"}[5m]))

D — p99 latency (Time series)

histogram_quantile(
  0.99,
  sum(rate(http_request_duration_seconds_bucket{job="$job", env="$env"}[5m])) by (le)
)

패널 타입	RED에 쓰는 경우
Time series	RPS·latency 추세
Stat	현재 RPS 한 숫자
Gauge	error rate %, CPU
Table	top-N slow endpoints

변수

{
  "name": "job",
  "type": "query",
  "datasource": "Prometheus",
  "query": "label_values(http_requests_total, job)"
}

• query 변수 — Prometheus에서 라벨 값 목록
• custom — staging,prod 고정
• 변수 변경 시 같은 대시보드 전 패널이 필터 갱신

4. Grafana 알람

Unified Alerting — Grafana 8+ 기본. rule → contact point → Slack 등.

# provisioning/alerting/rule-api-error.yaml (개념)
groups:
  - name: api-red
    interval: 1m
    rules:
      - uid: api-high-error-rate
        title: API error rate above 5%
        condition: C
        data:
          - refId: A
            datasourceUid: prometheus
            model:
              expr: |
                sum(rate(http_requests_total{job="api",status=~"5.."}[5m]))
                /
                sum(rate(http_requests_total{job="api"}[5m]))
          - refId: C
            model:
              type: threshold
              conditions:
                - evaluator:
                    params: [0.05]
                    type: gt
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "API 5xx rate > 5% for 5m"

필드	의미
for	조건이 연속 N분 유지될 때 fire — flapping 방지
condition	multi-query ref (A → B → threshold)
contact point	Slack webhook, email — 별도 provisioning

• recording rule (Prometheus)로 $job:error_rate5m을 미리 계산하면 alert expr 단순화 (앞서 Prometheus)
• Alertmanager만 쓸 팀은 Grafana alert 대신 Prometheus rule + AM route

5. SLO 패널

SLO·SLI·에러 버짓은 이후 편에서 본다. Grafana에서는 같은 PromQL로 선행 패널을 만든다.

패널	PromQL / 의미
Availability (30d)	1 - (5xx count / total) rolling window
Error budget remaining	(1 - actual_error_rate) / (1 - SLO_target)
Burn rate (1h)	short window error rate vs budget — 빠른 소진 감지

# 1h burn rate (개념) — 5xx 비율 / 허용 error budget
(
  sum(rate(http_requests_total{job="api", status=~"5.."}[1h]))
  /
  sum(rate(http_requests_total{job="api"}[1h]))
)
/
(1 - 0.999)

• SLO target 0.999 → 허용 error budget 0.1%
• burn rate > 1 — budget보다 빠르게 태우는 중
• multi-window multi-burn-rate alert는 Google SRE Alerting on SLO 패턴

Grafana 표현	운영
Stat + threshold green/yellow/red	한눈에 budget
Time series overlay	배포·장애 구간 비교
Annotation	deploy marker (Platform CI/CD)

6. 실무 체크리스트

항목	권장
대시보드	RED 한 페이지 + drill-down
변수	env, job, namespace — 패널 복제 금지
Git	dashboard JSON provisioning 또는 export in repo
알람	for 5m+, severity label, runbook URL in annotation
권한	Viewer / Editor / Admin — prod datasource read-only
성능	heavy query는 recording rule로 pre-aggregate

# health
curl -s http://grafana:3000/api/health

# test datasource (admin API token)
curl -H "Authorization: Bearer $GRAFANA_TOKEN" \
  http://grafana:3000/api/datasources/proxy/1/api/v1/query?query=up

7. 정리

• Grafana는 Prometheus PromQL 결과를 대시보드·Explore·알람으로 운영 UI화한다
• 변수로 multi-env, 패널 타입으로 RED를 한 화면에
• Unified alerting — rule, for, contact point; AM과 역할 분담 정하기
• SLO 패널 — error rate, budget, burn rate를 PromQL로 표현 (SLI 정의는 이후 편)
• 코드로 provision하면 리뷰·재현 가능

다음에 다룰 것

• 메트릭 설계 안티패턴
• cardinality 폭발, 라벨 설계

---

해당 내용은 Observability Engineering (Charity Majors, Liz Fong-Jones, George Miranda) 및 Grafana Documentation (grafana.com/docs) 의 내용을 기반으로 합니다.