zellyy-finance/docs/sentry-setup.md

# Sentry.io 설정 가이드

## 1. Sentry 계정 생성

1. [Sentry.io](https://sentry.io)에서 무료 계정 생성
2. "Create Project" 클릭
3. Platform: **React** 선택
4. 프로젝트명: `zellyy-finance`
5. 팀/조직 설정 (개인 계정 사용 가능)

## 2. DSN 및 설정 정보 획득

### DSN (Data Source Name) 가져오기
1. 프로젝트 생성 후 자동으로 표시되는 DSN 복사
2. 또는 `Settings > Projects > [프로젝트명] > Client Keys (DSN)` 에서 확인
3. 형식: `https://[키]@[지역].ingest.sentry.io/[프로젝트ID]`

### Auth Token 생성 (소스맵 업로드용)
1. `Settings > Auth Tokens` 메뉴 이동
2. "Create New Token" 클릭
3. 권한 설정:
   - `project:read`
   - `project:write` 
   - `org:read`
4. 토큰 이름: `zellyy-finance-sourcemaps`
5. 생성된 토큰을 안전하게 보관

### 조직 및 프로젝트 정보 확인
1. `Settings > General Settings`에서 조직명 확인
2. `Settings > Projects`에서 프로젝트명 확인

## 3. 환경 변수 설정

### 개발환경 (.env)
```env
# Sentry 모니터링 설정
VITE_SENTRY_DSN=https://your_actual_dsn@sentry.io/123456
VITE_SENTRY_ENVIRONMENT=development

# Sentry 빌드 관련
SENTRY_ORG=your_organization_name
SENTRY_PROJECT=zellyy-finance
SENTRY_RELEASE=zellyy-finance@1.0.0
SENTRY_DISABLE_SOURCEMAPS=true
```

### 프로덕션 환경 (Vercel, Netlify 등)
```env
# Sentry 모니터링 설정
VITE_SENTRY_DSN=https://your_actual_dsn@sentry.io/123456
VITE_SENTRY_ENVIRONMENT=production

# Sentry 빌드 관련 (소스맵 업로드용)
SENTRY_ORG=your_organization_name
SENTRY_PROJECT=zellyy-finance
SENTRY_AUTH_TOKEN=your_auth_token_here
SENTRY_RELEASE=zellyy-finance@1.0.0
SENTRY_DISABLE_SOURCEMAPS=false
```

## 4. 소스맵 업로드 테스트

### 로컬에서 프로덕션 빌드 테스트
```bash
# 소스맵과 함께 프로덕션 빌드
npm run build:sentry

# 빌드 후 dist 폴더 확인
ls -la dist/
# *.js.map 파일들이 생성되었다가 Sentry 업로드 후 삭제되는지 확인
```

### 배포 환경에서 소스맵 확인
1. Sentry 대시보드에서 `Releases` 메뉴 이동
2. 최신 릴리즈 클릭
3. `Artifacts` 탭에서 업로드된 소스맵 파일 확인

## 5. 에러 추적 테스트

### 개발환경에서 테스트
1. 브라우저에서 `F12` 개발자 도구 열기
2. Console에서 Sentry 테스트 버튼 클릭
3. Sentry 대시보드에서 `Issues` 메뉴에서 테스트 에러 확인

### 프로덕션 에러 테스트
```javascript
// 의도적으로 에러 발생시키기
throw new Error("프로덕션 테스트 에러");
```

## 6. 성능 모니터링 설정

### Core Web Vitals 확인
1. Sentry 대시보드에서 `Performance` 메뉴 이동
2. `Web Vitals` 탭에서 LCP, FID, CLS 지표 확인
3. 페이지별 성능 분석

### 커스텀 트랜잭션 추적
```typescript
import { trackEvent, measurePerformance } from '@/lib/sentry';

// 사용자 행동 추적
trackEvent('transaction_created', { amount: 1000, category: 'food' });

// 성능 측정
const startTime = performance.now();
await expensiveOperation();
measurePerformance('expensive_operation', startTime);
```

## 7. 알림 설정

### 이메일 알림 설정
1. `Settings > Notifications` 메뉴 이동
2. `Email` 탭에서 알림 규칙 설정:
   - 새로운 이슈 발생 시 즉시 알림
   - 이슈 재발생 시 알림
   - 성능 저하 감지 시 알림

### Slack 통합 (선택사항)
1. `Settings > Integrations` 메뉴 이동
2. Slack 통합 설정
3. 알림받을 채널 설정

## 8. 릴리즈 추적

### 자동 릴리즈 추적
```bash
# 빌드 시 자동으로 릴리즈 생성 및 배포 기록
npm run build:prod
npm run deploy
```

### 수동 릴리즈 관리
```bash
# 새 릴리즈 생성
npm run sentry:release

# 배포 기록
npm run sentry:deploy
```

## 9. 보안 고려사항

### 민감한 정보 필터링
- 이미 `src/lib/sentry.ts`에서 설정됨:
  - 비밀번호, 토큰 포함 에러 메시지 필터링
  - 로컬호스트 에러 필터링
  - 세션 재생에서 텍스트 마스킹

### 소스맵 보안
- 프로덕션 빌드 후 로컬 소스맵 파일 자동 삭제
- Sentry에만 저장되어 에러 디버깅 시 활용

## 10. 문제 해결

### 소스맵 업로드 실패
```bash
# Sentry CLI 설치 및 직접 업로드 테스트
npm install -g @sentry/cli
sentry-cli releases files $SENTRY_RELEASE upload-sourcemaps ./dist
```

### 에러 추적이 안 될 때
1. DSN이 올바르게 설정되었는지 확인
2. 네트워크 방화벽/브라우저 확장 프로그램 확인
3. 개발자 도구 Network 탭에서 Sentry 요청 확인

### 성능 데이터가 수집되지 않을 때
- `tracesSampleRate`가 0보다 큰지 확인
- 프로덕션 환경에서는 샘플링 비율이 낮을 수 있음 (0.1 = 10%)

## 11. 비용 최적화

### 무료 플랜 한도
- 월간 5,000 에러 이벤트
- 10,000 성능 트랜잭션
- 1개월 데이터 보존

### 샘플링 조정
```typescript
// 개발환경
tracesSampleRate: 1.0,  // 100% 수집
replaysSessionSampleRate: 0.1,  // 10% 세션 재생

// 프로덕션환경  
tracesSampleRate: 0.1,  // 10% 수집
replaysSessionSampleRate: 0.05,  // 5% 세션 재생
```

이 설정으로 Sentry를 통한 포괄적인 에러 추적 및 성능 모니터링이 가능합니다.