들어가며
최근 우리 회사의 Next.js 기반 웹 애플리케이션의 복잡성이 급격히 증가하면서, 운영 환경에서 발생하는 문제가 프론트엔드에서 비롯된 것인지, 아니면 백엔드에서 기인한 것인지 구분하기 어려운 상황이 자주 발생했습니다. 기존에는 Datadog을 사용하여 API 관련 에러를 추적하고 있었지만, 프론트엔드에서 발생하는 에러에 대한 로그 수집과 추적이 미흡하여 문제 해결에 많은 어려움을 겪었습니다. 이러한 도전을 극복하기 위해, 우리는 애플리케이션의 안정성과 성능을 지속적으로 개선해야 할 필요성을 느꼈고, 그 해결책으로 Sentry의 도입을 결정하게 되었고, 이번 포스팅에서는 간단하게 Sentry란 무엇이고 next.js에 적용하는 방법을 포스팅 하려고합니다.
1. Sentry란 무엇인가?
Sentry는 실시간으로 로그를 수집하고 분석하는 도구이자, 포괄적인 모니터링 플랫폼으로 에러를 효과적으로 추적하고 관리하여, 개발자들이 보다 신속하게 대응할 수 있게 돕습니다. 에러가 발생했을 때 그 에러가 나타난 코드와 런타임 환경을 포함한 필수적인 정보를 자동으로 수집하여 개발자에게 제공함으로써, 어디서나 에러를 효과적으로 진단하고 해결할 수 있는 능력을 제공합니다.
2. Next.js에 Sentry 적용하기
2-1 패키지 설치
npm install @sentry/nextjs
yarn add @sentry/nextjs
pnpm add @sentry/nextjs
2-1 sentry에서 DSN, Auth token 발급받기


