Develop
Sentry Next.js 에러 모니터링 완벽 가이드 — 운영 중 오류를 실시간으로 추적하는 방법
운영 배포 후 유저가 겪는 에러를 실시간으로 포착하고, 난독화된 프로덕션 코드 배후의 실제 원본 소스 코드 스택 트레이스를 확인하기 위해 Next.js에 Sentry 에러 모니터링을 연동하는 최적의 셋업 가이드입니다.
- ·Sentry는 에러 발생 시 스택 트레이스, 사용자 환경, 브라우저 정보, 직전 이벤트 등 에러 재현에 필요한 맥락 정보를 자동으로 수집한다
- ·소스맵을 Sentry에 업로드하면 압축된 프로덕션 코드 대신 원본 소스 파일과 줄 번호로 스택 트레이스를 확인할 수 있다
- ·Sentry Performance는 트랜잭션 추적과 Web Vitals 측정으로 성능 문제도 모니터링할 수 있다
- ·Sentry의 무료 플랜은 월 5,000건의 에러를 처리하며 소규모 프로젝트에 충분하다
예전에 유저로부터 '결제 화면에서 버튼을 눌렀는데 반응이 없어요'라는 신고를 받고 땀을 뻘뻘 흘린 적이 있습니다. 로컬에서는 재현이 도무지 되지 않고, 유저의 기기나 브라우저 정보도 없어 원인을 찾느라 꼬박 이틀을 날렸죠. 이 사건 이후 Sentry를 부랴부랴 넥스트 프로젝트에 이식했습니다. 놀랍게도 Sentry가 에러 당시의 정확한 사용자 환경 사양과 에러 직전에 클릭했던 사용자 인터랙션 경로(Breadcrumbs)를 한눈에 보여주어, 사소한 iOS 사파리 호환성 버그였다는 걸 단 5분 만에 찾아 해결했습니다. 운영 서비스에 Sentry는 단순 선택이 아니라 필수 가디언이더군요.
1. Sentry Wizard와 런타임별 설정
Next.js에 Sentry 에러 모니터링 위자드로 손쉽게 연동 설정하는 방법
Sentry 연동을 수동으로 하려다 보면 클라이언트, 서버, 그리고 Edge(미들웨어) 환경 각각의 에러 캡처 라이프사이클을 가로채야 해서 굉장히 피로합니다. 다행히 Sentry는 npx @sentry/wizard@latest -i nextjs 라는 원클릭 마법사 툴을 제공합니다. 이 명령어를 실행하면 본인의 Sentry 계정 로그인부터 전용 DSN 주소 셋업, 그리고 sentry.client.config.ts, sentry.server.config.ts, sentry.edge.config.ts 같은 설정 뼈대 파일 생성까지 논스톱으로 자동 구성해 줍니다. 개발자는 그저 생성된 파일 내부에 트래픽 유입 강도에 맞게 샘플링 레이트(tracesSampleRate) 수치만 적절히 다듬어 주면 됩니다.
2. 소스맵 업로드와 보안 무결성
Next.js 빌드 시 Sentry 소스맵을 비공개 업로드하여 에러 스택 트레이스 가독성 높이기
프로덕션으로 빌드된 Next.js 파일은 코드 크기를 줄이기 위해 난독화 및 압축 과정을 거칩니다. 이 때문에 기본 에러 로그는 의미 없는 한 줄의 외계어처럼 보여 원인 규명이 불가능하죠. 이를 디버깅 가능한 예쁜 텍스트로 보려면 빌드 타임에 생성된 소스맵(Source Map) 파일이 필요합니다. @sentry/nextjs 패키지는 빌드 과정에서 소스맵을 자동으로 Sentry 비공개 서버에 전송해 줍니다. 단, 이 소스맵이 일반 브라우저 유저에게도 노출되면 내가 짠 소스 코드가 외부에 100% 털리는 보안 취약점이 되므로, next.config.js 내에서 productionBrowserSourceMaps 옵션은 필히 false로 격리 보존해야 보안 무결성이 유지됩니다.
Sentry로 Next.js 운영 환경 에러를 빠르게 분류하고 대응하는 방법
Sentry 대시보드로 수집된 에러들은 이슈(Issue) 단위로 자동 군집 분석되어 목록에 등재됩니다. 한 에러가 몇 번 발생했고 몇 명의 방문자가 튕김을 겪었는지 통계화되죠. 각 이슈를 클릭해 세부 조회를 시작하면 에러 당시의 마크업 덤프와 콜스택은 물론, 유저가 마우스로 무엇을 딛고 API 통신을 발송했는지 알려주는 브레드크럼(Breadcrumbs) 흐름이 정렬되어 표시됩니다. 여기에 추가로 로깅 시점 유저 정보를 매핑해두면 어떤 계정 유저에게 장애가 터졌는지 즉시 식별하여 실시간 고객 대응 전술을 구동할 수 있습니다.
3. 이슈 트래킹과 노이즈 필터링
Sentry 에러 모니터링 대시보드에서 크롤러 노이즈와 중복 에러 필터링하는 법
Sentry를 무턱대고 켜두면 온갖 크롤러 봇이 던지는 쓰레기 요청 에러나 브라우저 불법 확장 프로그램(AdBlock 등)이 뿜어내는 잡음 로그가 대시보드를 어지럽힙니다. 이는 유료 플랜의 쿼터 비용 낭비로 이어지죠. 이를 막으려면 beforeSend 콜백 메서드를 활성화하여 특정 네트워크 에러나 확장 프로그램 발 에러 메시지는 서버로 발송하지 않고 드롭(Drop)시키는 필터링 가드를 구축해야 합니다. 또한 사용자 식별이 필요한 유저 도메인에서는 Sentry.setUser() 헬퍼를 심어두어, 장애 발생 시 어떤 고객이 직접 피해를 보았는지 핀포인트로 식별하여 즉각 파악하고 안내할 수 있는 고급 대응 태세까지 완성할 수 있습니다.
자주 묻는 질문
무료 플랜 쿼터가 다 차면 에러 기록 수집이 완전히 끊기나요?+
Sentry Developer 무료 플랜은 매월 5,000건의 에러 이벤트를 무상 수집해 줍니다. 만약 한도를 초과하면 해당 월의 남은 기간 동안은 수집이 중단되며 다음 결제 주기에 리셋됩니다. 트래픽이 많다면 tracesSampleRate를 0.05(5%) 등으로 낮춰 성능 추적 비중을 다이어트하는 조율이 요긴합니다.
개발 로컬 환경(development)에서도 Sentry 로그가 쌓여서 쿼터가 낭비돼요.+
Sentry 초기화 코드 내에 enabled: process.env.NODE_ENV === 'production' 조건을 추가해 두거나, 환경별 변수를 로컬 .env.local 에서는 Sentry DSN 값을 비워두도록 세팅해 놓으면 로컬 삽질 로그가 운영 대시보드로 무단 방출되는 것을 쉽게 차단할 수 있습니다.
관련 글
Next.js App Router에서 Google Analytics 4 설정하는 방법 — 페이지뷰와 이벤트 추적까지
UA 종료 후 GA4로 전환한 환경에서 Next.js App Router에 Google Analytics 4를 연동하는 방법을 정리했습니다. next/script 로드, usePathname 페이지뷰 추적, 커스텀 이벤트까지 다룹니다.
Next.js App Router 메타데이터 완벽 가이드 — generateMetadata로 SEO 최적화하는 방법
Next.js App Router에서는 Head 컴포넌트 대신 Metadata API를 써야 합니다. layout.tsx 전역 설정부터 포스트별 generateMetadata, robots.ts와 sitemap.ts까지 가볍게 정리해 보았습니다.
GitHub Actions로 Node.js CI/CD 파이프라인을 구성하는 방법 — 빌드부터 자동 배포까지
Jenkins 없이 GitHub 저장소 안에서 CI/CD를 완결하고 싶다면 GitHub Actions가 가장 빠른 선택이다. workflow 파일 작성부터 Secrets 관리, SSH 배포까지 순서대로 정리했다.