알림 및 장애 대응 Runbook

🎯 목적

이 문서는 Polaris 운영 중 알림이 발생했을 때 팀원이 어떤 순서로 확인하고 대응할지 정리한 Runbook이다.

MVP 단계에서는 알림을 많이 만드는 것보다, 핵심 장애를 놓치지 않고 팀원이 같은 절차로 대응하는 것이 중요하다. 이 문서는 장애 원인을 한 번에 맞히기 위한 문서가 아니라, 장애 상황에서 확인 순서를 줄이고 영향 범위를 빠르게 판단하기 위한 체크리스트다.

💡 왜 Runbook이 필요한가

장애가 발생하면 가장 어려운 것은 “무엇부터 봐야 하는지”다. 알림만 있고 대응 순서가 없으면 각자 다른 로그를 보거나, 이미 확인한 내용을 반복해서 확인하게 된다.

Polaris의 장애는 단순히 서버가 죽는 형태로만 나타나지 않는다.

• Redis 장애는 AI fallback 증가나 인증 문제로 나타날 수 있다.
• event-log 저장 실패는 메인 플로우 실패가 아니라 분석 데이터 유실로 나타날 수 있다.
• AI provider 장애는 사용자에게 5xx가 아니라 fallback 품질 저하로 보일 수 있다.
• 보상 처리 실패는 즉시 장애보다 사용자 신뢰 문제로 커질 수 있다.
• 프론트 에러는 백엔드가 정상이어도 사용자 화면에서 실패로 나타난다.

따라서 Runbook은 알림 발생 후 팀원이 같은 언어로 상황을 분류하고, 영향 범위를 확인하고, 임시 조치를 결정하기 위한 기준이 된다.

🧭 이 문서의 범위

구분 이 문서에서 다룸 상세 문서

🚨 알림 등급	P0/P1/P2/P3 기준	이 문서
🚦 대응 순서	알림 확인, 담당자 지정, 영향 범위 판단	이 문서
🛠️ 장애 시나리오	Gateway, DB, Redis, AI fallback, 보상, 프론트 에러	이 문서
🖥️ 인프라 healthcheck	명령어와 1차 확인만 포함	인프라 모니터링
📈 API/JVM 지표	장애 판단에 필요한 지표만 참조	애플리케이션 메트릭
📊 제품/AI 로그	영향 범위 판단에 필요한 쿼리만 참조	사용자/제품 로그
🤖 AI Ops	향후 자동 리포트 연결만 설명	AI Ops 로드맵

💬 알림 채널

추천 채널:

• #polaris-alerts: 자동 알림
• #polaris-dev: 대응 논의
• #polaris-incident-log: 장애 기록

MVP에서는 #polaris-alerts 하나로 시작해도 된다. 다만 알림 발생 후 누가 확인 중인지, 현재 상태가 무엇인지는 스레드에 남긴다.

권장 상태값:

상태 의미

ACK	알림을 확인했고 담당자가 붙음
INVESTIGATING	원인과 영향 범위 확인 중
MITIGATED	임시 조치로 사용자 영향 완화
RESOLVED	정상 복구 확인
FOLLOW_UP	재발 방지 작업 필요

🧯 알림 등급

등급 의미 예시 대응 목표

🔴 P0	서비스 핵심 사용이 거의 불가능	frontend 접속 불가, gateway down, DB down, 로그인 전체 실패, 대부분 API 5xx	즉시 확인, 빠른 복구, 사후 기록
🟠 P1	핵심 기능 장애 또는 데이터 정합성 위험	미션 완료 실패, 별조각 지급 실패, Redis down으로 인증 영향, AI fallback 급증 장기 지속	10분 이내 확인, 영향 범위 파악, 임시 조치
🟡 P2	일부 기능 저하 또는 품질 저하	공유 카드 실패 증가, 특정 화면 에러 증가, API latency 증가, CPU/memory 높음	당일 확인, 원인 기록, 후속 이슈
🔵 P3	참고성 알림	신규 프론트 에러 첫 발생, 일시적 metric 변동, 낮은 빈도의 비핵심 API 오류	필요 시 확인, 추세 관찰

🚦 공통 대응 순서

1. 알림 스레드에 ACK를 남긴다.
2. 담당자를 1명 지정한다.
3. 사용자 영향 여부를 먼저 판단한다.
4. 최근 배포 여부를 확인한다.
5. 인프라 생존성, API 오류, 제품 로그 순서로 확인한다.
6. 임시 조치가 필요하면 rollback/restart/fallback 전환 여부를 결정한다.
7. 복구 후 같은 지표가 정상화됐는지 확인한다.
8. P0/P1은 장애 기록을 남긴다.

