[React/리액트] 프로젝트에 Sentry 도입하기 / 모니터링 시스템 구축하기

평소 프론트엔드 모니터링에 관심이 많았는데, 운영 중인 서비스에서 발생하는 에러를 실시간으로 파악하지 못하는 불편함을 겪고 있었다. 이를 해결하고자 Sentry를 도입한 경험을 공유하고자 한다.

Vite + React 프로젝트에서 Sentry를 설정하고 활용하는 방법을 상세히 다룰 예정이다.

Sentry란?

Sentry는 실시간으로 애플리케이션의 에러를 감지하고 모니터링할 수 있는 플랫폼이다

Sentry를 선택한 이유

프론트엔드 모니터링 도구로 Google Analytics나 Microsoft Clarity 같은 대안들도 있었다. 하지만 이 도구들은 사용자 행동 분석이나 일반적인 웹 분석에 초점이 맞춰져 있다는 한계가 있었다.

 

GA, Clarity와 Sentry의 차이점

• Google Analytics: 사용자 행동 패턴, 트래픽, 전환율 등 비즈니스 관점의 데이터 분석에 강점
• Microsoft Clarity: 히트맵, 세션 레코딩 등 UX 분석과 사용자 행동 패턴 파악에 특화
• Sentry: 실시간 에러 추적, 스택 트레이스 제공, 디버깅에 필요한 상세 정보 제공

Sentry는 순수하게 에러 모니터링과 디버깅에 특화된 도구다. 특히 다음과 같은 장점들 때문에 Sentry를 선택했다.

1. 개발자 친화적인 에러 리포트
   • 정확한 에러 발생 위치와 스택 트레이스 제공
   • 소스맵 지원으로 실제 코드 라인 추적 가능
   • 에러 발생 시점의 상태와 환경 정보 상세 제공
2. 실시간성
   • 에러 발생 즉시 알림 가능
   • 이슈의 발생 빈도와 영향도 실시간 모니터링
   • 신속한 대응이 가능한 환경 제공
3. 개발 워크플로우 통합
   • GitHub 등 개발 도구들과의 쉬운 연동
   • CI/CD 파이프라인에 통합 가능
   • 팀 협업 도구들과의 원활한 연동

다른건 다 모르겠고 에러 발생시 즉시 알림이 가능하다는 점이 가장 마음에 들었고 유사한 에러들을 자동으로 그룹화해준다는 점에서 에러 대응에 가장 효과적일 것 같다는 판단을 했다. 또한 현재 프로젝트에서 디스코드를 사용하고 있는데 팀 디스코드와 에러 알림을 연동하면 매우 좋고 개발 생산성이 향상될 것 같다는 점에서 바로 Sentry를 선택했다. 따라서 해당 글에서는 Sentry 기초 설정과 함께 디스코드 알림 연동까지 기록하고자 한다! 자세한 도입 배경은 바로 밑에 있다.

도입 배경

우리 프로젝트에서 Sentry를 도입하게 된 계기는 크게 세 가지가 있다.

 

1. 사용자 환경 다양화
- PC, 모바일 등 다양한 디바이스
- Chrome, Safari, Firefox 등 여러 브라우저
- 각기 다른 OS와 버전

 

우리는 웹앱/웹뷰 이렇게 웹에서 접근할 수 있는 웹앱과 해당 사이트를 웹뷰로 전환해 앱으로 접속할 수 있도록 개발을 했기 때문에 에러가 발생할 수 있는 환경이 다양했다. 현실적으로 이렇게 다양한 환경에서 발생할 수 있는 에러들을 일일이 테스트하고 대응하기는 불가능하다.

 

2. 에러 추적의 어려움
- 사용자가 신고하기 전까지 에러 파악 불가
- 에러 발생 상황과 맥락 파악이 어려움
- 재현이 힘든 버그들의 존재

로컬이나 개발 환경에서는 발생하지 않던 에러들이 실제 운영 환경에서 발생하는 경우가 많았고, 이를 효과적으로 추적할 방법이 필요했다!

3. 선제적 대응 필요성
- 사용자 경험 향상을 위한 빠른 버그 픽스
- 에러 패턴 분석을 통한 예방적 조치
- 품질 모니터링 체계 구축

단순히 에러를 수집하는 것을 넘어, 애플리케이션의 안정성을 지속적으로 모니터링하고 개선할 수 있는 시스템이 필요했다! 하지만 이건 실사용자의 부족으로 실제로 이어지진 못했다 흑흑 언젠가 해보겠지,,,

Sentry 설정하기

1. 필요한 패키지 설치
먼저 Sentry 관련 패키지들을 설치한다.

yarn add @sentry/react @sentry/vite-plugin

2. Vite 설정
vite.config.ts 파일에 Sentry 플러그인을 추가했다. 소스맵 생성을 위한 설정도 함께 추가했다. 소스맵이란 

import { sentryVitePlugin } from '@sentry/vite-plugin';
import react from '@vitejs/plugin-react';
import { defineConfig } from 'vite';
import tsconfigPaths from 'vite-tsconfig-paths';

