알람 관련 문의 대응

고객이 알람 관련 문제를 신고할 때의 대응 가이드다. UI 화면 기준 증상 → 기술 원인 → 해결 경로 순으로 진행한다.

---

1. 증상 목록

#	고객이 말하는 증상 (UI 기준)	섹션
S-1	"알람이 발생했는데 알림을 못 받았습니다"	2.1
S-2	"알람이 너무 많이 울립니다"	2.2
S-3	"알람 설정/조회 시 오류가 납니다"	2.3

---

2. 증상별 대응 가이드

2.1 S-1: 알람을 수신하지 못했다

증상: 임계값 초과 등의 이벤트가 발생했으나 알람 알림(이메일, 슬랙, 웹훅 등)을 받지 못했다. 또는 알람 이력(알람 > 알람 이력)에 기록은 있으나 외부 알림이 전달되지 않았다.

고객에게 확인

1. 알람 이력 화면에서 해당 알람이 기록되어 있는가?
   • 경로: 알람 > 알람 이력
   • 확인 항목: 날짜/시간, 레벨(WARN/CRITICAL), 서비스명
2. 알람 규칙이 활성화되어 있는가?
   • 경로: 알람 > 알람 설정
   • 확인 항목: 알람 규칙 활성/비활성 토글
3. 알림 채널(이메일, 슬랙 등)이 올바르게 설정되어 있는가?

확인 경로: 알람 > 알람 설정 > [해당 규칙] > 알림 대상
확인 항목: 이메일 주소 / Webhook URL 올바른지 확인

기술지원 확인

1. 알람 API 서버에서 알람 이력 조회:

# 알람 이력 API 직접 호출
curl "http://localhost:6600/meerkat/v1/alert/history/$(date '+%Y%m%d')?level=ALL&limit=10" \
  | python3 -m json.tool

2. API 서버 로그에서 알람 처리 확인:

docker logs flowkat-api-server --tail 100 | grep -i "alert\|alarm\|notification\|webhook"

3. 알람 처리 서비스 확인 (알람은 collect-server와 api-server에서 처리한다):

docker logs flowkat-collect-server --tail 50 | grep -i "alert\|alarm\|plugin"
docker logs flowkat-api-server --tail 50 | grep -i "alert\|alarm\|notification"

확인 포인트:

확인 항목	정상 상태	비정상 상태
알람 이력 API	이력 데이터 존재	빈 배열 또는 404
알람 규칙 상태	활성	비활성
알림 채널 설정	Webhook URL 200 OK	403/404/타임아웃
API 서버 로그	알람 처리 성공	발송 실패 로그

벤더 에스컬레이션 시 전달 정보

• 알람 이력 API 응답: curl http://localhost:6600/meerkat/v1/alert/history/{YYYYMMDD}
• API 서버 로그 (알람 발생 시각 전후 30분): docker logs flowkat-api-server
• 알람 규칙 설정 캡처 (활성 상태 및 알림 채널 설정 화면)
• 알림 채널 URL 또는 이메일 주소 (마스킹 후)
• 알람 발생 예상 시각 및 임계값

---

2.2 S-2: 알람이 과다 발생한다

증상: 짧은 시간 내에 동일한 알람이 수십~수백 건 반복 발생한다. 또는 임계값을 설정하지 않은 서비스에서도 알람이 발생한다.

고객에게 확인

1. 알람 이력에서 반복 발생하는 알람의 서비스명과 내용을 확인한다.
2. 알람 규칙에 쿨다운(알람 억제) 설정이 되어 있는가?
3. 임계값이 너무 낮게 설정되어 있지 않은가?

확인 경로: 알람 > 알람 설정 > [해당 규칙]
확인 항목: 임계값, 지속 시간, 쿨다운 설정

기술지원 확인

# 특정 서버의 최근 알람 건수 확인
curl "http://localhost:6600/meerkat/v1/alert/history/$(date '+%Y%m%d')?level=ALL&limit=100" \
  | python3 -c "import json,sys; d=json.load(sys.stdin); print(len(d.get('result', [])))"

# API 서버에서 알람 발송 빈도 확인
docker logs flowkat-api-server --since 10m | grep "alert" | wc -l

확인 포인트:

확인 항목	정상 상태	비정상 상태
쿨다운 설정	최소 60초 이상	없음 또는 0초
임계값 설정	비즈니스 기준에 맞는 값	너무 낮은 값
알람 발생 건수	정상 업무 범위	분당 수십 건

벤더 에스컬레이션 시 전달 정보

• 과다 발생 알람 규칙 설정 캡처 (임계값, 쿨다운 포함)
• 알람 이력 API 결과 (해당 날짜 전체)
• 알람 발생 서비스/서버의 실제 메트릭 값 (당시 CPU%, 응답시간 등)
• 알람 발생 시작 시각 및 빈도

---

2.3 S-3: 알람 설정/조회 오류

증상: 알람 설정(알람 > 알람 설정) 화면에서 저장 시 오류가 발생하거나, 알람 이력 조회 API에서 에러가 반환된다.

고객에게 확인

1. 어떤 동작 중 오류가 발생했는가? (설정 저장, 이력 조회, API 직접 호출)
2. 화면에 표시된 에러 코드나 메시지가 있는가?
3. API 직접 호출 시: URL 형식이 올바른가? (/meerkat prefix 포함)

기술지원 확인

# API URL prefix 확인 (404 발생 시)
# 올바른 URL 형식: /meerkat/v1/alert/history/{YYYYMMDD}
curl -I "http://localhost:6600/meerkat/v1/alert/history/$(date '+%Y%m%d')"

# 파라미터 형식 확인 (400 발생 시)
# startYmdHm: YYMMDDHHmm (10자리), date: YYYYMMDD (8자리)

# API 서버 상태 확인
docker ps -f name=flowkat-api --format "table {{.Names}}\t{{.Status}}"
docker logs flowkat-api-server --tail 20

확인 포인트:

확인 항목	정상 상태	비정상 상태
API 응답 코드	200 OK	404/400/503
URL 형식	/meerkat/v1/alert/history/...	/v1/alert/history/... (prefix 누락)
날짜 파라미터	YYYYMMDD 8자리	YYYY-MM-DD 형식 오류
컨테이너 상태	Up	Exited/Restarting

벤더 에스컬레이션 시 전달 정보

• 에러 발생 API URL 전문 (파라미터 포함)
• 에러 응답 본문 전체 (JSON)
• docker logs flowkat-api-server --tail 50 출력
• API 서버 포트 매핑: docker port flowkat-api-server

---

3. 관련 문서

모듈	관련 trouble-shooting	핵심 이슈
알람 이력 API	099-alert-history-api	API 404/400, 빈 결과, 파라미터 형식

---

4. 트러블슈팅 플로우