프론트엔드 에러 모니터링: Sentry 소스맵과 릴리스 추적

배포 후 사용자에게서 "화면이 하얗게 됐다"는 제보가 들어오면, 콘솔 로그만으로는 원인을 찾기 어렵다. 사용자의 브라우저에서 무슨 일이 일어났는지, 어느 배포본에서 시작됐는지 알 수 없기 때문이다. 에러 모니터링을 붙이면 이 문제가 해결되지만, 소스맵 업로드와 릴리스 태깅을 제대로 하지 않으면 스택이 압축된 코드로만 남아 쓸모가 없다. 이 글은 프론트엔드 오류 추적을 실전에서 쓸 수 있게 만드는 설정을 정리한다.

에러 모니터링이 없을 때의 문제

모니터링이 없으면 다음을 알 수 없다.

• 오류가 몇 명에게, 어떤 브라우저에서 발생했는지.
• 어느 릴리스부터 새로 생긴 오류인지.
• 같은 오류가 여러 형태로 보고되는지, 하나의 근본 원인인지.
• 오류가 사용자 흐름을 실제로 막았는지.

Sentry 같은 도구는 이 정보를 수집한다. 다만 수집 자체보다 "어떻게 묶고 어떻게 거르는가"가 유용성을 좌우한다.

소스맵 업로드와 릴리스 태깅

프로덕션 코드는 압축·난독화되므로, 원본 소스로 스택을 복원하려면 빌드 시 소스맵을 생성해 업로드해야 한다. Sentry Next.js 소스맵 가이드에 따르면 프레임워크 통합 마법사(@sentry/wizard)를 쓰거나 빌드 설정에 SENTRY_AUTH_TOKEN과 release 식별자를 주입해 빌드 단계에서 소스맵 업로드를 자동화할 수 있다.

# Next.js 예시: 빌드 시 소스맵 생성·업로드
# sentry.client.config / next.config 설정에서
# release 값을 빌드 환경과 동일하게 주입
SENTRY_AUTH_TOKEN=*** npm run build

업로드된 소스맵은 공개 서빙되면 안 된다. 배포 산출물에서 .map 파일을 제거하거나 접근을 막아, 원본 코드가 외부에 노출되지 않게 한다.

빌드·환경별 릴리스 이름 규칙

릴리스 이름은 커밋 해시나 버전 태그처럼 빌드마다 고유하고 추적 가능한 값으로 정한다. 환경(프로덕션·스테이징)도 태그로 구분해야 스테이징 오류가 프로덕션 지표를 오염시키지 않는다. 규칙이 사람마다 다르면 "이 오류가 어느 배포본에서 났는지"를 연결할 수 없다.

오류 그룹화와 노이즈 줄이기

같은 원인의 오류가 여러 메시지로 흩어지면 우선순위를 정할 수 없다. 스택과 메시지를 기준으로 자동 그룹화되지만, 동적 값이 메시지에 섞이면 그룹이 쪼개진다. 이런 경우 정규화하거나 사용자 정의 그룹화 키를 지정한다. 반대로 서로 다른 원인이 한 그룹으로 묶이면 그룹화 키를 조정한다. 또 잡을 필요 없는 오류(브라우저 확장, 취소된 요청, 예상된 검증 실패)는 필터로 제외해 신호 대 잡음을 높인다.

개인정보·민감 정보 필터링

오류 이벤트에는 URL, 폼 값, 헤더가 포함될 수 있다. 이벤트를 전송하기 전에 민감 필드를 지우는 훅을 둔다. 토큰, 이메일, 주민번호 형태의 값이 로그에 남으면 그것 자체가 보안 사고가 된다.

beforeSend(event) {
  if (event.request?.headers) {
    delete event.request.headers["authorization"];
  }
  return event;
}

또한 샘플링 비율을 정해 이벤트 폭주를 막고, 성능 추적은 필요한 비율로만 켠다. 전부 수집하면 비용과 노이즈가 함께 늘어난다.

