V1에서는 장애를 사용자 CS 문의로 먼저 알았다. CloudWatch 알람은 있었지만 SNS 토픽에 구독자가 없어 아무에게도 전달되지 않았다. V2는 요청 경로에서 장애를 판단할 지점을 정하고, 지점마다 알림 규칙을 두어 Discord로 개발팀에 보낸다. 목표는 사용자보다 먼저 장애를 아는 것이다.

모니터링 도구 선정과 수집 구조는 V2 중앙 집중식 모니터링 시스템 설계를 따른다. 이 문서는 그 위의 알림 계층만 다룬다.

1. V1의 알림은 왜 동작하지 않았는가?
2. 장애는 어디에서 판단하는가?
3. 알림 경로를 왜 두 개로 나누는가?
4. 어떤 규칙이 어느 채널로 가는가?
5. 어떤 순서로 켜고 어떻게 검증하는가?

요청이 지나가는 순서를 따라가며, 지점마다 **"여기가 깨지면 사용자가 무엇을 겪는가"**를 기준으로 판단 지점을 정했다.

flowchart LR
  USER["사용자"] --> ALB["① Prod ALB"]
  ALB --> TG["② 대상 그룹<br/>헬스체크"]
  TG --> TASK["③ ECS 서비스<br/>rest · websocket · fastapi"]
  TASK --> APPM["④ 애플리케이션<br/>5xx · 지연 · Hikari · JVM"]
  TASK --> REDIS["⑤ Redis Pub/Sub<br/>채팅 fan-out"]
  TASK --> RDS["RDS MySQL"]

  subgraph OBS["⑥ 관측 계층"]
    ALLOY["Alloy"] --> LOKI["Loki"]
    PROM["Prometheus"]
    GRAF["Grafana"]
  end
  TASK -. 로그 .-> ALLOY
  TASK -. 메트릭 .-> PROM

ALB 자체 5xx(①)와 애플리케이션 5xx(④)는 다른 신호다. ①은 요청이 앱까지 가지 못한 경우이고, ④는 앱이 받았지만 실패한 경우다. 그래서 두 신호를 서로 다른 경로에서 본다.

Grafana Alerting은 모니터링 EC2 안에서 돈다. 모니터링 호스트가 죽으면 서비스 알림도 같이 멈추고, 알림이 오지 않는 상태가 정상처럼 보인다. 그래서 다음 두 가지는 모니터링 스택과 독립된 CloudWatch Alarm에 둔다.

• 모니터링 호스트가 죽어도 알아야 하는 것 (⑥)
• AWS가 이미 지표를 주는 것 (①②③⑤). Prometheus로 복제하지 않는다.

애플리케이션 내부 지표(④)는 Prometheus에만 있으므로 Grafana Alerting이 맡는다.

flowchart LR
  subgraph SRC["AWS 지표"]
    ALBM["ALB · 대상 그룹"]
    ECSM["ECS Container Insights"]
    ECM["ElastiCache"]
    HB["모니터링 하트비트<br/>sync.sh가 1분마다 전송"]
    ALF["Alloy 로그 지표 필터"]
  end

  subgraph A["경로 A · CloudWatch"]
    CWA["CloudWatch Alarm<br/>moyeota-v2-*"]
    SNS["SNS<br/>moyeota-v2-alerts"]
    EB["EventBridge 규칙<br/>ALARM · OK 상태 변경"]
    APID["API destination<br/>입력 변환기 → JSON"]
  end

  subgraph B["경로 B · 모니터링 EC2"]
    PROM["Prometheus"]
    GA["Grafana Alerting<br/>규칙 6개 · 1분 평가"]
    POL["알림 정책<br/>stage · severity 라우팅"]
  end

  APP["ECS 태스크<br/>:8090 /actuator/prometheus<br/>fastapi /metrics"]
  MAIL["이메일"]
  INC["Discord #incident"]
  ALT["Discord #alerts"]

  ALBM & ECSM & ECM & HB & ALF --> CWA
  CWA --> SNS --> MAIL
  CWA -->|상태 변경 이벤트| EB --> APID --> INC
  APP -->|scrape 30초| PROM --> GA --> POL
  POL -->|"stage=prod & severity=page"| INC
  POL -->|그 외| ALT

모니터링 설계 단계(설계 문서 6절)에서는 SNS → Lambda → Discord를 계획했지만, 구현하면서 바꿨다. SNS는 Discord 웹훅이 요구하는 {"content": "..."} 형식으로 보낼 수 없어 중간에 변환기가 필요하다. Lambda를 쓰면 코드·런타임·패키징을 따로 관리해야 한다. 반면 EventBridge 입력 변환기로 JSON을 만들고 API destination으로 웹훅에 바로 POST하면 실행 코드 없이 같은 일을 한다.

