[G1-Sync] Manual knowledge update

2026-05-09 21:08:02 +09:00
parent f0befc887a
commit 93ec7e9056
363 changed files with 68333 additions and 64 deletions
@@ -0,0 +1,125 @@
+---
+id: observability-error-reporting
+title: Error Reporting — Sentry / 분류 / 우선순위
+category: Coding
+status: draft
+source_trust_level: B
+verification_status: conceptual
+created_at: 2026-05-09
+updated_at: 2026-05-09
+tags: [observability, error-reporting, sentry, vibe-coding]
+tech_stack: { language: "TypeScript / Sentry / Bugsnag", applicable_to: ["Web", "Backend", "Mobile"] }
+applied_in: []
+aliases: [Sentry, exception capture, source maps, fingerprinting]
+---
+
+# Error Reporting
+
+> 로그만으로는 에러 우선순위 판단 어려움. **Sentry / Bugsnag 같은 도구**가 fingerprint / count / 영향 사용자 수 / breadcrumb / source map / 알림을 묶어줌. 단 **모든 throw 가 capture 대상은 아님**.
+
+## 📖 핵심 개념
+- Fingerprint: 같은 종류 에러 묶기. 1만번 발생해도 하나의 issue.
+- Breadcrumb: 에러 직전의 사용자/시스템 액션 시퀀스.
+- Source map: minified 코드 stack 을 원본 매핑.
+- Release: 어떤 빌드에서 발생했는지. SHA / version 으로.
+- Sample rate: 트래픽 큰 곳은 sampling.
+
+## 💻 코드 패턴
+
+### Sentry Node
+```ts
+import * as Sentry from '@sentry/node';
+
+Sentry.init({
+  dsn: process.env.SENTRY_DSN,
+  environment: process.env.NODE_ENV,
+  release: process.env.GIT_SHA,
+  tracesSampleRate: 0.1,
+  profilesSampleRate: 0.1,
+  beforeSend(event, hint) {
+    // PII redact
+    if (event.user?.email) event.user.email = '[REDACTED]';
+    // 무시할 에러
+    if (hint.originalException instanceof KnownClientError) return null;
+    return event;
+  },
+});
+
+// Express integration
+app.use(Sentry.Handlers.requestHandler());
+app.use(Sentry.Handlers.tracingHandler());
+// ... routes ...
+app.use(Sentry.Handlers.errorHandler());
+```
+
+### Sentry Browser (Vite/Next)
+```ts
+import * as Sentry from '@sentry/react';
+
+Sentry.init({
+  dsn,
+  release,
+  integrations: [Sentry.browserTracingIntegration(), Sentry.replayIntegration()],
+  tracesSampleRate: 0.1,
+  replaysSessionSampleRate: 0.01,
+  replaysOnErrorSampleRate: 1.0,
+});
+
+// React error boundary
+<Sentry.ErrorBoundary fallback={<ErrorPage />}>{children}</Sentry.ErrorBoundary>
+```
+
+### 사용자 컨텍스트
+```ts
+Sentry.setUser({ id: user.id, email: user.email });
+// 로그아웃
+Sentry.setUser(null);
+```
+
+### Custom fingerprint — 잘못 묶이는 경우
+```ts
+Sentry.captureException(err, {
+  fingerprint: ['stripe-decline', err.code],
+  tags: { provider: 'stripe', errorCode: err.code },
+  extra: { orderId, userId },
+});
+```
+
+### 의도적 무시
+```ts
+// 사용자가 cancel 한 fetch — 에러 X
+fetch(...).catch(e => {
+  if (e.name === 'AbortError') return; // Sentry 안 보냄
+  Sentry.captureException(e);
+});
+```
+
+## 🤔 의사결정 기준
+| 에러 종류 | capture |
+|---|---|
+| 예측된 도메인 실패 (잔액 부족) | ❌ — 정상 흐름 |
+| 4xx (클라이언트 잘못) | 보통 ❌ |
+| 5xx (서버 버그) | ✅ |
+| 외부 API 실패 (재시도 후 final fail) | ✅ + provider tag |
+| Browser unhandled rejection | ✅ (자동) |
+| React render error | ✅ (ErrorBoundary onError) |
+| AbortError | ❌ |
+| Network offline | ❌ 또는 별도 이벤트 |
+
+## ❌ 안티패턴
+- **모든 에러 capture**: 노이즈 → 진짜 버그 파묻힘.
+- **PII 그대로**: 이메일 / 카드 / 토큰. beforeSend 에서 redact.
+- **source map 안 업로드**: stack 이 minified — 디버깅 불가. CI 가 release 와 함께 업로드.
+- **release 태그 없음**: 어떤 버전 사고인지 모름. git SHA 자동.
+- **fingerprint 잘못**: 같은 에러가 1000개 issue 로 분리. 또는 다른 에러가 한 issue 로.
+- **알림 없음 / 알림 폭주**: critical 레벨만 PagerDuty. 나머지는 Slack/이메일.
+- **breadcrumb 에 민감정보**: form 입력 자동 캡처가 비밀번호 leak. denyUrls / mask.
+- **dev 에서도 Sentry on**: 노이즈. environment 분리.
+
+## 🤖 LLM 활용 힌트
+- 새 catch 블록: "예측 가능 vs 시스템 에러 분류 후 system 만 capture" 강제.
+- ErrorBoundary onError + captureException + extra context.
+
+## 🔗 관련 문서
+- [[Error_Handling_Result_vs_Throw]]
+- [[Observability_Structured_Logging]]