feat(phase-5-3): Logger, Metrics, 알림 시스템 통합
Phase 5-3 모니터링 강화 작업의 통합을 완료했습니다. 변경사항: - Logger 통합: console.log를 구조화된 로깅으로 전환 (9개 파일) - JSON 기반 로그, 환경별 자동 전환 (개발/프로덕션) - 타입 안전성 보장, 성능 측정 타이머 내장 - Metrics 통합: 실시간 성능 모니터링 시스템 연결 (3개 파일) - Circuit Breaker 상태 추적 (api_call_count, error_count, state) - Retry 재시도 횟수 추적 (retry_count) - OpenAI API 응답 시간 측정 (api_call_duration) - 알림 통합: 장애 자동 알림 시스템 구현 (2개 파일) - Circuit Breaker OPEN 상태 → 관리자 Telegram 알림 - 재시도 실패 → 관리자 Telegram 알림 - Rate Limiting 적용 (1시간에 1회) - 문서 업데이트: - CLAUDE.md: coder 에이전트 설명 강화 (20년+ 시니어 전문가) - README.md, docs/: 아키텍처 문서 추가 영향받은 파일: 16개 (수정 14개, 신규 2개) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
70
CLAUDE.md
70
CLAUDE.md
@@ -28,7 +28,12 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
|
||||
- 주요 디렉토리: `src/tools/`, `src/routes/`, `src/services/`
|
||||
|
||||
**사용 가능한 에이전트 타입:**
|
||||
- `general-purpose`: 범용 작업, 코드 작성/수정
|
||||
- `coder`: 20년 이상의 경험을 갖고 있는 시니어 코딩 전문가 (코드 작성/수정 최우선)
|
||||
- TypeScript/Cloudflare Workers 구현 마스터
|
||||
- 프로덕션 수준의 코드 품질 보장
|
||||
- 엔터프라이즈급 에러 핸들링 및 타입 안정성
|
||||
- 성능 최적화 및 베스트 프랙티스 적용
|
||||
- `general-purpose`: 범용 작업 (coder 사용 불가 시 폴백)
|
||||
- `Explore`: 프로젝트 구조 분석 (thorough 레벨)
|
||||
- `Bash`: 빌드/배포/테스트 실행
|
||||
|
||||
@@ -36,12 +41,12 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
|
||||
|
||||
| 작업 유형 | 조건 | 에이전트 타입 | 이유 |
|
||||
|-----------|------|---------------|------|
|
||||
| **코드 작성/수정** | 모든 코드 변경 | `general-purpose` | 컨텍스트 절약, 독립 실행 |
|
||||
| **리팩토링** | 파일 수 무관 | `general-purpose` (병렬) | 일관성, 컨텍스트 분리 |
|
||||
| **Function Calling 도구** | 추가/수정 | `general-purpose` (병렬) | tools/ + openai-service.ts 동시 처리 |
|
||||
| **스키마 작업** | D1 마이그레이션 | `general-purpose` | 백업→마이그레이션→검증 전체 위임 |
|
||||
| **코드 작성/수정** | 모든 코드 변경 | `coder` | TS/Workers 전문, 타입 안정성, 프로덕션 품질 |
|
||||
| **리팩토링** | 파일 수 무관 | `coder` (병렬) | 일관성, 컨텍스트 분리, TS 최적화 |
|
||||
| **Function Calling 도구** | 추가/수정 | `coder` (병렬) | tools/ + openai-service.ts 동시 처리 |
|
||||
| **스키마 작업** | D1 마이그레이션 | `coder` | 백업→마이그레이션→검증 전체 위임 |
|
||||
| **프로젝트 분석** | 구조 파악 | `Explore` (thorough) | 대량 파일 읽기 분리 |
|
||||
| **코드 리뷰** | 보안/성능 | `Explore` + `general-purpose` | 분석 후 개선 제안 |
|
||||
| **코드 리뷰** | 보안/성능 | `Explore` + `coder` | 분석 후 개선 제안 |
|
||||
| **빌드/배포** | npm run, wrangler | `Bash` | 긴 로그 출력 분리 |
|
||||
| **테스트** | 로컬 테스트 실행 | `Bash` | 테스트 출력 분리 |
|
||||
|
||||
@@ -52,8 +57,8 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
|
||||
- ✅ 메인 세션은 조율/지시만 담당
|
||||
|
||||
**병렬 처리 필수:**
|
||||
- 독립적인 파일 여러 개 → 병렬 general-purpose 에이전트
|
||||
- 다른 디렉토리 동시 작업 → 병렬 general-purpose 에이전트
|
||||
- 독립적인 파일 여러 개 → 병렬 `coder` 에이전트
|
||||
- 다른 디렉토리 동시 작업 → 병렬 `coder` 에이전트
|
||||
- Function Calling 도구 추가 → tools/{new}.ts + openai-service.ts 병렬
|
||||
|
||||
**예시:**
|
||||
@@ -64,9 +69,10 @@ Edit src/tools/weather-tool.ts
|
||||
Read src/openai-service.ts
|
||||
Edit src/openai-service.ts
|
||||
|
||||
// ✅ 에이전트 사용 (컨텍스트 절약)
|
||||
Task (subagent_type: "general-purpose", 2개 병렬)
|
||||
// ✅ coder 에이전트 사용 (컨텍스트 절약 + 전문성)
|
||||
Task (subagent_type: "coder", 2개 병렬)
|
||||
→ 독립 컨텍스트에서 작업 → 요약만 반환
|
||||
→ TypeScript 최적화, Workers 패턴 준수
|
||||
```
|
||||
|
||||
**직접 처리 (최소화):**
|
||||
@@ -176,20 +182,35 @@ curl https://telegram-summary-bot.kappa-d8e.workers.dev/webhook-info
|
||||
|
||||
### 에러 핸들링
|
||||
```typescript
|
||||
// 패턴: try-catch + 사용자 친화적 메시지
|
||||
// 패턴: try-catch + 사용자 친화적 메시지 + 구조화된 로깅
|
||||
import { createLogger } from './utils/logger';
|
||||
const logger = createLogger('service-name');
|
||||
|
||||
try {
|
||||
// 작업
|
||||
} catch (error) {
|
||||
console.error('[ServiceName] 작업 실패:', error);
|
||||
logger.error('작업 실패', error as Error, { context: 'data' });
|
||||
return '죄송합니다. 일시적인 오류가 발생했습니다.';
|
||||
}
|
||||
```
|
||||
|
||||
### 로깅 규칙
|
||||
```typescript
|
||||
console.log('[ServiceName] 동작 설명'); // 정상 동작
|
||||
console.error('[ServiceName] 에러 설명:', error); // 에러
|
||||
// 구조화된 로깅 (Phase 5-3에서 도입)
|
||||
import { createLogger } from './utils/logger';
|
||||
const logger = createLogger('service-name');
|
||||
|
||||
logger.info('동작 설명', { key: 'value' }); // 정상 동작
|
||||
logger.error('에러 설명', error as Error); // 에러
|
||||
logger.warn('경고 메시지', { context: 'data' }); // 경고
|
||||
|
||||
// 성능 측정
|
||||
const end = logger.startTimer('작업 완료');
|
||||
await doWork();
|
||||
end(); // duration 자동 기록
|
||||
|
||||
// wrangler tail로 확인 가능
|
||||
// 프로덕션: JSON 형식, 개발: 읽기 쉬운 형식 자동 전환
|
||||
```
|
||||
|
||||
### 네이밍
|
||||
@@ -431,6 +452,27 @@ Telegram Webhook → Security Validation → Command/Message Router
|
||||
| `commands.ts` | 봇 명령어 | `handleCommand()` |
|
||||
| `telegram.ts` | Telegram API | `sendMessage()`, `sendTypingAction()` |
|
||||
|
||||
**Logging & Monitoring (Phase 5-3):**
|
||||
| 파일 | 역할 | 주요 기능 |
|
||||
|------|------|----------|
|
||||
| `utils/logger.ts` | 구조화된 로깅 | JSON 기반 로그, 환경별 전환 (개발/프로덕션) |
|
||||
| `utils/metrics.ts` | 성능 메트릭 수집 | API 호출 시간, 에러율, Circuit Breaker 상태 |
|
||||
| `utils/circuit-breaker.ts` | Circuit Breaker | OpenAI API 보호, 자동 복구 |
|
||||
| `utils/retry.ts` | 재시도 로직 | 지수 백오프, 15개 API 지원 |
|
||||
|
||||
**Logger 사용 예시:**
|
||||
```typescript
|
||||
import { createLogger } from './utils/logger';
|
||||
const logger = createLogger('openai');
|
||||
|
||||
logger.info('AI 응답 생성', { model: 'gpt-4o-mini' });
|
||||
logger.error('API 호출 실패', error as Error, { retryCount: 3 });
|
||||
|
||||
const end = logger.startTimer('처리 완료');
|
||||
await process();
|
||||
end(); // duration 자동 기록
|
||||
```
|
||||
|
||||
**Function Calling Tools (8개):**
|
||||
| 도구 | 함수명 | 외부 API | 트리거 키워드 |
|
||||
|------|--------|----------|---------------|
|
||||
|
||||
Reference in New Issue
Block a user