[FEAT] Sentry 기반 에러 모니터링 환경 구성

package.json

@@ -19,6 +19,7 @@
     "i18n:transform": "tsx scripts/i18nTransform.ts"
   },
   "dependencies": {
+    "@sentry/react": "^10.46.0",
     "@tanstack/eslint-plugin-query": "^5.91.4",
     "@tanstack/react-query": "^5.90.20",
     "axios": "^1.13.4",
@@ -44,6 +45,7 @@
     "@babel/types": "^7.28.4",
     "@chromatic-com/storybook": "^3.2.2",
     "@eslint/js": "^9.15.0",
+    "@sentry/vite-plugin": "^5.1.1",
     "@storybook/addon-essentials": "^8.6.15",
     "@storybook/addon-interactions": "^8.6.15",
     "@storybook/addon-onboarding": "^8.6.15",

src/apis/apis/member.ts

@@ -1,3 +1,4 @@
+import * as Sentry from '@sentry/react';
 import { setAccessToken } from '../../util/accessToken';
 import { ApiUrl } from '../endpoints';
 import { request } from '../primitives';
@@ -40,6 +41,10 @@ export async function postUser(code: string): Promise<PostUserResponseType> {
     throw new Error('Authorization 헤더가 존재하지 않습니다.');
   }
 
+  Sentry.setUser({
+    id: String(response.data.id),
+  });
+
   return response.data;
 }
 

src/apis/axiosInstance.ts

@@ -1,4 +1,5 @@
 import axios from 'axios';
