Sentry로 Node.js 오류 추적 및 알림 설정

소개

Sentry는 런타임에서 발생하는 예외와 성능 문제를 수집해 문제 재현과 원인 분석을 돕는 도구다. 이 글에서는 Sentry를 이용한 Node.js 오류 추적과 알림 설정을 단계별로 설명한다. 초보자도 따라할 수 있도록 기본 설치부터 Express 연동, 알림 규칙까지 실무 중심으로 정리한다.

사전 준비

다음 항목을 확인하면 설정이 원활하다.

• Node.js 프로젝트(버전 14+ 권장)
• Sentry 계정 및 프로젝트 생성
• 프로젝트의 DSN(프로젝트 설정에서 확인)
• 환경 변수 관리 방법(예: dotenv, 환경별 설정)

설치 및 초기화

먼저 Sentry SDK를 설치한다. npm 또는 yarn을 사용하면 된다.

npm install @sentry/node @sentry/tracing --save

기본 설정

애플리케이션 진입점에서 SDK를 초기화한다. DSN은 환경 변수로 관리한다.

require('dotenv').config();
const Sentry = require('@sentry/node');
const Tracing = require('@sentry/tracing');

Sentry.init({
  dsn: process.env.SENTRY_DSN,
  environment: process.env.NODE_ENV || 'development',
  tracesSampleRate: 0.1, // 퍼포먼스 모니터링 비율
  release: process.env.npm_package_version
});

Express와 연동

Express 앱에 미들웨어로 등록하면 요청별 스코프와 에러 캡처가 자동으로 동작한다.

const express = require('express');
const app = express();

// Sentry request handler
app.use(Sentry.Handlers.requestHandler());
app.use(Sentry.Handlers.tracingHandler());

// 라우트 정의
app.get('/', (req, res) => {
  res.send('Hello Sentry');
});

// 예외 발생 예시
app.get('/error', (req, res) => {
  throw new Error('테스트 에러');
});

// Sentry error handler
app.use(Sentry.Handlers.errorHandler());

app.listen(3000);

프로덕션에서의 추가 설정

Unhandled 에러 및 프로미스 거부 처리

프로세스 레벨의 에러도 캡처해 Sentry로 전송한다. 이때 재시작 정책을 명확히 해야 한다.

process.on('uncaughtException', (err) => {
  Sentry.captureException(err);
  // 적절한 로그 후 프로세스 종료 여부 결정
});

process.on('unhandledRejection', (reason) => {
  Sentry.captureException(reason);
});

환경 구분과 릴리스 태깅

환경(environment)과 릴리스(release)를 설정하면 배포별 에러 추적이 쉬워진다. CI/CD 파이프라인에서 릴리스 태그를 자동화하는 것을 권장한다.

알림(Alerts) 설정 전략

Sentry의 Alert Rules를 사용해 알림을 구성한다. 핵심은 노이즈를 줄이고 중요한 에러에만 알림이 가도록 하는 것이다.

• 에러 비율 기반 알림: 특정 에러 발생률이 급증할 때
• 구체적 이벤트 알림: 치명적인 예외 발생 시 즉시 알림
• 환경별 알림: production은 즉시, staging은 요약

알림 수단으로는 이메일, Slack, PagerDuty 등을 연동할 수 있다. Sentry UI에서 Integration을 추가하고, 프로젝트별 Alert Rule을 생성하면 된다.

디버깅을 위한 추가 팁

• Breadcrumbs 활성화로 사용자 행동과 시스템 상태를 함께 확인
• Tag와 Context 사용으로 문제의 범위와 영향을 빠르게 좁힘
• Source maps 업로드로 트랜스파일된 코드의 원본 라인 확인
• 샘플링과 Rate limit으로 과다한 이벤트 발생을 제어

테스트와 검증

설치 후에는 의도적으로 에러를 발생시켜 전송 흐름과 알림을 확인한다. 다음 예제는 간단한 테스트용 에러다.

app.get('/sentry-test', (req, res) => {
  Sentry.captureMessage('sentry test message');
  res.status(200).send('Sentry test sent');
});

운영 관점의 권장사항

• 민감 정보는 스크럽(PII 제거) 설정을 통해 제거
• 에러 우선순위 분류로 온콜 부담 경감
• 정기 릴리스와 매핑해 문제 원인 추적 속도 향상

맺음말

Sentry를 도입하면 Node 오류 추적 Sentry 연동이 쉬워지고 문제 대응 속도가 개선된다. 초기 설정과 알림 정책을 명확히 하면 운영 비용을 줄이고 더 안정적인 서비스 운영이 가능하다.