릴리스와 오류 회귀 확인

릴리스 태깅이 되어 있으면 "이번 배포에서 새로 생긴 오류"를 골라낼 수 있다. 배포 직후 일정 시간 동안 새 오류와 급증한 오류를 확인하는 루틴을 만든다. 수집된 스택 트레이스와 로그에서 최초 원인을 좁히고 민감값을 가리는 절차는 AI로 에러 로그 디버깅하기와 함께 적용하면 원인 파악 시간을 줄일 수 있다. Next.js 환경이라면 서버·클라이언트 경계에서 발생하는 오류를 구분해 보는 것이 중요하며, 이는 App Router 서버 액션 오류 처리 글의 분류와 연결된다.

사용자에게 보이는 오류와 그렇지 않은 오류 구분

모니터링 도구에 들어오는 모든 이벤트가 사용자에게 영향을 준 것은 아니다. 백그라운드 요청 실패나 재시도로 복구된 오류는 사용자가 인지하지 못할 수 있다. 반대로 예외로 잡히지 않고 조용히 실패하는 경우도 있다. 그래서 오류 발생 건수뿐 아니라 어떤 사용자 흐름에서 발생했는지, 핵심 경로(로그인·결제·저장)에서 발생했는지를 함께 기록한다. 오류 경계로 컴포넌트 트리를 감싸 렌더링 실패가 전체 화면을 지우지 않게 하고, 실패 시 대체 UI와 재시도 경로를 제공한다. 이렇게 하면 "오류가 났다"를 넘어 "사용자가 무엇을 못 했는가"로 우선순위를 정할 수 있다. 이벤트에 사용자 식별자를 붙일 때는 개인정보 정책을 따르고, 세션 단위로 묶어 한 사용자에게 반복되는 문제를 찾아낸다.

릴리스 회귀를 볼 때는 오류율의 절대값보다 변화량을 본다. 트래픽이 적은 시간대에 배포하면 오류 수 자체는 작아 보일 수 있으므로, 세션 대비 오류 비율이나 영향 사용자 비율로 비교한다. 배포 후 일정 시간을 관찰 구간으로 두고 그 구간의 신규 오류가 0에 가까워지면 안정으로 판단하는 규칙을 정해 두면 판단이 흔들리지 않는다.

또한 오류 이벤트의 심각도와 사용자 영향을 함께 보면, 같은 서버 오류라도 결제 실패와 통계 위젯 실패를 구분해 대응 우선순위를 정할 수 있다. 알림 규칙도 이 구분을 반영해 핵심 경로의 오류만 즉시 호출하고, 나머지는 일일 요약으로 묶는 편이 지속 가능하다.

알림과 배포 직후 점검 순서

모든 오류에 알림을 보내면 곧 무시된다. 배포 파이프라인과 연결해 다음 4단계 순서로 점검 루틴을 고정한다.

1. 빌드 단계에서 SENTRY_AUTH_TOKEN으로 소스맵을 업로드하고 배포 산출물에서 .map 파일을 삭제한다.
2. sentry.client.config.ts의 ignoreErrors와 beforeSend 훅에서 브라우저 확장 오류와 authorization 헤더를 제거한다.
3. 배포 후 30분 동안 신규 이슈(New Issues)와 세션 대비 오류율(Crash Free Sessions) 변화를 확인한다.
4. 핵심 경로(결제·로그인) 오류만 즉시 호출 알림으로 연결하고 나머지는 일일 요약으로 분리한다.

영향도(발생 사용자 수, 핵심 경로 여부, 신규 여부)를 기준으로 알림 조건을 정하고, 담당과 대응 시간을 문서화한다. 영향도(발생 사용자 수, 핵심 경로 여부, 신규 여부)를 기준으로 알림 조건을 정하고, 담당과 대응 시간을 문서화한다. 알림이 울렸을 때 "누가, 어디서, 무엇을 확인하는가"가 정해져 있지 않으면 모니터링은 대시보드 장식으로 끝난다.