본문으로 건너뛰기

v1.8.1 — 알림 트리거 AI 진단 + 문서 대폭 확장

· 약 6분
AWSops Team

외부 알림 시스템의 이벤트를 수신해 상관 분석 → 자동 AI 근본 원인 분석 → Slack 알림까지 한 번에 처리하는 파이프라인을 추가했습니다. 아울러 ADR 18건, 런북 5건, 모듈 CLAUDE.md 11개, Web 가이드 2페이지(KO+EN)가 함께 추가되어 프로젝트 문서가 대폭 보강되었습니다.

핵심 변화

알림 트리거 AI 진단 (ADR-009) · 4종 웹훅 (CloudWatch/Alertmanager/Grafana/Generic) · HMAC 인증 · Slack Block Kit · ADR 18건 신규 · 런북 5건 신규 · Web 가이드 확장

알림 트리거 AI 진단 (ADR-009)​

심각도 critical 인시던트 발생 시 자동으로 부분 AI 진단이 실행됩니다.

파이프라인 흐름​

[CloudWatch Alarm] → SNS Topic → SQS Queue
                                    ↓
                            [EC2 Poller (15s)]
                                    ↓
[Alertmanager/Grafana/Generic] → POST /api/alert-webhook
                                    ↓
                            [alert-correlation.ts]
                                    ↓
                         [alert-diagnosis.ts (AI)]
                                    ↓
                          [Slack/SNS 발송]

지원 소스​

소스수신 방식정규화 스키마
CloudWatch AlarmsSNS → SQS → EC2 폴링CloudWatch 이벤트
Prometheus Alertmanager직접 웹훅 (HMAC)Alertmanager v4
Grafana Alerting직접 웹훅 (HMAC)Grafana unified
Generic JSON직접 웹훅 (HMAC)커스텀 스키마

상관 분석 엔진​

src/lib/alert-correlation.ts가 개별 알림을 인시던트로 그룹화합니다:

기준기본값설명
시간 윈도우5분동일 서비스에서 5분 내 발생한 알림 병합
공통 서비스1개 이상labels.service 또는 resource 일치
공통 네임스페이스1개 이상K8s 알림 labels.namespace 일치
중복 제거1분동일 fingerprint 알림 1분 내 중복 억제
심각도 에스컬레이션warning 3건 5분 내→ critical 승격

스코프 제한 자동 진단​

전체 15섹션 진단과 달리 발화한 알림 범위로만 제한되어 1~2분 내 완료됩니다:

  1. AlertContext 빌드 — 영향받은 서비스/리소스/네임스페이스, 발화 시각(since) 추출
  2. 스코프 제한 수집 — CloudWatch 메트릭을 since 기준 ±10분, 해당 리소스만 필터링
  3. 관련 섹션 선택 — Compute / Network / Container 등 3~5개만 실행
  4. 변경 감지 — Terraform state / CloudTrail 최근 변경 비교
  5. Bedrock Sonnet 분석 — 근본 원인 추정 + Next Steps 제안
// src/lib/alert-diagnosis.ts (핵심 인터페이스)
interface AlertContext {
  services: string[];
  resources: string[];
  namespaces: string[];
  since: Date;     // 발화 시각 − 10분
  until: Date;     // 발화 시각 + 10분
}

Slack 알림 (Block Kit)​

심각도에 따라 채널 라우팅 + 스레드 업데이트로 동작합니다:

심각도기본 채널색상
critical#incidents🔴 빨강
warning#alerts🟠 주황
info#alerts-low🔵 파랑
  • 최초 알림은 메인 메시지, 후속 이벤트(추가 알림 병합, AI 진단 결과, 해결)는 동일 스레드에 reply
  • Webhook 모드와 Bot Token 모드 모두 스레딩 지원 (thread_ts 재사용)
  • CloudWatch OK 또는 Alertmanager resolved 수신 시 ✅ 해결 알림

HMAC 인증​

공유 시크릿은 data/config.json의 alertWebhookSecret에 저장합니다:

curl -X POST https://awsops.example.com/awsops/api/alert-webhook \
  -H 'X-Alert-Source: generic' \
  -H "X-Signature-256: sha256=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$SECRET" | awk '{print $2}')" \
  -H 'Content-Type: application/json' \
  -d "$BODY"

알림 지식 베이스​

data/alert-diagnosis/ 아래에 진단 기록이 영구 저장됩니다:

파일내용
incidents/<id>.json개별 인시던트 + AI 진단 결과
summary-<YYYY-MM>.json월간 통계 (top services, alert names, resolution time)

UI의 Knowledge Base 탭에서 과거 유사 인시던트를 검색할 수 있으며, 새 인시던트 발생 시 유사도 기반으로 자동 추천됩니다.

문서 대폭 확장​

ADR 18건 신규 (011-028)​

v1.8.0에서 추가된 기능들의 설계 의사결정을 공식화했습니다:

번호주제
ADR-011외부 데이터소스 통합 (SSRF 방어 + allowlist)
ADR-012SNS 알림 전략
ADR-013자동 수집 조사 에이전트
ADR-014리포트 생성 및 스케줄링
ADR-015AI 라우팅 우선순위
ADR-016Bedrock 모델 선택 전략
ADR-017캐시 워머 디자인
ADR-018Cognito 인증 플로우
ADR-019SSE 스트리밍
ADR-020HMAC 웹훅 인증
ADR-021Admin Email 권한 모델
ADR-022CDK 스택 분리
ADR-023멀티 라우트 병렬 실행
ADR-024i18n (ko/en) 지원
ADR-025Code Interpreter 샌드박스
ADR-026CloudFront + Lambda@Edge
ADR-027OpenCost + Prometheus (EKS 비용)
ADR-028Memory Store (대화 이력)