2-3 root 경로(모노레포라면 각 서비스 루트 경로)에 아래 세 파일 추가
sentry.client.config.ts
프론트엔드(클라이언트 측)에서 사용될 Sentry 설정 파일입니다. 브라우저에서 실행되는 코드의 에러를 캡처합니다.
import * as Sentry from "@sentry/nextjs";
Sentry.init({
dsn: '프로젝트 DSN', // Sentry 프로젝트의 고유 키로, 에러 데이터를 전송하는 데 사용됩니다.
environment: globalThis.process.env.NEXT_PUBLIC_ENV, // 실행 환경(개발, 테스트, 생산 등)을 설정합니다.
tracesSampleRate: 1.0, // 트랜잭션 데이터를 샘플링하는 비율을 설정합니다. 1.0은 100% 샘플링을 의미합니다.
replaysSessionSampleRate: 0.1, // 세션 리플레이를 캡처할 확률을 설정합니다. 0.1은 10%의 세션을 캡처합니다.
replaysOnErrorSampleRate: 1.0, // 에러 발생 시 리플레이를 캡처할 확률을 설정합니다. 1.0은 에러가 발생한 모든 세션을 캡처합니다.
integrations: [
Sentry.replayIntegration(), // 세션 리플레이 기능을 활성화합니다.
Sentry.breadcrumbsIntegration({
console: true, // 콘솔 로그를 자동으로 Breadcrumbs에 기록하도록 설정합니다.
}),
Sentry.browserTracingIntegration(), // 브라우저에서의 성능 추적을 위한 통합을 활성화합니다.
],
});
sentry.edge.config.ts
Edge 서버에서 사용될 Sentry 설정 파일입니다. Vercel과 같은 플랫폼에서 사용되며, 서버리스 함수나 에지 네트워크에서 발생하는 이슈를 관리합니다.
import * as Sentry from "@sentry/nextjs";
Sentry.init({
dsn: "내 프로젝트 DSN",
// Set tracesSampleRate to 1.0 to capture 100%
// of transactions for performance monitoring.
// We recommend adjusting this value in production
tracesSampleRate: 1.0,
// ...
// Note: if you want to override the automatic release value, do not set a
// `release` value here - use the environment variable `SENTRY_RELEASE`, so
// that it will also get attached to your source maps
});
sentry.server.config.ts
서버 측에서 사용될 Sentry 설정 파일입니다. Next.js의 서버사이드 렌더링 코드에서 발생하는 에러를 캡처합니다.
import * as Sentry from "@sentry/nextjs";
Sentry.init({
dsn: "내 프로젝트 DSN",
// Set tracesSampleRate to 1.0 to capture 100%
// of transactions for performance monitoring.
// We recommend adjusting this value in production
tracesSampleRate: 1.0,
// ...
// Note: if you want to override the automatic release value, do not set a
// `release` value here - use the environment variable `SENTRY_RELEASE`, so
// that it will also get attached to your source maps
});
- dsn: Sentry 프로젝트의 고유 키로, 에러 데이터를 전송하는 데 사용됩니다.
- environment: 실행 환경(개발, 테스트, 생산 등)을 설정합니다.
- tracesSampleRate: 트랜잭션 데이터를 샘플링하는 비율을 설정합니다. (1.0은 100% 샘플링을 의미합니다.)
- replaysSessionSampleRate: 세션 리플레이를 캡처할 확률을 설정합니다. (0.1은 10%의 세션을 캡처합니다.)
- replaysOnErrorSampleRate: 에러 발생 시 리플레이를 캡처할 확률을 설정합니다. (1.0은 에러가 발생한 모든 세션을 캡처합니다.)
- integrations: Sentry와 함께 사용할 추가 기능을 설정합니다.
- replayIntegration(): 세션 리플레이 기능을 활성화합니다.
- breadcrumbsIntegration({ console: true }): 콘솔 로그를 자동으로 Breadcrumbs에 기록하도록 설정합니다.
- browserTracingIntegration(): 브라우저에서의 성능 추적을 위한 통합을 활성화합니다.
2-4 next.config.js 파일에 아래 코드 추가
// Next.js 프로젝트에 Sentry를 사용하기 위한 설정
const { withSentryConfig } = require("@sentry/nextjs");
const nextConfig = {
// 여기에 기존의 next.js 구성 옵션들을 추가합니다.
sentry: {
// Sentry 구성 옵션들이 여기에 들어갑니다.
},
};
const sentryWebpackPluginOptions = {
// Sentry 웹팩 플러그인 설정
org: "example-org",
project: "example-project",
authToken: process.env.SENTRY_AUTH_TOKEN, // 소스맵 업로드를 위한 인증 토큰
silent: true, // 모든 로그 억제
};
module.exports = withSentryConfig(nextConfig, sentryWebpackPluginOptions);
2-5 공통 ErrorBoundary 만들기
ErrorBoundary는 자식 컴포넌트 트리 내에서 발생하는 JavaScript 에러를 캐치하여 처리하는 컴포넌트입니다. 에러 바운더리는 주로 UI의 일부분만 에러에 영향을 받게 하여 전체 애플리케이션의 다운을 막는데 사용됩니다. Sentry와 함께 사용하면 에러 정보를 Sentry로 보낼 수 있습니다.
import React from 'react';
import * as Sentry from '@sentry/react';
class ErrorBoundary extends React.Component {
constructor(props) {
super(props);
this.state = { eventId: null };
}
componentDidCatch(error, errorInfo) {
Sentry.withScope(scope => {
scope.setExtras(errorInfo);
const eventId = Sentry.captureException(error);
this.setState({ eventId });
});
}
render() {
if (this.state.eventId) {
// 렌더링 시 에러 UI 표시
return (
<button onClick={() => Sentry.showReportDialog({ eventId: this.state.eventId })}>
에러 보고하기
</button>
);
}
return this.props.children;
}
}
2-5 try-catch Sentry 적용
'try-catch' 블록을 사용하면 실행 중 발생할 수 있는 예외를 처리할 수 있습니다. Sentry와 함께 사용하면 캐치된 에러를 Sentry로 보낼 수 있습니다.
try {
// 예외 처리 대상 코드
} catch (error) {
Sentry.captureException(error);
}
3. Sentry 핵심 기능
- 대시보드 (Dashboard): 애플리케이션의 전반적인 건강 상태를 포함하여 에러 발생 빈도와 성능 문제를 총체적으로 파악할 수 있는 중심적인 인터페이스를 제공합니다. 사용자는 여기에서 시간 경과에 따른 에러 추세와 성능 지표의 변화를 한눈에 볼 수 있습니다.
- 이슈 트래커 (Issues): 발생한 각 에러를 독립된 이슈로 관리하고, 해당 이슈에 대한 상세 정보를 제공합니다. 이를 통해 에러의 원인과 영향을 받는 사용자 수, 그리고 해당 에러의 발생 빈도 등을 파악할 수 있어 문제 해결에 중요한 데이터를 제공합니다.
- 릴리즈 (Releases): 소프트웨어의 버전별로 릴리즈 정보를 추적하며, 각 릴리즈에서 발생한 에러와 성능 지표를 관리합니다. 이를 통해 개발자는 특정 릴리즈에 대한 문제를 식별하고, 개선 작업을 계획할 수 있습니다.
- 성능 모니터링 (Performance): 애플리케이션의 트랜잭션을 모니터링하고, 각 트랜잭션의 응답 시간과 처리량 같은 세부 성능 지표를 제공합니다. 성능 저하 문제를 식별하고 분석하여 개선 방안을 모색할 수 있습니다.
- Discover: 로그 데이터와 이벤트를 깊이 있게 분석할 수 있는 도구입니다. 사용자는 사용자 정의 쿼리와 데이터 시각화를 통해 복잡한 데이터를 탐색하고, 관련 정보를 기반으로 보고서를 생성할 수 있습니다.
- 알림 설정 (Alerts): 에러 발생률이 일정 수준을 초과하거나 특정 이슈가 발생하는 등의 조건이 충족될 때 알림을 설정할 수 있습니다. 이메일이나 Slack과 같은 통합된 서비스를 통해 이러한 알림을 받을 수 있습니다.
마무리
현재 회사에서 Sentry를 도입하는 초기 단계에 있고, 주로 'Issues' 섹션에서 실제로 에러가 잡히는지만 확인해 본 상태입니다. 이 과정을 통해 Sentry의 기능을 직접 체험하고, 실시간 에러 모니터링의 효과를 조금씩 느낄 수 있었습니다. 아직 완전히 활용해 보지는 못했지만, 이 도구가 앞으로 우리 프로젝트의 문제 해결과 성능 개선에 얼마나 큰 도움이 될지 기대하고 있습니다.