feat(monitoring): integrate prometheus and promtail log aggregation with sms alerts

2026-06-05 18:34:22 +09:00
parent 4bae1dd00d
commit 1f47abb860
4 changed files with 284 additions and 0 deletions
--- a/.env.sample
+++ b/.env.sample
@@ -152,3 +152,11 @@ DEVFRONT_URL=http://localhost:5174
 DEVFRONT_CALLBACK_URLS=http://localhost:5174/auth/callback,https://sso.hmac.kr/devfront/auth/callback
 ORGFRONT_CALLBACK_URLS=http://localhost:5175/auth/callback,https://sso.hmac.kr/orgfront/auth/callback
 VITE_ORGCHART_URL=
+
+# --- Monitoring & Alerts (Grafana SMS Webhook & Promtail) ---
+SMS_WEBHOOK_PORT=8080
+# 알림 수신 대상 휴대폰 번호 (쉼표 구분)
+MONITOR_RECIPIENT_PHONES=01012345678,01098765432
+# 로그를 전송받을 Loki 서버 엔드포인트 URL
+LOKI_URL=http://loki:3100/loki/api/v1/push
+
--- a/docker/docker-compose.staging.template.yaml
+++ b/docker/docker-compose.staging.template.yaml
@@ -108,6 +108,37 @@ services:
    networks:
      - baron_net

