Sentry 실전 프로젝트 에러 추적

실전 프로젝트에서 Sentry를 활용해 에러를 추적하고 모니터링하는 방법을 배워봅니다. 초기 설정부터 고급 기능까지 실무에서 바로 적용할 수 있는 내용을 다룹니다.

---

---

들어가며

안녕하세요!

여러분이 Sentry 실전 프로젝트 에러 추적에 대해 궁금하셨다면 잘 찾아오셨습니다. 이 글에서는 실무에서 바로 사용할 수 있는 핵심 개념들을 친근하고 이해하기 쉽게 설명해드리겠습니다.

총 8가지 주요 개념을 다루며, 각각의 개념마다 실제 동작하는 코드 예제와 함께 상세한 설명을 제공합니다. 초보자도 쉽게 따라할 수 있도록 단계별로 풀어서 설명하니 걱정하지 마세요!

목차

1. Sentry_기본_설정
2. 에러_캡처_자동화
3. 커스텀_에러_컨텍스트
4. 사용자_식별_추적
5. 성능_모니터링
6. 브레드크럼_활용
7. 환경별_설정_분리
8. Source_Maps_연동

---

1. Sentry 기본 설정

여러분의 프로덕션 환경에서 갑자기 에러가 발생했는데 어디서 왜 발생했는지 모르는 상황을 겪어본 적 있나요? Sentry는 이런 문제를 해결해줍니다.

개념 이해하기

간단히 말해서, Sentry는 실시간 에러 추적 서비스입니다. 애플리케이션에서 발생하는 모든 에러를 자동으로 수집하고, 어디서 언제 왜 발생했는지 상세하게 알려줍니다.

코드 예제

import * as Sentry from "@sentry/node";

Sentry.init({
  dsn: "https://your-dsn@sentry.io/project-id",
  environment: process.env.NODE_ENV,
  tracesSampleRate: 1.0,
});

동작 원리

이것이 하는 일: DSN은 여러분의 Sentry 프로젝트 고유 주소입니다. environment로 현재 실행 환경을 구분하고, tracesSampleRate로 성능 추적 샘플링 비율을 설정합니다. 여러분이 이 코드를 추가하면 모든 에러가 자동으로 Sentry 대시보드에 전송됩니다.

핵심 정리

핵심 정리: Sentry.init()으로 프로젝트를 초기화하면 에러 추적이 시작됩니다.

실전 팁

실전에서는 DSN을 환경변수로 관리하세요. 절대 코드에 직접 하드코딩하지 마세요.

---

2. 에러 캡처 자동화

모든 try-catch 블록에 에러 로깅을 수동으로 추가하는 것은 비효율적이죠. Sentry는 자동으로 에러를 캡처합니다.

개념 이해하기

간단히 말해서, Sentry는 글로벌 에러 핸들러를 등록해 모든 미처리 에러를 자동으로 감지합니다. 별도의 코드 수정 없이도 대부분의 에러가 자동으로 리포팅됩니다.

코드 예제

// 자동 캡처 (Sentry.init 후 자동 동작)
throw new Error("자동으로 캡처됩니다");

// 수동 캡처
try {
  riskyOperation();
} catch (error) {
  Sentry.captureException(error);
}

동작 원리

이것이 하는 일: 초기화 후 발생하는 모든 에러는 자동으로 Sentry에 전송됩니다. 특정 에러를 명시적으로 캡처하고 싶다면 captureException을 사용하세요. 여러분이 이렇게 하면 에러 누락 없이 모든 문제를 추적할 수 있습니다.

핵심 정리

핵심 정리: 자동 캡처가 기본이고, 필요시 수동으로 captureException을 사용합니다.

---

3. 커스텀 에러 컨텍스트

단순히 에러 메시지만 보면 원인 파악이 어려운 경우가 많죠. 에러가 발생할 때의 상황 정보가 필요합니다.

