Grafana Monitoring

macOS 메뉴바 앱으로 Grafana Cloud(Mimir/Loki/Tempo)를 통해 서비스 상태를 실시간 모니터링합니다.

주요 기능

• 메뉴바 상주 — 서비스 헬스 상태를 한눈에 확인
• Prometheus/Mimir — CPU, 메모리, P99 레이턴시, RPS, 에러율 메트릭 조회
• Loki — 서비스 로그 조회
• Tempo — 에러 트레이스 조회 (HTTP 5xx)
• 알림 — 헬스 상태 변화 시 macOS 네이티브 알림
• 설정 가능 — 모니터링 대상 서비스, 폴링 주기, 알림 임계값 커스터마이즈

기술 스택

항목	내용
언어	Swift 5.9+, SwiftUI
최소 OS	macOS 14 (Sonoma)
빌드	Swift Package Manager
아키텍처	Actor 기반 GrafanaClient, @Observable 상태 관리

프로젝트 구조

GrafanaMonitoring/
├── Package.swift
├── bundle.sh                       # 빌드 + .app 번들 생성 + 코드사인
└── Sources/
    ├── App/
    │   ├── GrafanaMonitoringApp.swift   # 앱 진입점
    │   └── AppDelegate.swift        # NSStatusItem, 메뉴바 아이콘
    ├── Models/
    │   ├── Service.swift            # MonitoredService, ServiceHealth
    │   ├── MetricsData.swift        # 메트릭 데이터 모델
    │   └── AlertThreshold.swift     # 알림 임계값
    ├── Services/
    │   ├── GrafanaClient.swift      # Prometheus/Loki/Tempo API 클라이언트
    │   ├── MetricsPoller.swift      # 주기적 메트릭 폴링
    │   ├── NotificationManager.swift # macOS 알림
    │   └── KeychainHelper.swift     # API 토큰 보관
    ├── Views/
    │   ├── MenuBarView.swift        # 메인 팝오버
    │   ├── ServiceRowView.swift     # 서비스 행 (확장 가능)
    │   ├── ServiceDetailView.swift  # 메트릭 + 로그 + 트레이스
    │   └── SettingsView.swift       # 설정 화면
    └── Utils/
        └── Settings.swift           # UserDefaults 기반 설정

빌드 및 실행

cd GrafanaMonitoring
bash bundle.sh
open GrafanaMonitoring.app

swift run은 앱 번들이 생성되지 않아 알림 권한 등에서 크래시가 발생합니다. 반드시 bundle.sh를 사용하세요.

bundle.sh는 다음을 수행합니다:

1. swift build로 빌드
2. .app 번들 + Info.plist 생성
3. Ad-hoc 코드사인 (알림 권한에 필요)

설정

앱 실행 후 Settings에서 다음을 설정합니다:

• Grafana Cloud API Token — glc_ 접두사의 Cloud Access Policy 토큰
• 모니터링 대상 서비스 — 비워두면 전체 서비스 모니터링
• 폴링 주기 — 메트릭 조회 간격
• 알림 임계값 — CPU, 메모리, 에러율 등의 경고/위험 기준값

Grafana Cloud 엔드포인트

서비스	엔드포인트
Prometheus/Mimir	prometheus-prod-49-prod-ap-northeast-0.grafana.net
Loki	logs-prod-030.grafana.net
Tempo	tempo-prod-20-prod-ap-northeast-0.grafana.net

각 서비스별로 별도의 User ID를 사용하며, Basic Auth로 인증합니다.

모니터링 메트릭

• CPU — ECS 태스크 평균 CPU 사용률
• 메모리 — ECS 태스크 메모리 사용률 (사용량/예약량 %)
• P99 레이턴시 — HTTP 요청 99th percentile 응답 시간
• 에러율 — HTTP 5xx 응답 비율
• RPS — 초당 요청 수

라이선스

Private