Grafana 연동 - 인프라 알림

Grafana는 수많은 조직이 지표, 로그, 트레이스를 시각화하는 데 사용하는 오픈 소스 분석 및 모니터링 솔루션입니다. Grafana를 Echobell과 연동하면 지표가 알림 조건을 만족하는 순간 바로 알림을 받을 수 있습니다. CPU 사용률 급증, 메모리 부족, 서비스 장애를 비롯해 모니터링 중인 어떤 조건이든 마찬가지입니다.

이 가이드에서는 기본 설정부터 고급 알림 관리 전략까지, Grafana 알림을 Echobell과 연결하는 방법을 단계별로 안내합니다.

사전 준비 사항

시작하기 전에 다음을 준비하세요.

• 채널을 하나 이상 만든 Echobell 계정(여기에서 시작하기)
• Grafana 인스턴스 접근 권한(버전 8.0 이상 권장, 호환성을 위해서는 9.0 이상)
• Grafana에서 알림 전송을 설정할 수 있는 관리자 권한(보통 Admin 또는 Editor 역할이 필요합니다)
• Grafana 대시보드와 지표에 대한 기본적인 이해
• 모니터링 환경과 알림 요구 사항에 대한 이해

설정 개요

연동 과정은 크게 다섯 단계로 이루어지며, 보통 10~15분이면 끝납니다.

1. Echobell 채널 만들기 - Grafana 알림 전용 채널을 준비합니다
2. 알림 템플릿 설정하기 - 알림이 기기에 어떻게 표시될지 정합니다
3. Webhook URL 가져오기 - 채널의 고유한 Webhook 엔드포인트를 확인합니다
4. Grafana Contact point 설정하기 - Grafana가 Echobell로 알림을 보내도록 구성합니다
5. Grafana에서 알림 규칙 만들기 - 어떤 조건에서 알림을 보낼지 정의합니다

설정을 마치면 Grafana에서 발생한 알림이 실시간으로 기기까지 자동으로 전달됩니다.

단계별 가이드

{{alertName}} - {{status}}

🔔 Alert: {{alertName}}
📊 Metric: {{metric}}
📈 Value: {{value}}
⏰ Time: {{time}}
ℹ️ Message: {{message}}

{
  "alertName": "{{ .alertName }}",
  "status": "{{ .status }}",
  "metric": "{{ .metric }}",
  "value": "{{ .value }}",
  "time": "{{ .time }}",
  "message": "{{ .message }}",
  "externalLink": "{{ .dashboardURL }}"
}

연동 테스트하기

설정을 확인하는 방법은 다음과 같습니다.

1. 금방 조건이 충족되는 테스트용 알림 규칙을 만듭니다
2. 조건이 충족될 때까지 기다립니다
3. Echobell 앱에서 알림이 도착했는지 확인합니다
4. 모든 알림 변수가 제대로 표시되는지 확인합니다
5. 알림을 눌러 연결된 Grafana 대시보드가 열리는지 확인합니다

알림 유형

Grafana 알림 채널을 구독할 때는 다음 알림 유형을 상황에 맞게 설정하세요.

• 긴급한 시스템 장애나 비상 상황 알림에는 긴급을 사용하세요
• 심각한 서비스 중단, 임계값 초과, 비상 알림에는 전화를 사용하세요
• 일반적인 정보성 알림과 정기 알림에는 일반을 사용하세요

알림 관리 모범 사례

알림 템플릿 정리하기

모든 채널에서 알림 템플릿을 명확하고 일관되게 유지하세요:

Title: {{alertName}} - {{status}}
Body: 
Server: {{instance}}
Metric: {{metric}}  
Current: {{value}}
Threshold: {{threshold}}

• 구조화된 형식을 사용하세요 - 명확한 레이블로 정보를 정리합니다
• 핵심 정보를 담으세요 - 지표 이름, 값, 임계값, 영향을 받는 시스템
• 이모지는 절제해서 사용하세요 - 심각한 상황에는 🚨, 경고에는 ⚠️, 해결에는 ✅
• 제목은 간결하게 유지하세요 - 문제를 즉시 알 수 있도록 5~8단어를 목표로 합니다
• 템플릿을 테스트하세요 - 실제로 적용하기 전에 테스트 알림을 보내 표시 형식을 확인합니다

중요 알림 설정하기

알림 피로를 피하려면 임계값을 적절히 설정하세요:

• 과도한 알림을 피하세요 - 흥미로운 수준이 아니라 조치가 필요한 수준으로 임계값을 정합니다
• 히스테리시스를 활용하세요 - 알림 발생과 복구에 서로 다른 임계값을 설정합니다
• 관련 알림을 묶으세요 - 서로 연관된 조건은 하나의 알림 규칙으로 합칩니다
• 평가 주기를 알맞게 설정하세요 - 반응 속도와 잡음 감소 사이에서 균형을 잡습니다
• 관찰 구간을 고려하세요 - 알림을 보내기 전에 조건을 여러 번 확인합니다

