Community생산성 & 협업github.com

grafana-observability

코드로 관리되는 Grafana 옵저버빌리티 스택(Prometheus 메트릭, Loki 로그, Tempo 트레이스, Alloy 수집, Grafana 대시보드 및 알림)을 설계, 구축, 실행하고 학습합니다. Grafana, PromQL, LogQL 학습 또는 교육, 모니터링 설정, 대시보드/알림 규칙/알림 정책/연락 지점/Alloy 파이프라인/Grafana Terraform 작성 또는 검토, 알림이 과도하거나, 무음이거나, NoData에 멈추거나, 아무에게도 전달되지 않는 문제를 디버깅할 때 사용하세요.

grafana-observability란 무엇인가요?

이 스킬은 프로덕션 등급의 자체 호스팅 Grafana 옵저버빌리티 스택을 설계, 구축, 실행 및 학습하기 위한 포괄적인 가이드입니다. 실제 운영 경험에서 비롯된 10가지 핵심 규칙과 워크플로우를 통해 알림 규칙, 대시보드, Terraform 코드 및 수집 파이프라인을 안전하고 효과적으로 관리하는 방법을 제공합니다. 코드 기반의 진실 공급원(Code as Source of Truth) 원칙을 강조하며, Terraform을 통한 알림 관리, 대시보드 생성 스크립트 사용, Git 기반 버전 관리를 권장합니다. 또한 학습 경로, 아키텍처 참조, 쿼리 작성, 메타 모니터링, 구현 계획 등 다양한 참조 자료를 제공하여 초보자부터 고급 사용자까지 단계적으로 학습할 수 있도록 지원합니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/louij2/grafana-observability-skill/tree/HEAD/.github/skills/grafana-observability

Installed? Explore more 생산성 & 협업 skills: steipete/gemini, steipete/gh-issues, steipete/skill-creator · View all 6 →

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

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.

중요한 규칙

  1. 코드가 진실의 원천입니다. Terraform을 통해 알림을 변경하고, 대시보드는 Git에 있는 생성기 스크립트 또는 JSON으로 구축하세요. UI에서 클릭한 내용은 다음 apply 시 손실되거나, 더 나쁘게는 다음 apply가 자동으로 되돌릴 수 있습니다.
  2. apply 전에 항상 두 가지 드리프트를 확인하세요. (a) 라이브에는 있지만 코드에는 없는 규칙: 대상이 지정되지 않은 apply는 이를 삭제합니다. (b) 코드에는 있지만 라이브에서 변경된 규칙: apply는 이를 되돌립니다. "변경 사항 없음" 계획은 Terraform이 한 번도 본 적 없는 규칙에 대해 아무것도 증명하지 않습니다. references/as-code.md를 참조하세요.
  3. 저장된 계획을 보호하세요. terraform plan -out을 실행한 후, 의도하지 않은 모든 리소스의 delete/replace를 거부하세요. 폴더에 prevent_destroy를 설정하세요. Grafana 폴더를 삭제하면 해당 폴더의 모든 대시보드와 규칙이 삭제됩니다.
  4. 서비스 계정 토큰을 사용하고, admin:password는 절대 사용하지 마세요. 상태가 토큰 인증으로 생성된 경우, 기본 인증 apply는 폴더, 연락 지점 및 정책 트리의 삭제 및 재생성을 계획합니다. 이로 인해 한 번의 apply로 59개의 대시보드와 전체 라우팅 트리가 한 번에 삭제된 적이 있습니다.
  5. 규칙에 절대 notification_settings (연락 지점)를 넣지 마세요. 이 속성이 있는 규칙은 정책 트리를 완전히 건너뜁니다. 심각도 라우팅, 반복 간격 및 음소거 타이밍에서 벗어납니다. 한 환경에서는 217개 규칙 중 196개가 이렇게 설정되어 있었고 아무도 알아채지 못했습니다.
  6. 임계값은 PromQL 내부가 아니라 Grafana의 threshold 단계에 넣으세요. expr > 90을 사용하면 정상 호스트는 시리즈를 반환하지 않으며, Grafana는 이를 OK가 아닌 NoData로 읽습니다. 원시 값을 쿼리하고, 단계 C에서 비교하세요.
  7. 실행 가능성에 따라 라우팅하고, 반복 간격을 실제 레버로 취급하세요. severity (critical/warning/info)와 만성적인 알려진 문제에는 urgency=backlog를 사용하세요. 대부분의 알림 소음은 이미 알려진 문제의 재알림입니다. 중요 알림은 매일, 경고는 매주 반복하고, 매시간 반복하지 마세요.
  8. 에스컬레이션은 지연이어야 하며, 무음이 확인이어야 합니다. 페이지 라우트는 group_wait를 약 15분으로 설정하므로, 알림이 여전히 발생 중이고 무음 해제되지 않은 경우에만 페이지를 보냅니다. 이벤트 스타일 규칙은 keep_firing_for를 대기 시간 이상으로 설정해야 합니다. 그렇지 않으면 에스컬레이션되기 전에 해결됩니다.
  9. 모니터링을 모니터링하세요. 평가 실패, 알림 전송 실패, 억제된(무음) 알림, 오래된 익스포터 및 중단된 백업을 감시하세요. 무음 알림 시스템은 정상 시스템과 똑같이 보입니다. references/meta-monitoring.md를 참조하세요.
  10. 검증하고, 신뢰하지 마세요. 모든 패널 또는 알림 쿼리를 데이터 소스에 대해 먼저 실행하세요. API 쓰기 후에는 객체를 다시 읽어 변경 사항이 적용되었는지 확인하세요. POST 응답은 어떤 콘텐츠가 올라갔는지 알려주지 않습니다. 두 사람 또는 두 세션 간의 일치는 검증이 아닙니다. 하나의 명령어가 검증입니다.