+import * as Sentry from '@sentry/react';
 import {
   getAccessToken,
   removeAccessToken,
@@ -13,12 +14,17 @@ import {
 
 // Get current mode (DEV, PROD or TEST)
 const currentMode = import.meta.env.MODE;
+const requestTimeoutMs = 5000;
+
+type SentryCapturedError = {
+  __sentry_captured__?: boolean;
+};
 
 // Axios instance
 export const axiosInstance = axios.create({
   baseURL:
     currentMode === 'test' ? undefined : import.meta.env.VITE_API_BASE_URL,
-  timeout: 5000,
+  timeout: requestTimeoutMs,
   timeoutErrorMessage:
     '시간 초과로 인해 요청을 처리하지 못했어요... 잠시 후 다시 시도해 주세요.',
   headers: {
@@ -38,6 +44,39 @@ axiosInstance.interceptors.request.use((config) => {
   return config;
 });
 
+function captureClientApiError(error: unknown) {
+  if (!axios.isAxiosError(error)) {
+    return;
+  }
+
+  const { response, config, code } = error;
+  const status = response?.status;
+
+  // 401 재발급 흐름과 정상/리다이렉트 응답만 제외하고, 4xx/5xx/네트워크 실패/타임아웃은 수집
+  if (status === 401 || (status !== undefined && status < 400)) {
+    return;
+  }
+
+  Sentry.captureException(error, {
+    tags: {
+      errorType: 'api-error',
+      httpStatus: status ? String(status) : 'network-error',
+    },
+    extra: {
+      pathname: window.location.pathname,
+      search: window.location.search,
+      url: config?.url,
+      method: config?.method,
+      baseURL: config?.baseURL,
+      params: config?.params,
+      timeout: config?.timeout ?? requestTimeoutMs,
+      errorCode: code,
+    },
+  });
+
+  (error as SentryCapturedError).__sentry_captured__ = true;
+}
+
 // Response interceptor
 axiosInstance.interceptors.response.use(
   (response) => response,
@@ -70,15 +109,27 @@ axiosInstance.interceptors.response.use(
         originalRequest.headers.Authorization = `${newAccessToken}`;
         return axiosInstance(originalRequest);
       } catch (refreshError) {
+        if (
+          axios.isAxiosError(refreshError) &&
+          refreshError.response?.status !== 401 &&
+          refreshError.response?.status !== 403
+        ) {
+          captureClientApiError(refreshError);
+        }
+
         console.error('Refresh Token is invalid or expired', refreshError);
         // 재발급도 실패하면 -> 로그인 페이지 이동
         const currentLang = i18n.resolvedLanguage ?? i18n.language;
         const lang = isSupportedLang(currentLang) ? currentLang : DEFAULT_LANG;
+        Sentry.setUser(null);
         window.location.href = buildLangPath('/home', lang);
         removeAccessToken();
         return Promise.reject(refreshError);
       }
     }
+
+    captureClientApiError(error);
+
     return Promise.reject(error);
   },
 );

src/apis/primitives.ts

@@ -9,6 +9,7 @@ export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
 export class APIError extends Error {
   public readonly status: number;
   public readonly data: unknown;
+  public __sentry_captured__?: boolean;
 
   constructor(message: string, status: number, data: unknown) {
     super(message);
@@ -18,6 +19,10 @@ export class APIError extends Error {
   }
 }
 
+type SentryCapturedError = {
+  __sentry_captured__?: boolean;
+};
+
 // Low-level http request function
 export async function request<T>(
   method: HttpMethod,
@@ -54,6 +59,9 @@ export async function request<T>(
         error.response?.status || 500,
         responseData,
       );
+      apiError.__sentry_captured__ = (
+        error as SentryCapturedError
+      ).__sentry_captured__;
       throw apiError;
     }
 

src/components/ErrorBoundary/ErrorBoundary.tsx

@@ -1,4 +1,5 @@
 import { Component, ErrorInfo, ReactNode } from 'react';
+import * as Sentry from '@sentry/react';
 import ErrorPage from './ErrorPage';
 
 interface ErrorBoundaryProps {
@@ -14,6 +15,10 @@ interface ErrorBoundaryState {
 const defaultError = new Error('알 수 없는 오류');
 const defaultStack = '스택 정보 없음';
 
+type SentryCapturedError = {
+  __sentry_captured__?: boolean;
+};
+
 class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundaryState> {
   constructor(props: ErrorBoundaryProps) {
     super(props);
@@ -31,7 +36,20 @@ class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundaryState> {
   }
 
   componentDidCatch(error: Error, errorInfo: ErrorInfo): void {
-    // You can also log the error to an error reporting service
+    // 이미 API 인터셉터 등에서 캡처된 에러가 아니라면 전송
+    if (!(error as SentryCapturedError).__sentry_captured__) {
+      Sentry.captureException(error, {
+        tags: {
+          errorType: 'render-error',
+        },
+        extra: {
+          pathname: window.location.pathname,
+          search: window.location.search,
+          componentStack: errorInfo.componentStack,
+        },
+      });
+    }
+
     console.log(error, errorInfo);
   }
 

src/hooks/mutations/useLogout.ts

@@ -1,3 +1,4 @@
+import * as Sentry from '@sentry/react';
 import { useMutation } from '@tanstack/react-query';
 import { logout } from '../../apis/apis/member';
 import { removeAccessToken } from '../../util/accessToken';
@@ -10,6 +11,7 @@ export default function useLogout(onSuccess: () => void) {
     },
     onSuccess: () => {
       removeAccessToken();
+      Sentry.setUser(null);
       onSuccess();
     },
   });

src/instrument.ts

@@ -0,0 +1,25 @@
+import * as Sentry from '@sentry/react';
+
+const dsn = import.meta.env.VITE_SENTRY_DSN;
+
+if (import.meta.env.PROD && dsn) {
+  Sentry.init({
+    dsn,
+    environment: import.meta.env.MODE,
+    integrations: [
+      // 페이지 로드와 라우트 이동 등의 성능 흐름 추적
+      Sentry.browserTracingIntegration(),
+      // 에러가 발생한 세션만 Replay로 남기고, 개인 정보 가림
+      Sentry.replayIntegration({
+        maskAllText: true,
+        blockAllMedia: true,
+      }),
+    ],
+    // 백엔드는 Datadog를 사용 중이므로, 프론트 단독 성능 추적만 낮은 비율로 수집
+    tracesSampleRate: 0.1,
+    // 일반 세션 Replay는 수집 X
+    replaysSessionSampleRate: 0,
+    // 에러가 발생한 세션은 모두 Replay로 남김
+    replaysOnErrorSampleRate: 1.0,
+  });
+}

src/main.tsx

@@ -1,3 +1,4 @@
+import './instrument';
 import { StrictMode } from 'react';
 import { createRoot } from 'react-dom/client';
 import { RouterProvider } from 'react-router-dom';

vite.config.ts

@@ -1,13 +1,36 @@
 import { defineConfig as defineViteConfig, loadEnv, mergeConfig } from 'vite';
 import { defineConfig as defineVitestConfig } from 'vitest/config';
 import react from '@vitejs/plugin-react';
+import { sentryVitePlugin } from '@sentry/vite-plugin';
 
 const viteConfig = defineViteConfig(({ mode }) => {
   const env = loadEnv(mode, process.cwd(), '');
+  const isProductionBuild = mode === 'production';
+  const hasSentryAuth =
+    !!env.SENTRY_AUTH_TOKEN && !!env.SENTRY_ORG && !!env.SENTRY_PROJECT;
+  const shouldUploadSourcemaps = isProductionBuild && hasSentryAuth;
+  const plugins = [react()];
+
+  if (shouldUploadSourcemaps) {
+    plugins.push(
+      sentryVitePlugin({
+        authToken: env.SENTRY_AUTH_TOKEN,
+        org: env.SENTRY_ORG,
+        project: env.SENTRY_PROJECT,
+        telemetry: false,
+        sourcemaps: {
+          filesToDeleteAfterUpload: 'dist/**/*.map',
+        },
+      }),
+    );
+  }
 
   return {
     base: env.VITE_BASE_PATH || '/',
-    plugins: [react()],
+    plugins,
+    build: {
+      sourcemap: shouldUploadSourcemaps ? 'hidden' : false,
+    },
     server: {
       proxy: {
         '/api': {