임계값 설정 예시:

# Bad: Alert at 50% CPU (too sensitive)
cpu_usage > 50

# Better: Alert at 80% for 5 minutes
avg_over_time(cpu_usage[5m]) > 80

# Best: Progressive alerts
# Warning at 70% sustained, Critical at 90%

의미 있는 알림 이름 사용하기

이름만 보고도 다음을 바로 알 수 있도록 알림 이름을 짓습니다.

• 무엇을 모니터링하는지(CPU, 메모리, 디스크)
• 어디에서 발생했는지(프로덕션, 스테이징, 특정 인스턴스)
• 왜 중요한지(사용자가 직접 쓰는 서비스인지, 핵심 데이터베이스인지)

좋은 예시:

• "프로덕션 데이터베이스 - 커넥션 풀 사용량 높음"
• "API 게이트웨이 - 응답 시간 저하"
• "워커 노드 3 - 디스크 공간 부족"

피해야 할 예시:

• "알림 1", "테스트 알림", "CPU 높음"

충분한 맥락 담기

알림 메시지에는 다음 내용이 담겨 있어야 합니다.

• 무슨 일이 일어났는가? 알림을 발생시킨 구체적인 조건
• 어디에서? 어떤 시스템, 서비스 또는 인스턴스인지
• 얼마나 심각한가? 현재 값과 임계값의 비교
• 언제? 알림이 발생한 시각
• 다음에 무엇을 해야 하는가? 관련 대시보드나 런북 링크

우선순위 설정하기

Echobell의 알림 유형을 전략적으로 활용하세요.

• 일반: 정보성 알림, 복구 알림, 급하지 않은 경고
• 긴급: 몇 시간 안에 대응해야 하는 중요한 알림
• 전화: 즉시 대응이 필요한 프로덕션 장애

Grafana의 심각도를 알림 유형에 다음과 같이 매핑하세요.

Critical + Production → Calling
High + Production → Time Sensitive  
Medium → Time Sensitive
Low → Normal
Info/Resolved → Normal

알림 보안

모니터링 환경을 안전하게 보호하세요:

• Webhook URL을 비밀로 유지하세요 - 이 URL만 있으면 인증 없이 알림을 보낼 수 있습니다
• 환경 변수를 사용하세요 - Grafana 프로비저닝 파일에 URL을 하드코딩하지 마세요
• Webhook을 주기적으로 교체하세요 - 특히 팀원이 나갈 때는 반드시 교체합니다
• Webhook 전송 상태를 지켜보세요 - 전송 실패를 추적하고 이상 징후를 확인합니다
• 알림 설정을 점검하세요 - 누가 알림을 수정할 수 있는지 정기적으로 검토합니다
• 알림 출처를 검증하세요 - Contact point에는 Grafana에 내장된 인증 기능을 사용합니다

알림 수명 주기 관리

알림을 건강하게 관리하세요:

1. 정기적으로 검토하기 - 분기마다 알림을 점검해 쓰이지 않는 규칙을 정리합니다
2. 알림 문서화하기 - 각 알림이 왜 필요한지 설명을 덧붙입니다
3. 알림 이력 추적하기 - 어떤 알림이 가장 자주 발생하는지 확인합니다
4. 임계값 조정하기 - 과거 데이터와 오탐 비율을 바탕으로 조정합니다
5. 오래된 알림 보관하기 - 종료되는 서비스의 규칙은 삭제하지 말고 비활성화해 둡니다
6. 버전 관리하기 - Grafana 프로비저닝으로 알림 변경 이력을 관리합니다

성능 고려 사항

• 알림 폭주를 피하세요 - 그룹화와 전송 시점을 알맞게 설정합니다
• 알림 정책을 활용하세요 - 심각도에 따라 알맞은 채널로 라우팅합니다
• 대기 주기와 반복 주기를 설정하세요 - 중복 알림을 막습니다
• 비슷한 알림을 묶으세요 - 집계를 통해 알림 양을 줄입니다
• 시간대를 고려하세요 - 업무 시간 필터링에는 조건을 사용합니다

실제 활용 예시

CPU 과부하 알림

Title: {{instance}} CPU Critical
Body: CPU usage: {{cpu_percent}}%
Duration: {{duration}}
Time: {{time}}
Dashboard: {{dashboard_url}}

메모리 부족

Title: Memory Warning - {{hostname}}
Body: Available: {{available_mb}}MB ({{percent_free}}%)
Threshold: {{threshold_mb}}MB
Action: Check memory-intensive processes