+  grafana-sms-webhook:
+    image: ${SMS_WEBHOOK_IMAGE_NAME:-ai-team/grafana-sms-webhook}:${IMAGE_TAG:-latest}
+    container_name: grafana_sms_webhook
+    restart: unless-stopped
+    env_file:
+      - .env
+    environment:
+      - NAVER_CLOUD_ACCESS_KEY=${NAVER_CLOUD_ACCESS_KEY}
+      - NAVER_CLOUD_SECRET_KEY=${NAVER_CLOUD_SECRET_KEY}
+      - NAVER_CLOUD_SERVICE_ID=${NAVER_CLOUD_SERVICE_ID}
+      - NAVER_SENDER_PHONE_NUMBER=${NAVER_SENDER_PHONE_NUMBER}
+      - MONITOR_RECIPIENT_PHONES=${MONITOR_RECIPIENT_PHONES}
+    ports:
+      - "${SMS_WEBHOOK_PORT:-8080}:8080"
+    networks:
+      - baron_net
+
+  promtail:
+    image: grafana/promtail:2.9.0
+    container_name: baron_promtail
+    restart: unless-stopped
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock:ro
+      - /var/lib/docker/containers:/var/lib/docker/containers:ro
+      - ./promtail-config.staging.template.yaml:/etc/promtail/promtail-config.yaml:ro
+    command: -config.file=/etc/promtail/promtail-config.yaml
+    environment:
+      - LOKI_URL=${LOKI_URL:-http://loki:3100/loki/api/v1/push}
+    networks:
+      - baron_net
+
 networks:
  baron_net:
    external: true
--- a/docker/promtail-config.staging.template.yaml
+++ b/docker/promtail-config.staging.template.yaml
@@ -0,0 +1,33 @@
+server:
+  http_listen_port: 9080
+  grpc_listen_port: 0
+
+positions:
+  filename: /tmp/positions.yaml
+
+clients:
+  - url: ${LOKI_URL:-http://loki:3100/loki/api/v1/push}
+
+scrape_configs:
+  - job_name: baron-sso-container-logs
+    docker_sd_configs:
+      - host: unix:///var/run/docker.sock
+        refresh_interval: 10s
+    relabel_configs:
+      - source_labels: ['__meta_docker_container_name']
+        regex: '/(.*)'
+        target_label: 'container_name'
+      # Baron SSO 및 핵심 Ory Stack 컨테이너만 필터링하여 로그 수집
+      - source_labels: ['container_name']
+        regex: '(baron_.*|oathkeeper|kratos|hydra|keto)'
+        action: keep
+      # 컨테이너 명에서 앞의 접두사를 떼어 서비스 및 잡 라벨 부여 (예: baron_backend -> backend)
+      - source_labels: ['container_name']
+        regex: 'baron_(.*)'
+        target_label: 'service'
+      - source_labels: ['container_name']
+        regex: 'baron_(.*)'
+        target_label: 'job'
+      # 정적 라벨 추가
+      - target_label: 'app_env'
+        replacement: 'stage'
--- a/docs/external_healthcheck_monitoring_design.md
+++ b/docs/external_healthcheck_monitoring_design.md
@@ -0,0 +1,212 @@
+# 외부 통합 모니터링 및 로그 수집 시스템 설계서 (Prometheus + Promtail + Loki)
+
+## 1. 개요 (Overview)
+본 문서는 Baron SSO 서비스가 배포될 **스테이징 서버**의 기존 도커(Docker) 기반 모니터링 및 로깅 인프라를 활용하여, **가용성 헬스체크(메트릭 수집)**와 **컨테이너 실시간 로그 통합 수집(로그 분석)**을 동시에 달성하고, 장애 상황 발생 시 담당자에게 즉시 SMS를 전송하는 엔드투엔드(End-to-End) 연동 설계를 정의합니다.
+
+- **메트릭(상태) 모니터링**: Prometheus + Grafana를 활용하여 `/health` 및 프론트엔드 포트 가용성 수집
+- **로그(텍스트) 모니터링**: Promtail + Loki를 활용하여 컨테이너 실시간 로그 수집 및 에러/패닉 로그 실시간 알림
+- **장애 알림 전파**: 기존 사내 SMS 게이트웨이 서비스인 [grafana-sms-webhook](https://gitea.hmac.kr/ai-team/grafana-sms-webhook)를 연동하여 실시간 알림 수신
+
+---
+
+## 2. 네트워크 및 데이터 수집 아키텍처 (Architecture)
+
+```
+[ Staging Host Docker Environment ]
+
+   +-------------------------------------------------------------+
+   |  baron_net (External Docker Network)                        |
+   |                                                             |
+   |  +--------------------+  +--------------------+             |
+   |  |   baron_backend    |  |  baron_adminfront  | ...         |
+   |  |   (Port 3000)      |  |  (Port 5173)       |             |
+   |  +----+---------+-----+  +----+---------+-----+             |
+   |       |         |             |         |                   |
+   |       |         |             |         |                   |
+   |       |         | (Docker Log |         |                   |
+   |       |         |  Stream)    |         |                   |
+   |       |         +-------+     |         |                   |
+   |       |                 v     |         v                   |
+   |       |            +----+-----+---------+-----+             |
+   |       |            |      baron_promtail      | (신규 수집기) |
+   |       |            |   (Docker Socket 마운트)  |             |
+   |       |            +----------+---------------+             |
+   |       |                       | (Push Logs)                 |
+   |       |                       v                             |
+   |       |            +----------+---------------+             |
+   |       |            |      Loki Container      | (기존 분석기) |
+   |       |            +----------+---------------+             |
+   |       |                       ^                             |
+   |       | (Scrape HTTP)         | (Query Logs)                |
+   |  +----+-----------------------+-----------------------+     |
+   |  |             Prometheus / Grafana Container         |     |
+   |  |  (baron_net 네트워크 참여 / 수집 및 얼럿 룰 감시)    |     |
+   |  +----------------------------+-----------------------+     |
+   |                               | (Alert Webhook)             |
+   |                               v                             |
+   |  +----------------------------+-----------------------+     |
+   |  |                  grafana-sms-webhook               |     |
+   |  |            (사내 SMS API 게이트웨이 연동)            |     |
+   |  +----------------------------+-----------------------+     |
+   +-------------------------------|-----------------------------+
+                                   |
+                                   | (NCP SENS Call)
+                                   v
+                           [ Naver Cloud NCP ]
+                                   |
+                                   | (SMS/LMS)
+                                   v
+                        [ Infra Administrator ]
+```
+
+---
+
+## 3. 스테이징 배포 파일 반영 사양 (Staging Deployment Changes)
+
+### 3.1 `docker-compose.staging.template.yaml` 변경 사항
+`grafana-sms-webhook`과 로그 수집기인 `promtail` 컨테이너를 함께 기동하도록 추가합니다.
+
+```yaml
+# docker/docker-compose.staging.template.yaml 하단에 추가
+
+services:
+  # ... 기존 backend, adminfront, userfront 등 서비스 정의 ...
+
+  grafana-sms-webhook:
+    # 저장소 주소: https://gitea.hmac.kr/ai-team/grafana-sms-webhook
+    image: ${SMS_WEBHOOK_IMAGE_NAME:-ai-team/grafana-sms-webhook}:${IMAGE_TAG:-latest}
+    container_name: grafana_sms_webhook
+    restart: unless-stopped
+    env_file:
+      - .env
+    environment:
+      - NAVER_CLOUD_ACCESS_KEY=${NAVER_CLOUD_ACCESS_KEY}
+      - NAVER_CLOUD_SECRET_KEY=${NAVER_CLOUD_SECRET_KEY}
+      - NAVER_CLOUD_SERVICE_ID=${NAVER_CLOUD_SERVICE_ID}
+      - NAVER_SENDER_PHONE_NUMBER=${NAVER_SENDER_PHONE_NUMBER}
+      - MONITOR_RECIPIENT_PHONES=${MONITOR_RECIPIENT_PHONES} # 콤마(,) 구분 수신처 번호
+    ports:
+      - "${SMS_WEBHOOK_PORT:-8080}:8080"
+    networks:
+      - baron_net
+
+  promtail:
+    image: grafana/promtail:2.9.0
+    container_name: baron_promtail
+    restart: unless-stopped
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock:ro
+      - /var/lib/docker/containers:/var/lib/docker/containers:ro
+      - ./promtail-config.staging.template.yaml:/etc/promtail/promtail-config.yaml:ro
+    command: -config.file=/etc/promtail/promtail-config.yaml
+    environment:
+      - LOKI_URL=${LOKI_URL:-http://loki:3100/loki/api/v1/push}
+    networks:
+      - baron_net
+
+networks:
+  baron_net:
+    external: true
+    name: baron_net
+```
+
+### 3.2 `promtail-config.staging.template.yaml` 설정 사양
+수집기가 도커 소켓을 읽어 컨테이너명을 자동으로 식별하고, Baron SSO 관련 로그만 선별하여 라벨을 붙인 후 Loki로 전송합니다.
+
+```yaml
+# docker/promtail-config.staging.template.yaml
+
+server:
+  http_listen_port: 9080
+  grpc_listen_port: 0
+
+positions:
+  filename: /tmp/positions.yaml
+
+clients:
+  - url: ${LOKI_URL:-http://loki:3100/loki/api/v1/push}
+
+scrape_configs:
+  - job_name: baron-sso-container-logs
+    docker_sd_configs:
+      - host: unix:///var/run/docker.sock
+        refresh_interval: 10s
+    relabel_configs:
+      - source_labels: ['__meta_docker_container_name']
+        regex: '/(.*)'
+        target_label: 'container_name'
+      # Baron SSO 및 핵심 Ory Stack 컨테이너만 필터링하여 로그 수집
+      - source_labels: ['container_name']
+        regex: '(baron_.*|oathkeeper|kratos|hydra|keto)'
+        action: keep
+      # 컨테이너 명에서 앞의 접두사를 떼어 서비스 및 잡 라벨 부여 (예: baron_backend -> backend)
+      - source_labels: ['container_name']
+        regex: 'baron_(.*)'
+        target_label: 'service'
+      - source_labels: ['container_name']
+        regex: 'baron_(.*)'
+        target_label: 'job'
+      # 정적 라벨 추가
+      - target_label: 'app_env'
+        replacement: 'stage'
+```
+
+---
+
+## 4. 기존 Prometheus & Loki 연동 가이드
+
+### 4.1 1단계: 기존 컨테이너를 `baron_net`에 합류
+기존에 동작 중인 Prometheus, Loki, Grafana 컨테이너가 `baron_net` 내부 도커 DNS를 인식할 수 있도록 연결합니다.
+```bash
+docker network connect baron_net prometheus
+docker network connect baron_net loki
+docker network connect baron_net grafana
+```
+
+### 4.2 2단계: Prometheus 수집 설정 (`prometheus.yml`)
+```yaml
+scrape_configs:
+  - job_name: 'baron-sso-backend-staging'
+    metrics_path: '/health'
+    scrape_interval: 15s
+    static_configs:
+      - targets: ['baron_backend:3000']
+```
+
+---
+
+## 5. Grafana 이중 알림 설정 (메트릭 알림 + 로그 알림)
+
+기존 Grafana에서 다음 두 종류의 알림 규칙을 지정하고 수신처로 `grafana_sms_webhook`을 연동합니다.
+
+### 5.1 메트릭 기반 가용성 얼럿 (Prometheus 데이터 소스)
+* **목적**: 백엔드가 완전히 다운되거나 `/health` 가 503 에러를 리턴할 때 문자 발송
+* **쿼리 예시**: `up{job="baron-sso-backend-staging"} == 0`
+* **지속 기간(For)**: `3m`
+* **장애 문자 템플릿**:
+  ```text
+  [Baron SSO 서버 다운 얼럿]
+  대상: baron_backend
+  상태: DOWN (접속 불가)
+  내용: 백엔드 컨테이너가 정상적으로 동작하지 않거나 웹 서버가 중단되었습니다. 즉시 서버 상태를 점검해 주십시오.
+  ```
+
+### 5.2 로그 기반 실시간 에러/패닉 얼럿 (Loki 데이터 소스)
+* **목적**: 서버는 돌고 있으나 내부 로직 상 치명적인 예외(Panic, Error)가 대량 발생하여 실사용자가 오작동을 겪을 때 문자 전송
+* **쿼리 예시 (LogQL)**: `sum(count_over_time({app_env="stage", service="backend"} |= "panic" [5m])) > 0` 또는 `|= "ERROR"`
+* **지속 기간(For)**: `0m` (발생 즉시 신속 문자 발송)
+* **장애 문자 템플릿**:
+  ```text
+  [Baron SSO 로그 에러 경보]
+  대상: baron_backend (Loki 수집 로그)
+  상태: 치명적인 에러/패닉 실시간 감지
+  내용: 백엔드 서비스 콘솔 로그에서 panic 또는 ERROR 키워드가 실시간으로 감지되었습니다. 로그 모니터링 대시보드를 확인하십시오.
+  ```
+
+---
+
+## 6. 기대 효과 및 결론
+
+1. **완벽한 가시성(Full Observability)**: 단순 서버 기동 여부 검사를 넘어, 서버 내부에서 도는 세부 에러나 버그 로그(Panic)까지 완전하게 모니터링 체계에 포착합니다.
+2. **이중 알림으로 완벽 방어**: 네트워크 장비 고장에 의한 접속 실패는 **메트릭 얼럿**으로 잡고, 내부 로직 결함에 의한 기능 오작동은 **로그 얼럿**으로 이중 방어하여 인프라 가용성 99.99%를 보장합니다.
+3. **효율적인 인프라 일원화**: 동일 그라파나 대시보드 내에서 메트릭 시각화와 로그 검색을 동시 처리하며, `grafana-sms-webhook` 통합 채널 하나만으로 모든 장애 문자를 송출합니다.