런북 5건 신규​

운영 상황에서 실제로 쓸 수 있는 트러블슈팅/설정 가이드:

  • alert-pipeline-troubleshoot.md — 웹훅이 안 올 때, 상관 분석이 인시던트를 못 만들 때, Slack이 안 뜰 때
  • cache-warmer-operations.md — 캐시 워머 디버깅, 쿼리 추가/제거
  • cognito-auth-troubleshoot.md — Lambda@Edge, HttpOnly 쿠키, OAuth2 콜백 이슈
  • deploy-flow.md — 11단계 배포 스크립트 운영 매뉴얼
  • multi-account-setup.md — Aggregator 설정, 교차 계정 IAM 역할, 검증 절차

모듈 CLAUDE.md 11개 신규​

각 소스 모듈의 역할/규칙/주요 파일을 Claude 컨텍스트 파일로 정리:

경로설명
docs/CLAUDE.md문서 구조
runbooks/CLAUDE.md런북 인덱스
decisions/CLAUDE.mdADR 인덱스
agent/CLAUDE.mdStrands Agent + 19 Lambda
scripts/CLAUDE.md11단계 배포 스크립트
tests/CLAUDE.mdVitest 구조
infra-cdk/CLAUDE.mdCDK 스택 구성
src/app/ai-diagnosis/CLAUDE.mdAI 종합 진단 페이지
src/app/alert-settings/CLAUDE.md알림 설정 페이지
src/app/k8s/CLAUDE.mdK8s 페이지
src/lib/collectors/CLAUDE.md7종 Auto-Collect 에이전트

Web 가이드 확장​

Docusaurus 가이드에 v1.8 기능을 반영했습니다:

  • monitoring/ai-diagnosis.md — 15섹션 진단, 내보내기 포맷(DOCX/MD/PDF/PPTX), 스케줄링, 비용 제어 팁
  • monitoring/alerts.md — 알림 파이프라인 전체 흐름, HMAC, 상관 분석, Slack 스레딩, 지식 베이스
  • intro.md — 40 페이지 / 18 API / 11 AI 라우트 반영, "AI 종합 진단 & 알림 파이프라인" 기능 블록 추가
  • faq/troubleshooting.md — Slack 알림 실패 / AI 진단 부분 실패 케이스
  • 한국어(docs/) + 영어(i18n/en/docusaurus-plugin-content-docs/current/) 양쪽 모두 반영

버그 수정 하이라이트​

항목설명
웹팩 동적 import컬렉터 동적 import에 /* webpackInclude: /\.(ts|tsx|js)$/ */ 매직 코멘트 추가 — CLAUDE.md가 webpack context에 포함되어 빌드 실패하던 문제 해결
Bedrock 모델 ID알림 진단에 global.anthropic.claude-sonnet-4-6 사용
Slack 스레드 재사용Webhook 모드에서도 thread_ts를 저장해 후속 이벤트 reply
리포트 다운로드S3 presigned URL 대신 프록시 URL 사용 — STS 세션 만료 시 404 해결
SNS 이메일마크다운을 평문으로 변환 후 발송
캐시 워머Monitoring 쿼리 제외 (CloudWatch FDW 호출이 pg Pool 고갈)
Silent 쿠키 삭제HttpOnly 쿠키는 POST /api/auth로 서버 사이드 삭제

주요 파일 변경​

파일변경 내용
src/app/api/alert-webhook/route.ts4종 소스 웹훅 수신 + HMAC 검증 + 상관 분석 트리거 + 활성 인시던트 GET
src/app/api/notification/route.tsSlack Block Kit / SNS 발송 (심각도 채널 라우팅, 마크다운→평문)
src/lib/alert-types.ts소스별 정규화 함수 (CloudWatch/Alertmanager/Grafana/Generic)
src/lib/alert-correlation.ts상관 분석 엔진 (30초 버퍼, 시간/서비스/리소스 매칭)
src/lib/alert-diagnosis.ts진단 오케스트레이터 (전략 선택, 병렬 컬렉터, AlertContext 스코프)
src/lib/alert-knowledge.ts지식 베이스 (JSONL 저장, 월간 요약, 유사도 검색)
src/lib/slack-notification.tsSlack 클라이언트 (Bot Token/Webhook, 스레드 업데이트)
src/lib/alert-sqs-poller.tsSQS 백그라운드 폴러 (SNS→SQS→EC2, DLQ, Rate Limit)
src/app/alert-settings/page.tsx알림 설정 관리 페이지 (Admin 전용)
docs/decisions/ADR-011~028.md18개 ADR 신규
docs/runbooks/*.md5개 런북 신규
web/docs/monitoring/ai-diagnosis.mdAI 종합 진단 가이드
web/docs/monitoring/alerts.md알림 파이프라인 가이드

버전 비교​

항목v1.8.0v1.8.1변경
알림 파이프라인—웹훅 + 상관 분석 + AI 진단신규
지원 알림 소스—4종 (CloudWatch/Alertmanager/Grafana/Generic)신규
Slack 알림—Block Kit + 스레드 업데이트신규
ADR10개 (001-010)28개 (001-028)+18
런북—5개신규
모듈 CLAUDE.md7개18개+11
Web 가이드 페이지3941+2 (ai-diagnosis, alerts)

참고​

  • ADR-009: 알림 트리거 AI 진단
  • ADR-012: SNS 알림 전략
  • ADR-013: 자동 수집 조사 에이전트
  • ADR-020: HMAC 웹훅 인증