서비스 중단

Title: 🚨 {{service_name}} Unreachable
Body: Health check failed
Last success: {{last_successful_check}}
Impact: {{affected_users}} users affected
Runbook: {{runbook_url}}

일반적인 사용 사례

인프라 모니터링

• CPU, 메모리, 디스크 사용량 임계값
• 네트워크 처리량과 패킷 손실
• 서비스 가용성과 헬스 체크
• 컨테이너 및 파드 상태 모니터링

애플리케이션 성능

• 응답 시간 저하
• 오류율 증가
• 데이터베이스 커넥션 풀 고갈
• 큐 적체와 처리 지연

비즈니스 지표

• 거래량 이상 징후
• 분당 매출 급감
• 활성 사용자 수 변화
• API 요청 한도 근접

보안 모니터링

• 인증 실패 시도
• 비정상적인 접근 패턴
• 인증서 만료 경고
• 방화벽 규칙 위반

더 많은 연동 전략은 Grafana 전화 알림에 관한 블로그 글에서 확인해 보세요.

문제 해결

알림이 오지 않는다면 다음 순서대로 확인해 보세요.

Webhook이 알림을 발생시키지 않는 경우

1. Webhook URL을 정확히 복사했는지 확인하세요

   • Echobell 채널 → Triggers → Webhook으로 이동합니다
   • https://hook.echobell.one/t/를 포함한 전체 URL을 복사합니다
   • Grafana에 붙여 넣을 때 공백이나 다른 문자가 섞이지 않았는지 확인합니다

2. 채널이 활성 상태인지 확인하세요

   • Echobell 앱을 엽니다
   • Grafana 알림 채널로 이동합니다
   • 실수로 삭제하거나 보관하지 않았는지 확인합니다

3. 활성 구독자가 있는지 확인하세요

   • 알림을 받으려면 최소 한 명 이상이 구독하고 있어야 합니다
   • 채널의 구독자 목록을 확인합니다
   • 본인의 구독이 활성 상태인지 확인합니다

4. Grafana Contact point 설정을 확인하세요

   • Grafana에서 Alerting → Contact points로 이동합니다
   • Echobell Contact point를 엽니다
   • URL이 채널의 Webhook 주소와 일치하는지 확인합니다
   • HTTP Method가 POST로 설정되어 있는지 확인합니다
   • Content-Type이 application/json인지 확인합니다

5. Grafana 알림 규칙 설정을 확인하세요

   • Alerting → Alert rules로 이동합니다
   • 실행되어야 할 규칙을 엽니다
   • 규칙이 Echobell Contact point에 연결되어 있는지 확인합니다
   • 알림 정책이 올바른 Contact point로 라우팅되는지 확인합니다

6. Grafana의 알림 이력을 확인하세요

   • Alerting → Alert rules로 이동합니다
   • 규칙을 클릭한 다음 Show history를 엽니다
   • 알림이 실제로 발생했는지(pending 상태에 머물러 있지 않은지) 확인합니다
   • 평가 오류가 없는지 확인합니다

알림은 발생하지만 전달되지 않는 경우

1. Webhook을 직접 테스트해 보세요

   curl -X POST https://hook.echobell.one/t/<channel-token> \
     -H "Content-Type: application/json" \
     -d '{"alertName": "Test", "status": "firing"}'

   이 방법으로는 알림이 오는데 Grafana에서는 오지 않는다면 문제는 Grafana 설정에 있습니다.

2. Grafana의 알림 정책을 확인하세요

   • Alerting → Notification policies로 이동합니다
   • 규칙의 레이블이 정책의 라우팅 규칙과 일치하는지 확인합니다
   • 그룹 대기 시간이나 반복 주기 같은 타이밍 문제가 없는지 확인합니다

3. Grafana 로그를 확인하세요

   • Grafana 로그에서 Webhook 전송 오류를 찾습니다
   • HTTP 상태 코드가 200인지 확인합니다
   • 타임아웃이나 연결 오류가 없는지 살펴봅니다

알림이 잘못 표시되는 경우

1. 템플릿 변수가 Grafana 페이로드와 맞지 않는 경우

   • Grafana는 .alertName, .status처럼 정해진 필드 이름을 보냅니다
   • 템플릿 변수가 페이로드 구조와 일치하는지 확인합니다
   • Grafana의 "Test" 버튼을 눌러 실제 페이로드를 확인해 봅니다

2. 알림에 정보가 빠져 있는 경우

   • 알림 설정에 따라 일부 Grafana 변수는 비어 있을 수 있습니다
   • 템플릿에 대체 값을 추가하세요: {{alertName || "Unknown Alert"}}
   • 사용할 수 있는 템플릿 변수는 Grafana 문서에서 확인합니다