export default defineConfig({
  plugins: [
    react(),
    tsconfigPaths(),
    sentryVitePlugin({
      org: "soongsil-university-uz",
      project: "javascript-react-bc",
    }),
  ],
  build: {
    sourcemap: true, // 소스맵 생성 활성화
  },
});

3. Sentry 초기화
utils 폴더 아래에 initSentry.ts 파일을 만들어 Sentry 초기화 로직을 분리했다. 가독성을 위해 ㅎ

import * as Sentry from '@sentry/react';

export const initSentry = () => {
  const SENTRY_DSN = import.meta.env.VITE_SENTRY_DSN;

  Sentry.init({
    dsn: SENTRY_DSN,
    integrations: [
      Sentry.browserTracingIntegration(),
      Sentry.replayIntegration()
    ],
    tracesSampleRate: 1.0,
    // 개발 환경에서는 localhost도 추가
    tracePropagationTargets: ['https://b1g4-bookmark.vercel.app/'],
    replaysSessionSampleRate: 0.1,
    replaysOnErrorSampleRate: 1.0,
  });
};

 

참고로 개발 환경과 배포 환경을 분리해야 개발 환경에서 나온 디버깅용 에러에 대한 알림도 따로 설정이 가능하다.

주요 설정값들은 이런 것들이 있다.

- `tracesSampleRate`: 성능 모니터링을 위한 샘플링 비율
- `tracePropagationTargets`: 추적할 도메인 설정
- `replaysSessionSampleRate`: 일반 세션의 녹화 비율
- `replaysOnErrorSampleRate`: 에러 발생 시 세션 녹화 비율

4. 애플리케이션에 적용
main.tsx에서 Sentry 초기화 함수를 호출했다. 사실 그냥 초기화 해줘도 된다.

import { initSentry } from './utils/initSentry';

initSentry();

createRoot(document.getElementById('root')!).render(
  <StrictMode>
    <App />
  </StrictMode>
);

5. 환경 변수 설정
프로젝트 루트에 .env 파일을 만들고 Sentry DSN을 설정했다. .gitignore에도 Sentry 관련 설정 파일을 추가해야 하는데 자동으로 추가된당

VITE_SENTRY_DSN=your-sentry-dsn-here

 

자세한 코드는 다음 pr에서 확인할 수 있다.

https://github.com/ssu-B1G4/Bookmark_web/pull/98

 

도입 결과

 

이렇게 어느 부분에서 에러가 났는지부터 몇명의 유저가, 이탈률은 얼마나 되는지 이런 것들을 전부 자세히 확인이 가능하다! 너무 신기

이렇게 에러에 대한 설명부터 언제 발생했는지~ 

 

이렇게 사용자의 에러를 녹화해주기도 한다. 브라우저나 OS 역시 확인할 수 있다. 사용자로부터 피드백이나 신고를 받지 않고도 어느 환경에서 에러가 났는지를 빠르게 파악할 수 있다는 점이 가장 좋았다! 빠른 에러 대응이 가능했다.

Discord 알림 설정

Sentry에서 발생하는 에러를 실시간으로 모니터링하기 위해 Discord 연동을 추가했다.

1. Sentry 프로젝트 설정에서 Discord Integration을 추가
2. Alert Rules 설정
   - 신규 이슈 발생 시 알림
   - 특정 심각도(error, fatal) 이상의 이슈만 알림
   - 운영 환경에서 발생한 이슈에 대해서만 알림

이렇게 설정하니 실제 에러 발생 시 Discord 채널에서 바로 확인이 가능해졌다.

Sentry 도입으로 얻은 이점

1. 실시간 에러 모니터링 가능
2. 에러 발생 환경과 스택 트레이스 확인 용이
3. Discord 연동으로 빠른 대응 가능

 

작은 프로젝트에서는 큰 효과를 얻지 못하겠지만 규모가 커질 수록 더 빛을 보는 기술이 모니터링 같다. Sentry 도입을 통해 미미하지만 에러 대응을 실시간으로 할 수 있는 경험을 했고 프로젝트의 개발 생산성도 조금이나마 올려볼 수 있는 기회를 가진 것 같아 재밌었다. 다음에는 안 써본 Clarity와 GA도 써보고 싶고 무엇보다 대용량 트래픽!! 사용자가 많은 환경에서 모니터링을 진행한 후 모니터링 결과에 맞는 의사 결정을 하는 개발을 정말 해보고싶다 ㅜㅜㅜ

 

모니터링 도입이 생각보다 어렵지 않으니! 그리고 공식 문서가 매우 자세하게 잘 나와있으니 그 부분을 잘 참고하면 누구나 모니터링 시스템을 쉽게 도입할 수 있다! 앞으로도 모니터링을 기반으로 한 데이터 기반의 최적화를 진행해야겠다고 생각햇다

다음에는 디스코드 알림 구분, 분류를 주제로 글을 써오겟음