Grafana 옵저버빌리티
다음은 프로덕션 수준의 자체 호스팅 스택(대시보드 약 60개, 알림 규칙 400개 이상, 스크레이프 작업 50개, 로그 및 트레이스)에서 얻은 실천 사항입니다. 아래 각 규칙은 이를 위반했을 때 실제 장애가 발생했기 때문에 존재합니다. 왜 그런지 설명되어 있으므로, 경계 사례를 판단할 수 있습니다.
먼저 모드를 선택하세요
- 학습 ("가르쳐 줘", "설명해 줘", "무엇인가요?", "퀴즈 내 줘"): references/learning-path.md를 따르세요. 한 단계씩 가르치고 assets/lab/에 있는 실습 환경을 실행하세요. 다음 단계로 넘어가기 전에 이해도를 확인하세요. 모든 단계를 한 번에 보여주지 마세요.
- 구축 (대시보드, 알림, 파이프라인, Terraform 또는 롤아웃): 아래 워크플로우를 따르고 작업에 필요한 참조 파일만 열세요.
- 조직 내 롤아웃 계획: references/implementation-plan.md.
한눈에 보는 스택
앱 / 호스트 / 네트워크 키트 / 클라우드 API
│ 메트릭 (익스포터, /metrics) │ 로그 (파일, 도커, syslog) │ 트레이스 (OTLP)
▼ ▼ ▼
Prometheus ◄── 스크레이프 ── Grafana Alloy (수집기: 검색, 재레이블, 수정, 전달)
│ │ │
│ Loki Tempo
└──────────────┬────────────────────┴────────────────────────────────┘
▼
Grafana ── 대시보드, Explore, 알림 ──► 연락 지점 (채팅, 이메일, 온콜)
▲
Terraform (폴더, 데이터 소스, 규칙, 라우팅) + 스크립트 (대시보드) + git
세부 정보: references/architecture.md.
중요한 규칙
- 코드가 진실의 원천입니다. Terraform을 통해 알림을 변경하고, 대시보드는 Git에 있는 생성기 스크립트 또는 JSON으로 구축하세요. UI에서 클릭한 내용은 다음 apply 시 손실되거나, 더 나쁘게는 다음 apply가 자동으로 되돌릴 수 있습니다.
- apply 전에 항상 두 가지 드리프트를 확인하세요. (a) 라이브에는 있지만 코드에는 없는 규칙: 대상이 지정되지 않은 apply는 이를 삭제합니다. (b) 코드에는 있지만 라이브에서 변경된 규칙: apply는 이를 되돌립니다. "변경 사항 없음" 계획은 Terraform이 한 번도 본 적 없는 규칙에 대해 아무것도 증명하지 않습니다. references/as-code.md를 참조하세요.
- 저장된 계획을 보호하세요.
terraform plan -out을 실행한 후, 의도하지 않은 모든 리소스의delete/replace를 거부하세요. 폴더에prevent_destroy를 설정하세요. Grafana 폴더를 삭제하면 해당 폴더의 모든 대시보드와 규칙이 삭제됩니다. - 서비스 계정 토큰을 사용하고,
admin:password는 절대 사용하지 마세요. 상태가 토큰 인증으로 생성된 경우, 기본 인증 apply는 폴더, 연락 지점 및 정책 트리의 삭제 및 재생성을 계획합니다. 이로 인해 한 번의 apply로 59개의 대시보드와 전체 라우팅 트리가 한 번에 삭제된 적이 있습니다. - 규칙에 절대
notification_settings(연락 지점)를 넣지 마세요. 이 속성이 있는 규칙은 정책 트리를 완전히 건너뜁니다. 심각도 라우팅, 반복 간격 및 음소거 타이밍에서 벗어납니다. 한 환경에서는 217개 규칙 중 196개가 이렇게 설정되어 있었고 아무도 알아채지 못했습니다. - 임계값은 PromQL 내부가 아니라 Grafana의 threshold 단계에 넣으세요.
expr > 90을 사용하면 정상 호스트는 시리즈를 반환하지 않으며, Grafana는 이를 OK가 아닌 NoData로 읽습니다. 원시 값을 쿼리하고, 단계 C에서 비교하세요. - 실행 가능성에 따라 라우팅하고, 반복 간격을 실제 레버로 취급하세요.
severity(critical/warning/info)와 만성적인 알려진 문제에는urgency=backlog를 사용하세요. 대부분의 알림 소음은 이미 알려진 문제의 재알림입니다. 중요 알림은 매일, 경고는 매주 반복하고, 매시간 반복하지 마세요. - 에스컬레이션은 지연이어야 하며, 무음이 확인이어야 합니다. 페이지 라우트는
group_wait를 약 15분으로 설정하므로, 알림이 여전히 발생 중이고 무음 해제되지 않은 경우에만 페이지를 보냅니다. 이벤트 스타일 규칙은keep_firing_for를 대기 시간 이상으로 설정해야 합니다. 그렇지 않으면 에스컬레이션되기 전에 해결됩니다. - 모니터링을 모니터링하세요. 평가 실패, 알림 전송 실패, 억제된(무음) 알림, 오래된 익스포터 및 중단된 백업을 감시하세요. 무음 알림 시스템은 정상 시스템과 똑같이 보입니다. references/meta-monitoring.md를 참조하세요.
- 검증하고, 신뢰하지 마세요. 모든 패널 또는 알림 쿼리를 데이터 소스에 대해 먼저 실행하세요. API 쓰기 후에는 객체를 다시 읽어 변경 사항이 적용되었는지 확인하세요. POST 응답은 어떤 콘텐츠가 올라갔는지 알려주지 않습니다. 두 사람 또는 두 세션 간의 일치는 검증이 아닙니다. 하나의 명령어가 검증입니다.
모든 변경에 대한 워크플로우
- 패널이나 알림이 답하는 질문과 이를 처리할 사람을 명시하세요. 아무도 알림에 대해 조치를 취하지 않는다면, 이는 알림이 아니라 대시보드 패널입니다.
- Explore 또는 데이터 소스 프록시 API를 통해 쿼리를 검증하세요. 데이터가 반환되는지, 그룹화하거나 라우팅할 레이블이 무엇인지, 정상 상태일 때 어떻게 동작하는지(비어 있음? 0?) 확인하세요.
- 코드로 작성하세요: Terraform 규칙 그룹, 대시보드 생성기 또는 Alloy 구성입니다. references/alerting.md 또는 references/dashboards.md를 따르세요.
- 드리프트를 확인한 후,
terraform plan -out=tfplan을 실행하세요. 특히grafana_notification_policy의 모든 접힌~블록을 읽으세요. 모든 알림이 어디로 가는지 결정하기 때문입니다. - 저장된 계획을 서비스 계정 토큰으로 적용하세요. 확실하지 않은 경우
-target을 사용하세요. - API에서 다시 읽어 규칙이 평가되는지(상태가 Error/NoData가 아님) 확인하고, 알림의 경우 실제 연락 지점까지 종단 간 테스트를 실행하세요.
- 왜를 커밋 메시지에 포함하여 커밋하세요. 선택이 잘못 보이지만 의도적일 경우 코드에 주석을 남기세요.
완료 조건
알림 규칙: Terraform에 정의됨; severity 레이블 설정됨; 요약 및 설명 템플릿에 영향을 받은 호스트 또는 서비스와 현재 값 포함; no_data_state가 의도적으로 선택됨; for가 플래핑을 방지할 만큼 충분히 김; 트리에 의해 라우팅됨(규칙별 연락 지점 없음); 설명에 runbook 링크 또는 첫 번째 단계 포함; 종단 간 테스트 완료; 기존 규칙과 중복 페이지를 보내지 않음.
대시보드: Git에 있음(생성되거나 id/version이 제거된 상태로 내보내짐); 올바른 폴더에 있음; 개요 허브에서 링크되고 다시 돌아올 수 있음; env/host에 대한 변수 포함; 모든 패널에 질문을 하거나 답하는 제목이 있음; 단위 및 임계값 설정됨; 링크에 keepTime 설정됨.
새 익스포터 또는 데이터 소스: 안정적인 레이블(env, team, service, role)로 스크레이프됨; 플릿 up == 0 규칙에 포함됨(별도 규칙을 추가하지 마세요); 마지막 실행 또는 신선도 메트릭이 있으면, 부실 규칙 추가; 메타 모니터링 감사에 추가됨; 데이터 소스에 고정 uid가 있음.
참조 색인
| 파일 | 열 때 |
|---|---|
| learning-path.md | 가르치거나 배울 때, 단계별 실습 포함 |
| architecture.md | 구성 요소, 레이블, 보존, 인증, HA 선택 시 |
| queries.md | PromQL 또는 LogQL 작성 시, 또는 쿼리가 잘못된 것 같을 때 |
| dashboards.md | 대시보드 구축 또는 검토 시 |
| alerting.md | 규칙, 라우팅, 연락 지점, 무음, 피로 관리 시 |
| as-code.md | Terraform, API, 백업, 드리프트, 복원 시 |
| meta-monitoring.md | 모니터링 자체가 작동하는지 확인할 때 |
| implementation-plan.md | 팀이나 회사에 Grafana 도입 시 |
자산: assets/lab/는 로컬 Docker Compose 실습 환경입니다. assets/terraform-starter/는 안전한 기본값이 이미 설정된 시작용 Terraform 스택입니다.