🧾 공통 알림 템플릿

필드 예시

Severity	P1
Service	redis
Scenario	Redis healthcheck failed
StartedAt	2026-05-22 15:20 KST
DetectedAt	2026-05-22 15:22 KST
TimeWindow	last 5 minutes
Evidence	redis-cli ping failed 2 times, RATE_LIMIT_UNAVAILABLE increased
Possible Impact	AI mission generation may use fallback
First Actions	docker compose ps redis, redis-cli ping, check redis logs
Owner	담당자
Status	ACK

🛠️ 시나리오별 Runbook

🚪 Gateway Down

등급: 🔴 P0

감지:

• external uptime check 실패
• /actuator/health 실패
• gateway container down
• 대부분 API 5xx

1차 확인:

docker compose ps
docker logs --tail=200 <gateway-container>
curl -i <http://localhost>:<port>/actuator/health

확인할 것:

• gateway container가 떠 있는가
• 최근 배포 직후인가
• 환경변수 누락이 있는가
• DB/Redis 연결 실패인가
• port conflict가 있는가
• reverse proxy/Nginx가 정상인가

임시 조치:

• gateway container restart
• 직전 정상 image rollback
• 환경변수 복구
• reverse proxy 재시작

복구 확인:

• 외부 domain 접속 성공
• /actuator/health 정상
• 핵심 API 5xx 감소
• 프론트 홈 로딩 성공

🐘 PostgreSQL Down

등급: 🔴 P0

감지:

• pg_isready 실패
• gateway health db down
• 대부분 API 5xx
• 로그인/미션/지갑 조회 실패

1차 확인:

docker compose ps postgres
pg_isready -h <host> -p 5432 -U <user> -d <db>
df -h
docker logs --tail=200 <postgres-container>

확인할 것:

• DB container가 떠 있는가
• disk full 여부
• connection limit 초과 여부
• migration 실패 여부
• 최근 배포 후 DB schema 문제가 있는가
• snapshot/backup이 있는가

임시 조치:

• disk/log 정리
• PostgreSQL container restart
• connection 누수 의심 시 앱 container 상태 확인
• 필요 시 snapshot/backup 확인

복구 확인:

• pg_isready 정상
• gateway health 정상
• 로그인/홈/미션 조회 API 정상
• 5xx 감소

⚡ Redis Down

등급: 🟠 P1 또는 🔴 P0

P0 조건:

• Redis down과 동시에 로그인/token/API 5xx가 증가한다.

P1 조건:

• Redis down이지만 사용자 플로우는 fallback으로 유지된다.

감지:

• redis-cli ping 실패
• Redis health down
• ai_usage_logs.error_type = RATE_LIMIT_UNAVAILABLE

1차 확인:

docker compose ps redis
redis-cli -h <host> -p 6379 ping
docker logs --tail=200 <redis-container>

AI 영향 확인:

select count(*)
from ai_usage_logs
where created_at >= now() - interval '5 minutes'
  and error_type = 'RATE_LIMIT_UNAVAILABLE';

확인할 것:

• Redis container가 떠 있는가
• Redis memory가 부족한가
• password/host env가 바뀌었는가
• 인증/토큰 흐름이 Redis에 의존하고 있는가
• AI rate limiter가 fail-closed인지 fail-open인지

임시 조치:

• Redis container restart
• memory/disk 확인
• Redis env 복구
• AI rate limit 정책 변경은 팀 합의 후 진행

복구 확인:

• redis-cli ping 정상
• token/login 관련 오류 감소
• RATE_LIMIT_UNAVAILABLE 감소
• AI fallback rate 정상화

🤖 AI Fallback 급증

등급: 🟠 P1 또는 🟡 P2

감지:

• 15분 fallback rate 30% 이상: P2
• 15분 fallback rate 70% 이상: P1
• RATE_LIMIT_UNAVAILABLE 발생: P1 후보

확인 쿼리:

select
  status,
  error_type,
  count(*) as count
from ai_usage_logs
where created_at >= now() - interval '15 minutes'
group by status, error_type
order by count desc;

확인할 것:

• Redis 장애인가
• provider timeout인가
• rate limit 초과인가
• invalid output/policy violation인가
• 최근 prompt 변경이 있었는가
• 최근 AI 모듈 배포가 있었는가

영향:

• 사용자 플로우는 유지될 수 있다.
• 미션 문구가 외부 AI 생성이 아닌 fallback으로 제공될 수 있다.
• 개인화 품질이 저하될 수 있다.

