memento-mcp-server 0.1.0

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

@@ -0,0 +1,537 @@
+---
+globs: "src/services/performance-alert-service.ts,src/services/performance-monitoring-integration.ts,src/tools/performance-alerts.ts,src/test-performance-alerts.ts"
+description: 성능 알림 시스템 개발 규칙
+---
+
+# 성능 알림 시스템 개발 규칙
+
+## 📋 성능 알림 시스템 개요
+
+### 현재 구현 상태
+- **성능 알림 서비스**: `src/services/performance-alert-service.ts`
+- **성능 모니터링 통합**: `src/services/performance-monitoring-integration.ts`
+- **성능 알림 도구**: `src/tools/performance-alerts.ts`
+- **성능 알림 테스트**: `src/test-performance-alerts.ts`
+
+### 핵심 인터페이스
+
+```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[];
+  
+  // 알림 검색
+  searchAlerts(filters: AlertSearchFilters): PerformanceAlert[];
+  
+  // 알림 통계
+  getStats(): AlertStats;
+}
+
+enum AlertLevel {
+  INFO = 'INFO',
+  WARNING = 'WARNING',
+  CRITICAL = 'CRITICAL'
+}
+
+enum AlertType {
+  RESPONSE_TIME = 'response_time',
+  MEMORY_USAGE = 'memory_usage',
+  ERROR_RATE = 'error_rate',
+  THROUGHPUT = 'throughput',
+  CUSTOM = 'custom'
+}
+```
+
+## 🔧 성능 알림 서비스 구현
+
+### 1. 알림 생성 메서드
+
+```typescript
+export class PerformanceAlertService {
+  private alerts: Map<string, PerformanceAlert> = new Map();
+  private logDirectory: string;
+  private maxAlerts = 1000; // 최대 저장 알림 수
+
+  constructor(logDirectory: string = './logs') {
+    this.logDirectory = logDirectory;
+    if (!existsSync(this.logDirectory)) {
+      mkdirSync(this.logDirectory, { recursive: true });
+    }
+  }
+
+  /**
+   * 성능 알림을 생성하고 로깅합니다.
+   */
+  createAlert(
+    level: AlertLevel,
+    type: AlertType,
+    metric: string,
+    value: number,
+    threshold: number,
+    message: string,
+    context?: Record<string, any>
+  ): PerformanceAlert {
+    const id = uuidv4();
+    const alert: PerformanceAlert = {
+      id,
+      timestamp: new Date(),
+      level,
+      type,
+      metric,
+      value,
+      threshold,
+      message,
+      context,
+      resolved: false,
+    };
+
+    this.alerts.set(id, alert);
+    this.cleanupOldAlerts();
+    this.logToFile(alert);
+    this.logToConsole(alert);
+
+    return alert;
+  }
+}
+```
+
+### 2. 알림 해결 처리
+
+```typescript
+/**
+   * 특정 알림을 해결 상태로 표시합니다.
+   */
+  resolveAlert(alertId: string, resolvedBy: string = 'system', resolution?: string): PerformanceAlert | null {
+    const alert = this.alerts.get(alertId);
+    if (alert) {
+      alert.resolved = true;
+      alert.resolvedAt = new Date();
+      alert.resolvedBy = resolvedBy;
+      alert.resolution = resolution;
+      console.log(`[INFO] 알림 해결됨: ${alertId} by ${resolvedBy}`);
+      this.logToFile(alert); // 해결된 상태로 다시 로깅
+      return alert;
+    }
+    return null;
+  }
+```
+
+### 3. 알림 검색 및 필터링
+
+```typescript
+/**
+   * 필터에 따라 알림을 검색합니다.
+   */
+  searchAlerts(filters: AlertSearchFilters): PerformanceAlert[] {
+    let results = Array.from(this.alerts.values());
+
+    if (filters.level) {
+      results = results.filter(a => a.level === filters.level);
+    }
+    if (filters.type) {
+      results = results.filter(a => a.type === filters.type);
+    }
+    if (filters.resolved !== undefined) {
+      results = results.filter(a => a.resolved === filters.resolved);
+    }
+    if (filters.from) {
+      results = results.filter(a => a.timestamp >= filters.from!);
+    }
+    if (filters.to) {
+      results = results.filter(a => a.timestamp <= filters.to!);
+    }
+
+    results.sort((a, b) => b.timestamp.getTime() - a.timestamp.getTime());
+
+    if (filters.limit) {
+      results = results.slice(0, filters.limit);
+    }
+
+    return results;
+  }
+```
+
+## 🔄 성능 모니터링 통합
+
+### 1. 실시간 모니터링 설정
+
+```typescript
+export class PerformanceMonitoringIntegration {
+  private db: Database.Database;
+  private performanceMonitor: PerformanceMonitor;
+  private performanceAlertService: PerformanceAlertService;
+  private config: MonitoringConfig;
+  private monitoringTimer: NodeJS.Timeout | null = null;
+
+  constructor(
+    db: Database.Database,
+    performanceAlertService: PerformanceAlertService,
+    config: MonitoringConfig
+  ) {
+    this.db = db;
+    this.performanceMonitor = new PerformanceMonitor(db);
+    this.performanceAlertService = performanceAlertService;
+    this.config = config;
+  }
+
+  /**
+   * 실시간 성능 모니터링을 시작합니다.
+   */
+  startRealTimeMonitoring(): void {
+    if (!this.config.enableRealTimeMonitoring) {
+      console.log('실시간 성능 모니터링이 비활성화되어 있습니다.');
+      return;
+    }
+
+    if (this.monitoringTimer) {
+      console.warn('실시간 성능 모니터링이 이미 실행 중입니다.');
+      return;
+    }
+
+    console.log(`실시간 성능 모니터링 시작. 주기: ${this.config.monitoringInterval / 1000}초`);
+    this.monitoringTimer = setInterval(() => this.checkPerformance(), this.config.monitoringInterval);
+  }
+}
+```
+
+### 2. 성능 체크 및 임계값 확인
+
+```typescript
+/**
+   * 현재 성능 지표를 확인하고 알림을 생성합니다.
+   */
+private async checkPerformance(): Promise<void> {
+  try {
+    // 1. 시스템 메트릭 수집
+    const systemMetrics = this.performanceMonitor.getSystemMetrics();
+    const dbMetrics = DatabaseUtils.getDatabaseStatus(this.db);
+
+    // 2. 성능 통계 가져오기
+    const overallStats = this.performanceMonitor.getOverallStats();
+    const queryStats = this.performanceMonitor.getQueryStats();
+    const searchStats = this.performanceMonitor.getSearchStats();
+
+    // 3. 알림 임계값 확인 및 알림 생성
+    this.checkResponseTime(overallStats.avgResponseTime);
+    this.checkMemoryUsage(systemMetrics.heapUsedMB);
+    this.checkErrorRate(overallStats.errorRate);
+    this.checkThroughput(overallStats.throughput);
+
+    // 4. 데이터베이스 관련 알림
+    if (dbMetrics.isLocked) {
+      this.performanceAlertService.createAlert(
+        AlertLevel.CRITICAL,
+        AlertType.CUSTOM,
+        'Database Lock',
+        1,
+        0,
+        '🔴 데이터베이스 잠금 감지! 심각한 성능 저하가 예상됩니다.',
+        { dbStatus: dbMetrics }
+      );
+    }
+  } catch (error) {
+    console.error('❌ 성능 모니터링 중 오류 발생:', error);
+    this.performanceAlertService.createAlert(
+      AlertLevel.CRITICAL,
+      AlertType.CUSTOM,
+      'Monitoring Error',
+      1,
+      0,
+      `❌ 성능 모니터링 시스템 자체 오류: ${(error as Error).message}`,
+      { error: (error as Error).stack }
+    );
+  }
+}
+```
+
+### 3. 임계값 확인 메서드들
+
+```typescript
+private checkResponseTime(avgResponseTime: number): void {
+  const { warning, critical } = this.config.alertThresholds.responseTime;
+  if (avgResponseTime >= critical) {
+    this.performanceAlertService.createAlert(
+      AlertLevel.CRITICAL,
+      AlertType.RESPONSE_TIME,
+      '평균 응답시간',
+      avgResponseTime,
+      critical,
+      `🔴 평균 응답시간이 심각한 임계값(${critical}ms)을 초과했습니다: ${avgResponseTime.toFixed(2)}ms`,
+      { avgResponseTime }
+    );
+  } else if (avgResponseTime >= warning) {
+    this.performanceAlertService.createAlert(
+      AlertLevel.WARNING,
+      AlertType.RESPONSE_TIME,
+      '평균 응답시간',
+      avgResponseTime,
+      warning,
+      `🟡 평균 응답시간이 임계값(${warning}ms)을 초과했습니다: ${avgResponseTime.toFixed(2)}ms`,
+      { avgResponseTime }
+    );
+  }
+}
+
+private checkMemoryUsage(heapUsedMB: number): void {
+  const { warning, critical } = this.config.alertThresholds.memoryUsage;
+  if (heapUsedMB >= critical) {
+    this.performanceAlertService.createAlert(
+      AlertLevel.CRITICAL,
+      AlertType.MEMORY_USAGE,
+      '메모리 사용량',
+      heapUsedMB,
+      critical,
+      `🔴 메모리 사용량이 심각한 임계값(${critical}MB)을 초과했습니다: ${heapUsedMB.toFixed(2)}MB`,
+      { heapUsedMB }
+    );
+  } else if (heapUsedMB >= warning) {
+    this.performanceAlertService.createAlert(
+      AlertLevel.WARNING,
+      AlertType.MEMORY_USAGE,
+      '메모리 사용량',
+      heapUsedMB,
+      warning,
+      `🟡 메모리 사용량이 임계값(${warning}MB)을 초과했습니다: ${heapUsedMB.toFixed(2)}MB`,
+      { heapUsedMB }
+    );
+  }
+}
+```
+
+## 🛠️ MCP 도구 구현
+
+### 1. performance_alerts 도구
+
+```typescript
+export const performanceAlertsTool: ToolDefinition = {
+  name: 'performance_alerts',
+  description: '실시간 성능 알림을 조회, 검색 및 관리합니다.',
+  inputSchema: z.object({
+    action: z.enum(['stats', 'list', 'search', 'resolve']).describe('수행할 작업'),
+    alertId: z.string().optional().describe('해결할 알림의 고유 ID (action이 "resolve"일 때 필수)'),
+    resolvedBy: z.string().optional().describe('알림을 해결한 주체'),
+    resolution: z.string().optional().describe('알림 해결에 대한 설명'),
+    level: z.nativeEnum(AlertLevel).optional().describe('조회할 알림의 심각도'),
+    type: z.nativeEnum(AlertType).optional().describe('조회할 알림의 유형'),
+    includeResolved: z.boolean().optional().default(false).describe('해결된 알림을 포함할지 여부'),
+    hours: z.number().min(1).optional().describe('지난 몇 시간 동안의 알림을 조회할지 지정'),
+    limit: z.number().min(1).max(100).optional().default(10).describe('반환할 알림 로그의 최대 개수'),
+  }),
+  handler: async (params: z.infer<typeof performanceAlertsTool.inputSchema>, context: ToolContext) => {
+    return executePerformanceAlerts(params, context);
+  },
+};
+```
+
+### 2. 도구 핸들러 구현
+
+```typescript
+export async function executePerformanceAlerts(
+  params: z.infer<typeof performanceAlertsTool.inputSchema>,
+  context: ToolContext
+) {
+  if (!context.services?.performanceAlertService) {
+    throw new Error('PerformanceAlertService가 초기화되지 않았습니다.');
+  }
+
+  const { action, alertId, resolvedBy, resolution, level, type, includeResolved, hours, limit } = params;
+
+  switch (action) {
+    case 'stats':
+      return handleStats(context);
+    case 'list':
+      return handleList(context, includeResolved, limit);
+    case 'search':
+      return handleSearch(context, { level, type, includeResolved, hours, limit });
+    case 'resolve':
+      if (!alertId) throw new Error('알림을 해결하려면 alertId가 필요합니다.');
+      return handleResolve(context, alertId, resolvedBy, resolution);
+    default:
+      throw new Error(`알 수 없는 작업: ${action}`);
+  }
+}
+```
+
+## 📊 로깅 및 모니터링
+
+### 1. 파일 로깅
+
+```typescript
+private logToFile(alert: PerformanceAlert): void {
+  const date = alert.timestamp.toISOString().split('T')[0];
+  const logFilePath = join(this.logDirectory, `performance-alerts-${date}.jsonl`);
+  appendFileSync(logFilePath, JSON.stringify(alert) + '\n');
+}
+```
+
+### 2. 콘솔 로깅
+
+```typescript
+private logToConsole(alert: PerformanceAlert): void {
+  let color = '';
+  switch (alert.level) {
+    case AlertLevel.INFO:
+      color = '\x1b[34m'; // Blue
+      break;
+    case AlertLevel.WARNING:
+      color = '\x1b[33m'; // Yellow
+      break;
+    case AlertLevel.CRITICAL:
+      color = '\x1b[31m'; // Red
+      break;
+  }
+  const resetColor = '\x1b[0m';
+  console.warn(`${color}[${alert.level}] ${alert.metric}${resetColor}\n  ID: ${alert.id}\n  Time: ${alert.timestamp.toISOString()}\n  Value: ${alert.value} (Threshold: ${alert.threshold})\n  Message: ${alert.message}\n  Context: ${JSON.stringify(alert.context, null, 2)}\n`);
+}
+```
+
+### 3. 오래된 알림 정리
+
+```typescript
+private cleanupOldAlerts(): void {
+  if (this.alerts.size > this.maxAlerts) {
+    const sortedAlerts = Array.from(this.alerts.values())
+      .sort((a, b) => a.timestamp.getTime() - b.timestamp.getTime());
+    
+    for (let i = 0; i < this.alerts.size - this.maxAlerts; i++) {
+      this.alerts.delete(sortedAlerts[i].id);
+    }
+  }
+}
+```
+
+## 🧪 테스트 작성
+
+### 1. 성능 알림 테스트
+
+```typescript
+// src/test-performance-alerts.ts
+import { MementoClient } from './client/index.js';
+import { AlertLevel, AlertType } from './services/performance-alert-service.js';
+
+async function runPerformanceAlertsTest() {
+  console.log('🚀 성능 알림 시스템 테스트 시작');
+  const client = new MementoClient();
+
+  try {
+    await client.connect({
+      transport: {
+        type: 'websocket',
+        url: 'ws://localhost:8080/mcp'
+      }
+    });
+
+    // 1. 초기 알림 통계 조회
+    console.log('\n📊 초기 알림 통계:');
+    const initialStats = await client.callTool('performance_alerts', { action: 'stats' });
+    console.log(JSON.stringify(initialStats, null, 2));
+
+    // 2. 활성 알림 목록 조회
+    console.log('\n🚨 활성 알림 목록:');
+    const activeAlerts = await client.callTool('performance_alerts', { action: 'list' });
+    console.log(JSON.stringify(activeAlerts, null, 2));
+
+    // 3. 알림 해결 테스트
+    if (activeAlerts.activeAlerts && activeAlerts.activeAlerts.length > 0) {
+      const alertToResolve = activeAlerts.activeAlerts[0];
+      console.log(`\n🛠️ 알림 해결 테스트: ${alertToResolve.id}`);
+      const resolveResult = await client.callTool('performance_alerts', {
+        action: 'resolve',
+        alertId: alertToResolve.id,
+        resolvedBy: 'test_script',
+        resolution: '테스트 스크립트에 의해 해결됨'
+      });
+      console.log(JSON.stringify(resolveResult, null, 2));
+    }
+
+  } catch (error) {
+    console.error('❌ 성능 알림 테스트 중 오류 발생:', error);
+  } finally {
+    await client.disconnect();
+    console.log('🎉 성능 알림 시스템 테스트 완료');
+  }
+}
+```
+
+### 2. 간단한 알림 테스트
+
+```typescript
+// src/test-simple-alerts.ts
+import { PerformanceAlertService, AlertLevel, AlertType } from './services/performance-alert-service.js';
+
+async function testSimpleAlerts() {
+  console.log('🚨 간단한 성능 알림 테스트 시작');
+
+  const alertService = new PerformanceAlertService('./logs');
+
+  // 1. 다양한 레벨의 알림 생성
+  const alert1 = alertService.createAlert(
+    AlertLevel.WARNING,
+    AlertType.RESPONSE_TIME,
+    '응답시간',
+    150,
+    100,
+    '🟡 응답시간 초과 임계값: 150 > 100',
+    { component: 'search_engine', operation: 'search' }
+  );
+
+  const alert2 = alertService.createAlert(
+    AlertLevel.CRITICAL,
+    AlertType.MEMORY_USAGE,
+    '메모리 사용량',
+    200,
+    150,
+    '🔴 메모리 사용량 심각한 초과: 200 > 150',
+    { component: 'memory_manager', heapTotal: 300 }
+  );
+
+  // 2. 알림 통계 조회
+  const stats = alertService.getStats();
+  console.log('📈 알림 통계:', stats);
+
+  // 3. 알림 해결 테스트
+  const resolved = alertService.resolveAlert(alert1.id, 'test_user', '테스트 해결');
+  console.log('✅ 알림 해결:', resolved);
+}
+```
+
+## 📋 개발 체크리스트
+
+### 성능 알림 서비스
+- [ ] PerformanceAlertService 클래스 구현
+- [ ] 알림 레벨 및 유형 분류
+- [ ] 알림 생성 및 관리
+- [ ] 알림 해결 추적 시스템
+- [ ] 파일 및 콘솔 로깅
+- [ ] 오래된 알림 자동 정리
+
+### 성능 모니터링 통합
+- [ ] PerformanceMonitoringIntegration 클래스 구현
+- [ ] 실시간 모니터링 설정
+- [ ] 임계값 기반 알림 생성
+- [ ] 성능 메트릭 수집
+- [ ] 자동 복구 작업
+
+### MCP 도구
+- [ ] performance_alerts 도구 구현
+- [ ] 도구 등록 및 통합
+- [ ] 에러 처리 및 검증
+- [ ] 다양한 액션 지원
+
+### 테스트
+- [ ] 성능 알림 테스트 스크립트
+- [ ] 간단한 알림 테스트
+- [ ] 통합 테스트 구현
+- [ ] 실시간 모니터링 테스트
+
+### 모니터링
+- [ ] 실시간 성능 모니터링
+- [ ] 임계값 설정 및 관리
+- [ ] 알림 패턴 분석
+- [ ] 대시보드 통합