모든 변경에 대한 워크플로우

  1. 패널이나 알림이 답하는 질문과 이를 처리할 사람을 명시하세요. 아무도 알림에 대해 조치를 취하지 않는다면, 이는 알림이 아니라 대시보드 패널입니다.
  2. Explore 또는 데이터 소스 프록시 API를 통해 쿼리를 검증하세요. 데이터가 반환되는지, 그룹화하거나 라우팅할 레이블이 무엇인지, 정상 상태일 때 어떻게 동작하는지(비어 있음? 0?) 확인하세요.
  3. 코드로 작성하세요: Terraform 규칙 그룹, 대시보드 생성기 또는 Alloy 구성입니다. references/alerting.md 또는 references/dashboards.md를 따르세요.
  4. 드리프트를 확인한 후, terraform plan -out=tfplan을 실행하세요. 특히 grafana_notification_policy의 모든 접힌 ~ 블록을 읽으세요. 모든 알림이 어디로 가는지 결정하기 때문입니다.
  5. 저장된 계획을 서비스 계정 토큰으로 적용하세요. 확실하지 않은 경우 -target을 사용하세요.
  6. API에서 다시 읽어 규칙이 평가되는지(상태가 Error/NoData가 아님) 확인하고, 알림의 경우 실제 연락 지점까지 종단 간 테스트를 실행하세요.
  7. 왜를 커밋 메시지에 포함하여 커밋하세요. 선택이 잘못 보이지만 의도적일 경우 코드에 주석을 남기세요.

완료 조건

알림 규칙: 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.mdPromQL 또는 LogQL 작성 시, 또는 쿼리가 잘못된 것 같을 때
dashboards.md대시보드 구축 또는 검토 시
alerting.md규칙, 라우팅, 연락 지점, 무음, 피로 관리 시
as-code.mdTerraform, API, 백업, 드리프트, 복원 시
meta-monitoring.md모니터링 자체가 작동하는지 확인할 때
implementation-plan.md팀이나 회사에 Grafana 도입 시

자산: assets/lab/는 로컬 Docker Compose 실습 환경입니다. assets/terraform-starter/는 안전한 기본값이 이미 설정된 시작용 Terraform 스택입니다.

관련 스킬