memento-mcp-server 0.1.0

package/.cursor/rules/performance-monitoring.mdc

@@ -0,0 +1,345 @@
+---
+globs: *performance-monitoring*,*performance-alert*
+description: Memento 프로젝트의 성능 모니터링 및 알림 시스템 개발 규칙입니다. 실시간 성능 추적, 임계값 기반 알림, 자동 복구를 통한 시스템 안정성 보장을 위한 가이드라인을 제공합니다.
+---
+
+# 성능 모니터링 및 알림 시스템 개발 규칙
+
+## 🎯 개요
+
+성능 모니터링 시스템은 Memento MCP Server의 성능을 실시간으로 추적하고, 임계값 기반 알림을 통해 시스템 안정성을 보장합니다. 자동 복구 메커니즘을 통해 문제 발생 시 즉시 대응할 수 있습니다.
+
+## 📁 파일 구조
+
+```
+src/services/
+├── performance-monitor.ts                    # 기본 성능 모니터링
+├── performance-alert-service.ts              # 성능 알림 서비스
+├── performance-monitoring-integration.ts     # 통합 모니터링
+└── test-performance-monitoring.ts            # 테스트 파일
+```
+
+## 🔧 핵심 기능
+
+### 1. 실시간 성능 모니터링
+- **메모리 사용량**: 힙 사용량, RSS, 외부 메모리
+- **CPU 사용률**: 프로세스 CPU 사용률
+- **응답 시간**: 평균/최대 응답 시간
+- **처리량**: 초당 요청 수
+- **에러율**: 에러 발생 비율
+
+### 2. 임계값 기반 알림
+- **경고 알림**: 성능 저하 경고
+- **심각 알림**: 시스템 위험 상태
+- **자동 복구**: 문제 발생 시 자동 대응
+- **알림 관리**: 알림 생성, 해결, 통계
+
+### 3. 성능 최적화
+- **자동 인덱스 생성**: 느린 쿼리 최적화
+- **캐시 정리**: 메모리 사용량 최적화
+- **연결 풀 관리**: 데이터베이스 연결 최적화
+- **가비지 컬렉션**: 메모리 정리
+
+## 🛠️ 개발 가이드라인
+
+### 성능 모니터링 서비스
+```typescript
+interface PerformanceMonitor {
+  // 메트릭 수집
+  collectMetrics(): Promise<PerformanceMetrics>;
+  
+  // 성능 체크
+  checkPerformance(): Promise<PerformanceStatus>;
+  
+  // 메트릭 기록
+  recordMetric(name: string, value: number, tags?: Record<string, string>): void;
+  
+  // 성능 리포트 생성
+  generateReport(timeRange: string): Promise<PerformanceReport>;
+}
+```
+
+### 성능 알림 서비스
+```typescript
+interface PerformanceAlertService {
+  // 알림 생성
+  createAlert(
+    level: AlertLevel,
+    type: AlertType,
+    metric: string,
+    value: number,
+    threshold: number,
+    message: string,
+    context?: Record<string, any>
+  ): PerformanceAlert;
+  
+  // 알림 해결
+  resolveAlert(alertId: string, resolvedBy: string, resolution?: string): PerformanceAlert | null;
+  
+  // 활성 알림 조회
+  getActiveAlerts(): PerformanceAlert[];
+  
+  // 알림 통계
+  getStats(): AlertStats;
+}
+```
+
+### 성능 모니터링 통합
+```typescript
+interface PerformanceMonitoringIntegration {
+  // 실시간 모니터링 시작
+  startRealTimeMonitoring(): void;
+  
+  // 실시간 모니터링 중지
+  stopRealTimeMonitoring(): void;
+  
+  // 성능 체크
+  private checkPerformance(): Promise<void>;
+  
+  // 임계값 확인
+  private checkResponseTime(avgResponseTime: number): void;
+  private checkMemoryUsage(heapUsedMB: number): void;
+  private checkErrorRate(errorRate: number): void;
+  private checkThroughput(throughput: number): void;
+}
+```
+
+## 📊 성능 메트릭
+
+### 기본 메트릭
+```typescript
+interface PerformanceMetrics {
+  memory: {
+    usage: number;        // 메모리 사용량 (MB)
+    heapUsed: number;     // 힙 사용량 (MB)
+    heapTotal: number;    // 힙 총량 (MB)
+    rss: number;          // RSS 메모리 (MB)
+    external: number;     // 외부 메모리 (MB)
+  };
+  
+  cpu: {
+    usage: number;        // CPU 사용률 (%)
+    loadAverage: number[]; // 로드 평균
+  };
+  
+  database: {
+    totalMemories: number;        // 총 메모리 수
+    memoryByType: Record<string, number>; // 타입별 메모리 수
+    averageMemorySize: number;    // 평균 메모리 크기
+    databaseSize: number;         // 데이터베이스 크기
+    queryPerformance: {
+      averageQueryTime: number;   // 평균 쿼리 시간
+      slowQueries: Array<{        // 느린 쿼리
+        query: string;
+        time: number;
+        count: number;
+      }>;
+    };
+  };
+  
+  search: {
+    totalSearches: number;        // 총 검색 수
+    averageSearchTime: number;    // 평균 검색 시간
+    cacheHitRate: number;         // 캐시 히트율
+    embeddingSearchRate: number;  // 임베딩 검색 비율
+  };
+  
+  system: {
+    uptime: number;               // 업타임 (초)
+    cpuUsage: number;             // CPU 사용률
+    loadAverage: number[];        // 로드 평균
+  };
+}
+```
+
+### 알림 임계값
+```typescript
+interface AlertThresholds {
+  responseTime: {
+    warning: number;    // 경고 임계값 (ms)
+    critical: number;   // 심각 임계값 (ms)
+  };
+  memoryUsage: {
+    warning: number;    // 경고 임계값 (MB)
+    critical: number;   // 심각 임계값 (MB)
+  };
+  errorRate: {
+    warning: number;    // 경고 임계값 (%)
+    critical: number;   // 심각 임계값 (%)
+  };
+  throughput: {
+    warning: number;    // 경고 임계값 (ops/sec)
+    critical: number;   // 심각 임계값 (ops/sec)
+  };
+}
+```
+
+## 🚨 알림 시스템
+
+### 알림 레벨
+```typescript
+enum AlertLevel {
+  INFO = 'INFO',         // 정보성 알림
+  WARNING = 'WARNING',   // 경고 알림
+  CRITICAL = 'CRITICAL'  // 심각 알림
+}
+```
+
+### 알림 타입
+```typescript
+enum AlertType {
+  RESPONSE_TIME = 'response_time',    // 응답 시간
+  MEMORY_USAGE = 'memory_usage',      // 메모리 사용량
+  ERROR_RATE = 'error_rate',          // 에러율
+  THROUGHPUT = 'throughput',          // 처리량
+  CUSTOM = 'custom'                   // 사용자 정의
+}
+```
+
+### 알림 생성 예시
+```typescript
+// 응답 시간 알림
+const alert = alertService.createAlert(
+  AlertLevel.WARNING,
+  AlertType.RESPONSE_TIME,
+  '평균 응답시간',
+  150,
+  100,
+  '🟡 응답시간이 임계값을 초과했습니다',
+  { component: 'search_engine', operation: 'search' }
+);
+
+// 메모리 사용량 알림
+const alert = alertService.createAlert(
+  AlertLevel.CRITICAL,
+  AlertType.MEMORY_USAGE,
+  '힙 메모리 사용량',
+  200,
+  150,
+  '🔴 메모리 사용량이 위험 수준입니다',
+  { component: 'memory_manager', operation: 'create_memory' }
+);
+```
+
+## 🔄 자동 복구 시스템
+
+### 복구 전략
+```typescript
+interface RecoveryStrategy {
+  // 메모리 정리
+  cleanupMemory(): Promise<void>;
+  
+  // 캐시 정리
+  clearCache(): Promise<void>;
+  
+  // 데이터베이스 최적화
+  optimizeDatabase(): Promise<void>;
+  
+  // 연결 풀 재시작
+  restartConnectionPool(): Promise<void>;
+}
+```
+
+### 자동 복구 실행
+```typescript
+// 심각한 메모리 사용량 시 자동 복구
+if (heapUsedMB > criticalThreshold) {
+  console.log('🔴 메모리 사용량이 위험 수준입니다. 자동 복구를 시작합니다...');
+  
+  await recoveryStrategy.cleanupMemory();
+  await recoveryStrategy.clearCache();
+  
+  console.log('✅ 자동 복구가 완료되었습니다.');
+}
+```
+
+## 🧪 테스트 가이드라인
+
+### 단위 테스트
+```typescript
+describe('PerformanceMonitor', () => {
+  let monitor: PerformanceMonitor;
+  
+  beforeEach(() => {
+    monitor = new PerformanceMonitor();
+  });
+  
+  it('should collect memory metrics', async () => {
+    const metrics = await monitor.collectMetrics();
+    
+    expect(metrics.memory.heapUsed).toBeGreaterThan(0);
+    expect(metrics.memory.rss).toBeGreaterThan(0);
+  });
+  
+  it('should detect performance issues', async () => {
+    // 성능 저하 시뮬레이션
+    await simulateHighMemoryUsage();
+    
+    const status = await monitor.checkPerformance();
+    expect(status.hasIssues).toBe(true);
+  });
+});
+```
+
+### 통합 테스트
+```typescript
+describe('PerformanceMonitoring Integration', () => {
+  it('should create alerts when thresholds exceeded', async () => {
+    const monitoring = new PerformanceMonitoringIntegration(
+      db,
+      alertService,
+      { enableRealTimeMonitoring: true }
+    );
+    
+    // 임계값 초과 시뮬레이션
+    await simulateHighResponseTime();
+    
+    // 알림 생성 확인
+    const alerts = alertService.getActiveAlerts();
+    expect(alerts.length).toBeGreaterThan(0);
+    expect(alerts[0].type).toBe(AlertType.RESPONSE_TIME);
+  });
+});
+```
+
+## 📈 모니터링 대시보드
+
+### 실시간 메트릭
+- **시스템 상태**: CPU, 메모리, 디스크 사용률
+- **애플리케이션 성능**: 응답 시간, 처리량, 에러율
+- **데이터베이스 성능**: 쿼리 시간, 연결 수, 인덱스 사용률
+- **검색 성능**: 검색 시간, 캐시 히트율, 임베딩 생성률
+
+### 알림 관리
+- **활성 알림**: 현재 발생한 알림 목록
+- **알림 통계**: 알림 발생 빈도, 해결 시간
+- **알림 설정**: 임계값 조정, 알림 채널 설정
+
+## 🚀 배포 고려사항
+
+### 환경 변수
+```bash
+# 성능 모니터링 설정
+PERFORMANCE_MONITORING_ENABLED=true
+PERFORMANCE_MONITORING_INTERVAL=30000
+PERFORMANCE_ALERT_ENABLED=true
+PERFORMANCE_ALERT_WEBHOOK_URL=https://hooks.slack.com/...
+```
+
+### 모니터링 도구
+- **Prometheus**: 메트릭 수집
+- **Grafana**: 대시보드 시각화
+- **AlertManager**: 알림 관리
+- **Jaeger**: 분산 추적
+
+### 성능 최적화
+- **메트릭 샘플링**: 불필요한 메트릭 제거
+- **압축**: 오래된 메트릭 압축 저장
+- **배치 처리**: 여러 메트릭을 한 번에 처리
+
+## 📚 참고 자료
+
+- [Node.js Performance Monitoring](https://nodejs.org/api/perf_hooks.html)
+- [Prometheus Metrics](https://prometheus.io/docs/concepts/metric_types/)
+- [Grafana Dashboards](https://grafana.com/docs/grafana/latest/dashboards/)
+- [Performance Monitoring Best Practices](https://www.datadoghq.com/blog/monitoring-101-alerting/)