개념 이해하기

간단히 말해서, 에러 컨텍스트는 에러와 함께 전송되는 추가 정보입니다. 사용자 ID, 요청 파라미터, 현재 상태 등을 함께 보내면 디버깅이 훨씬 쉬워집니다.

코드 예제

Sentry.setContext("order", {
  orderId: "12345",
  amount: 50000,
  paymentMethod: "card"
});

Sentry.captureException(new Error("결제 실패"));

동작 원리

이것이 하는 일: setContext로 에러와 함께 전송할 커스텀 데이터를 설정합니다. 에러 발생 시 Sentry 대시보드에서 이 정보를 함께 확인할 수 있습니다. 여러분이 주문 관련 에러를 추적할 때 주문 정보를 함께 볼 수 있어 원인 파악이 빨라집니다.

핵심 정리

핵심 정리: setContext로 에러에 비즈니스 로직 관련 정보를 추가할 수 있습니다.

실전 팁

실전에서는 민감한 정보(비밀번호, 카드번호)는 절대 컨텍스트에 포함하지 마세요.

---

4. 사용자 식별 추적

특정 사용자에게만 에러가 발생하는 경우, 그 사용자를 식별할 수 있어야 문제를 재현하고 해결할 수 있습니다.

개념 이해하기

간단히 말해서, Sentry는 에러가 발생한 사용자 정보를 함께 기록할 수 있습니다. 어떤 사용자에게 얼마나 자주 에러가 발생하는지 추적할 수 있습니다.

코드 예제

Sentry.setUser({
  id: "user-123",
  email: "user@example.com",
  username: "john_doe",
  ip_address: "{{auto}}"
});

동작 원리

이것이 하는 일: setUser로 현재 사용자 정보를 등록합니다. 이후 발생하는 모든 에러에 이 사용자 정보가 자동으로 첨부됩니다. 여러분이 로그인 후 이 코드를 실행하면 해당 사용자의 모든 에러를 추적할 수 있습니다.

핵심 정리

핵심 정리: setUser로 사용자 정보를 등록하면 에러를 사용자별로 분석할 수 있습니다.

실전 팁

실전에서는 로그인 시점에 setUser를 호출하고, 로그아웃 시 setUser(null)로 초기화하세요.

---

5. 성능 모니터링

에러만큼이나 중요한 것이 성능입니다. 어떤 기능이 느린지 알고 싶지 않나요?

개념 이해하기

간단히 말해서, Sentry의 트랜잭션 기능은 특정 작업의 실행 시간을 측정합니다. API 호출, 데이터베이스 쿼리, 특정 함수의 성능을 추적할 수 있습니다.

코드 예제

const transaction = Sentry.startTransaction({
  op: "api.call",
  name: "POST /api/orders"
});

await processOrder(orderId);

transaction.finish();

동작 원리

이것이 하는 일: startTransaction으로 성능 측정을 시작하고, finish()로 종료합니다. 시작과 종료 사이의 시간이 자동으로 측정됩니다. 여러분이 이 코드로 감싸면 해당 작업이 얼마나 걸리는지 Sentry에서 확인할 수 있습니다.

핵심 정리

핵심 정리: 트랜잭션으로 중요한 작업의 성능을 측정하고 모니터링합니다.

---

6. 브레드크럼 활용

에러가 발생하기 전에 사용자가 무엇을 했는지 알 수 있다면 디버깅이 훨씬 쉬워집니다.

개념 이해하기

간단히 말해서, 브레드크럼은 에러 발생 전 사용자 행동의 흔적입니다. 클릭, 페이지 이동, API 호출 등을 기록해두면 에러 발생 맥락을 파악할 수 있습니다.

코드 예제

Sentry.addBreadcrumb({
  category: "user-action",
  message: "장바구니에 상품 추가",
  level: "info",
  data: { productId: "P123" }
});

동작 원리