임시 조치:

• Redis 복구
• provider disabled/local mode 확인
• rate limit 설정 확인
• prompt 변경 rollback 검토
• fallback copy 품질 확인

복구 확인:

• fallback rate 정상화
• provider error 감소
• AI latency p95 정상화
• 미션 생성 API 오류 없음

🧩 미션 완료/보상 실패

등급: 🟠 P1

감지:

• POST /completion-answers 5xx 증가
• MISSION_COMPLETED는 있는데 wallet transaction이 없는 경우
• 사용자가 보상 미반영 제보
• mission reward outbox 실패 증가

확인 쿼리:

select *
from user_missions
where status = 'COMPLETED'
order by updated_at desc
limit 20;

select *
from star_piece_transactions
where reason like '%MISSION%'
order by created_at desc
limit 20;

확인할 것:

• mission status 변경과 wallet transaction 생성이 함께 되었는가
• idempotency key가 저장되었는가
• wallet reward gRPC 호출 실패가 있었는가
• reward outbox 재처리 대상이 있는가
• 중복 보상 또는 누락 보상 가능성이 있는가

임시 조치:

• 영향 user/mission 범위 추출
• outbox 재처리 상태 확인
• 수동 보상이 필요하면 승인 후 감사 기록 남기기
• 중복 지급 가능성이 있으면 관련 API 임시 제한 검토

복구 확인:

• 완료 API 5xx 감소
• reward transaction 정상 생성
• outbox pending/fail 건 감소
• 사용자 제보 건 처리 완료

🧯 프론트 에러 급증

등급: 🟠 P1 또는 🟡 P2

감지:

• Sentry issue 급증
• OAuth callback 실패 증가
• mission/share 핵심 화면 에러 증가
• 특정 release 이후 error 증가

확인할 것:

• release version
• browser/device
• route
• stacktrace
• API endpoint/status
• 최근 프론트 배포 여부
• source map 연결 여부

임시 조치:

• frontend rollback
• feature flag/fixture mode 여부 확인
• API schema mismatch 확인
• 특정 플로우 임시 안내 문구 추가

복구 확인:

• Sentry issue 발생률 감소
• OAuth/mission/share 핵심 플로우 정상
• 사용자 재현 케이스 해결

🧾 Event Log 저장 실패

등급: 🟡 P2 또는 🟠 P1

P1 조건:

• 제품 지표/보상 감사에 필요한 이벤트가 대량 유실될 가능성이 있다.

감지:

• event-log gRPC 실패 로그 증가
• event_logs 신규 row 급감
• 핵심 이벤트가 도메인 상태 변화와 불일치

확인할 것:

• event-log container 상태
• event-log DB connection 상태
• gRPC address/env 설정
• 최근 배포 여부
• 도메인 트랜잭션은 성공 중인지

영향:

• 사용자 메인 플로우는 정상일 수 있다.
• 제품 분석 지표와 AI/미션 funnel 데이터가 누락될 수 있다.
• 보상 원장 자체와 제품 이벤트 로그를 혼동하지 않는다.

임시 조치:

• event-log service restart
• gRPC 설정 확인
• 장애 시간대 이벤트 유실 범위 기록
• 필요 시 도메인 테이블 기준으로 지표 보정

📝 장애 기록 양식

P0/P1 장애는 복구 후 짧은 기록을 남긴다. 목적은 책임 추궁이 아니라, 같은 문제가 다시 생겼을 때 더 빨리 대응하기 위한 팀 지식 축적이다.

항목 내용

요약	어떤 문제가 있었는지 한 줄로 정리
발생 시간	장애가 시작된 시각
감지 방법	어떤 알림/제보/지표로 알게 되었는지
영향 범위	영향을 받은 기능과 사용자 범위
원인	확인된 원인 또는 추정 원인
대응 내용	어떤 조치를 했는지
복구 시간	정상화된 시각
재발 방지	다음에 막기 위한 작업
후속 작업	이슈/PR/문서 작업

🤖 AI Ops 리포트와의 연결

향후 AI Ops는 이 Runbook을 기반으로 Slack 리포트를 자동 생성한다.

LLM이 생성해야 하는 내용:

• 장애 요약
• 영향 범위
• 가능한 원인 후보
• 근거 metric/log/query
• 즉시 확인할 명령/쿼리
• 관련 Runbook 링크
• 재발 방지 후보

주의:

• LLM 분석은 추정이며 최종 판단은 사람이 한다.
• 자동 복구 명령은 실행하지 않는다.
• 개인정보와 민감 로그는 마스킹 후 전달한다.