3. JSON 파싱 오류

   • Grafana의 메시지 템플릿이 올바른 JSON인지 확인합니다
   • 이스케이프하지 않은 따옴표나 특수 문자가 없는지 확인합니다
   • 온라인 JSON 검증 도구로 페이로드 구조를 확인합니다

알림 타이밍 문제

1. 알림이 늦게 도착하는 경우

   • 네트워크 연결 상태를 확인합니다
   • Grafana가 Echobell 서버에 접근할 수 있는지 확인합니다
   • Grafana의 평가 주기를 확인합니다(지연의 원인이 될 수 있습니다)
   • 알림 정책의 타이밍 설정을 확인합니다

2. 중복 알림이 오는 경우

   • 알림 정책의 반복 주기 설정을 확인합니다
   • 같은 조건으로 여러 규칙이 함께 실행되고 있지는 않은지 확인합니다
   • 채널에 Contact point가 하나만 설정되어 있는지 확인합니다

3. 조용한 시간대에 도착하는 알림

   • iOS 집중 모드가 알림 전달에 영향을 줄 수 있습니다
   • 긴급 알림과 전화 알림은 일부 집중 모드를 통과할 수 있습니다
   • 기기의 알림 설정을 확인합니다

그래도 해결되지 않는다면

위 내용을 모두 시도했는데도 문제가 계속된다면 다음을 확인해 보세요.

1. Grafana 디버그 로그 활성화하기

   • grafana.ini에 [log] 섹션을 추가하고 level = debug를 설정합니다
   • 로그에서 Webhook 전송 시도와 응답을 확인합니다

2. Grafana에 내장된 테스트 기능 사용하기

   • Contact point 설정에서 "Test"를 눌러 샘플 알림을 보냅니다
   • 문제가 규칙에 있는지 전송 과정에 있는지 구분하는 데 도움이 됩니다

3. 다른 알림 규칙으로 시도하기

   • 반드시 실행될 조건으로 간단한 테스트 규칙을 만듭니다
   • 테스트 규칙은 동작하는데 실제 규칙이 동작하지 않는다면 문제는 규칙 설정에 있습니다

4. 지원팀에 문의하기

   • 지원 센터를 방문하세요
   • echobell@weelone.com으로 다음 내용을 함께 보내 주세요:
     • Grafana 버전
     • 샘플 알림 페이로드(민감한 정보는 제거)
     • Webhook URL(토큰은 가린 상태로)
     • 시도해 본 방법
     • 예상한 동작과 실제 동작

관련 문서 및 자료

Echobell 문서

• Webhook 연동 가이드 - Webhook 기능 자세히 알아보기
• 템플릿 시스템 - 알림 템플릿 문법 익히기
• 조건 - 기준에 따라 알림 필터링하기
• 알림 유형 - 알림 우선순위 이해하기
• 시작하기 - Echobell 기본 사용법과 설정

Grafana 자료

• Grafana Alerting 문서 - Grafana 공식 알림 가이드
• Contact points - Grafana Contact point 설정 방법
• Notification policies - 알림 라우팅과 그룹화
• Alert rules - 알림 규칙 만들기와 관리

관련 연동

• Prometheus 연동 - Prometheus 알림 직접 연결하기
• Uptime Kuma - 웹사이트 가동 시간 모니터링
• GitHub Actions - CI/CD 파이프라인 알림
• Home Assistant - 스마트홈 알림

블로그 글

• Grafana 알림을 전화로 받기 - 한 단계 더 나아간 Grafana 연동 전략
• GitHub Actions 실패를 놓치지 않는 방법 - CI/CD 알림 모범 사례
• UTC 조건으로 시간대를 지정해 알림 보내기 - 업무 시간 필터링

다음 단계

Grafana와 Echobell 연동을 마쳤다면 다음을 진행해 보세요.

1. 알림 다듬기 - 실제 사용 패턴에 맞춰 임계값을 조정합니다
2. 채널 추가로 만들기 - 심각도별로 채널을 나누어 운영합니다
3. 다른 연동 살펴보기 - 더 많은 도구를 Echobell에 연결해 보세요(전체 연동 보기)
4. 팀과 공유하기 - 알림 채널에 팀원을 추가합니다
5. 설정 문서화하기 - 특정 알림에 대응하는 런북을 만들어 둡니다
6. 알림 효과 확인하기 - 오탐 비율과 대응 시간을 추적합니다

더 많은 시스템을 모니터링하고 싶으신가요? 널리 쓰이는 다른 모니터링 도구와 플랫폼은 전체 연동 가이드에서 확인해 보세요.