이것이 하는 일: addBreadcrumb로 사용자 행동을 기록합니다. 에러 발생 시 최근 브레드크럼들이 함께 표시되어 에러 발생 전 상황을 재구성할 수 있습니다. 여러분이 중요한 사용자 액션마다 브레드크럼을 남기면 에러 원인을 쉽게 찾을 수 있습니다.

핵심 정리

핵심 정리: 브레드크럼으로 에러 발생 전 사용자 행동을 추적합니다.

실전 팁

실전에서는 너무 많은 브레드크럼을 남기면 오히려 혼란스러우니 중요한 액션만 기록하세요.

---

7. 환경별 설정 분리

개발 중에는 모든 에러를 보고 싶지만, 프로덕션에서는 샘플링이 필요할 수 있습니다.

개념 이해하기

간단히 말해서, 환경에 따라 Sentry 설정을 다르게 가져가는 것이 좋습니다. 개발 환경에서는 에러를 보내지 않거나, 프로덕션에서는 샘플링 비율을 조정할 수 있습니다.

코드 예제

Sentry.init({
  dsn: process.env.SENTRY_DSN,
  environment: process.env.NODE_ENV,
  enabled: process.env.NODE_ENV === "production",
  tracesSampleRate: process.env.NODE_ENV === "production" ? 0.1 : 1.0
});

동작 원리

이것이 하는 일: enabled로 Sentry를 활성화할지 결정하고, tracesSampleRate로 샘플링 비율을 환경별로 설정합니다. 여러분이 이렇게 설정하면 개발 환경에서는 Sentry가 비활성화되고, 프로덕션에서는 10%만 샘플링됩니다.

핵심 정리

핵심 정리: 환경 변수로 환경별 Sentry 설정을 분리합니다.

실전 팁

실전에서는 .env 파일로 환경별 설정을 관리하고, 프로덕션에서는 적절한 샘플링 비율을 찾아 비용을 절감하세요.

---

8. Source Maps 연동

프로덕션 코드는 압축되어 있어서 에러 스택 트레이스를 봐도 어디서 발생했는지 알기 어렵습니다.

개념 이해하기

간단히 말해서, Source Maps는 압축된 코드와 원본 코드를 매핑해줍니다. Sentry에 Source Maps를 업로드하면 에러 위치를 정확하게 알 수 있습니다.

코드 예제

// package.json scripts
{
  "build": "webpack --mode production",
  "sentry:sourcemaps": "sentry-cli sourcemaps upload --org=your-org --project=your-project ./dist"
}

동작 원리

이것이 하는 일: 빌드 후 sentry-cli로 Source Maps를 Sentry에 업로드합니다. 에러 발생 시 Sentry가 압축된 코드 위치를 원본 코드 위치로 변환해줍니다. 여러분이 이 과정을 거치면 app.min.js:1:2345 같은 위치 대신 실제 파일과 라인 번호를 볼 수 있습니다.

핵심 정리

핵심 정리: Source Maps 업로드로 압축된 코드에서도 정확한 에러 위치를 파악합니다.

실전 팁

실전에서는 CI/CD 파이프라인에 Source Maps 업로드를 자동화하고, 보안을 위해 업로드 후 공개 서버에서는 Source Maps를 제거하세요.

---

마치며

오늘은 Sentry 실전 프로젝트 에러 추적의 핵심 개념들을 함께 살펴보았습니다.

처음에는 어렵게 느껴질 수 있지만, 실제 프로젝트에서 하나씩 적용해보면서 익숙해지시길 바랍니다. 이론만 알고 있기보다는 직접 코드를 작성하고 실행해보는 것이 가장 빠른 학습 방법입니다.

질문이나 궁금한 점이 있다면 언제든 댓글로 남겨주세요. 함께 성장하는 개발자가 되어봅시다!

관련 태그

#Sentry #ErrorTracking #Monitoring #Performance #SourceMaps