Discord 메시지 형식은 다음과 같다. 알람 사유(reason) 문자열은 따옴표가 섞여 JSON이 깨질 수 있어서 넣지 않고, 콘솔 링크로 대신한다.

**[ALARM]** `moyeota-v2-prod-alb-elb-5xx` (이전 OK)
2026-10-15T05:00:00Z
https://ap-northeast-2.console.aws.amazon.com/cloudwatch/home?region=ap-northeast-2#alarmsV2:alarm/moyeota-v2-prod-alb-elb-5xx

모니터링 호스트의 sync.sh는 1분마다 Prometheus·Loki·Grafana 상태(ComponentHealthy 0 또는 1)와 데이터 디스크·메모리 사용률을 CloudWatch에 보낸다. 하트비트 알람은 treat_missing_data = breaching으로 설정해서, 호스트가 통째로 죽어 지표가 끊겨도 ALARM이 된다.

Loki로 가는 로그 유실은 별도로 잡는다. Alloy가 재시도를 모두 실패하고 로그 배치를 버리면 자기 로그(awslogs)에 final error sending batch를 남긴다. 이 문구를 로그 지표 필터로 세어 알람을 건다. 이때 CloudWatch Logs에는 원본 로그가 남아 있으므로 사후 분석은 가능하다.

알람 이름은 모두 moyeota-v2-로 시작한다. 아래 표에서는 이 접두어를 생략했다.

지속 시간은 배포 중 정상 동작을 오탐하지 않도록 정했다.

• 대상 그룹 3분: 롤링 배포 중 새 태스크가 헬스체크를 통과하기 전의 짧은 UnHealthy 구간을 넘긴다.
• 태스크 수 5분: 배포·Spot 교체로 Running이 잠깐 desired보다 적은 구간을 넘긴다.
• Alloy DAEMON 태스크 수: DAEMON 서비스의 desired는 컨테이너 인스턴스 수와 같다. 메모리 여유가 없어 Alloy가 못 뜬 호스트가 있으면 이 알람이 울리고, 그 호스트의 로그는 Loki로 가지 않는다.

• 저트래픽 제외: 요청이 몇 건 없을 때는 1건만 실패해도 비율이 크게 튀어 오탐이 생긴다. 그래서 초당 0.1건(분당 6건) 이상일 때만 비율을 본다.
• page와 warning의 기준: 사용자가 이미 실패를 겪고 있으면(응답 없음, 5xx) page로 둔다. 곧 문제가 될 징후(지연, 커넥션 대기, 힙)는 warning으로 둔다.
• p99 2.5초: BE에 요청한 SLO bucket 경계(1s, 2.5s)와 맞췄다. 사용자 영향을 최종 판단하는 일은 SLO burn-rate 알림(7절)이 맡고, 이 규칙은 조기 경보 역할을 한다.
• 각 규칙의 annotation에 1차 확인 항목을 적어 두었다. 예를 들어 5xx 비율 알림에는 "V2 서비스 상세 대시보드의 URI별 요청량과 에러 로그를 확인한다"가 함께 간다.

CloudWatch 경로에는 severity 구분이 없어서 모두 #incident로 간다. 이 경로에 둔 알람은 모두 관측 계층이 위험하거나 사용자 진입이 막힌 상황이라서 즉시 대응 대상으로 본다.

alert_stages의 기본값은 ["prod"]이다. Grafana 규칙도 같은 변수를 stage 정규식으로 쓴다.

예외로, 모니터링 하트비트 알람은 스테이지와 상관없이 만들고, Redis 알람은 ElastiCache가 있는 모든 스테이지에 만든다.

모든 기능은 변수 기본값이 꺼짐(false)이라서, 코드를 머지하는 것만으로는 리소스가 생기지 않는다. 아래 순서대로 켠다.

경로 A 테스트:

# SNS 구독 상태
aws sns list-subscriptions-by-topic --topic-arn $(terraform output -raw alerts_sns_topic_arn)

# 알람을 강제로 ALARM으로 바꿔 이메일·Discord 수신 확인 → 다음 평가에서 OK가 오는지 확인
aws cloudwatch set-alarm-state \
  --alarm-name moyeota-v2-monitoring-data-disk-high \
  --state-value ALARM --state-reason "manual test"

• V2 중앙 집중식 모니터링 시스템 설계
• 레포 issues/monitoring/: issue-04·pr-04(CloudWatch 알람·Discord), issue-08·pr-08(Grafana 알림), issue-09(SLO), be-request-monitoring
• Amazon EventBridge — API destinations
• Amazon CloudWatch — Alarm events and EventBridge
• Grafana — Use configuration files to provision alerting resources
• Google SRE Workbook — Alerting on SLOs