[Sentry][프론트엔드] source map을 올렸는데 스택트레이스가 안 풀릴 때 확인 순서

IT 리서치 노트

[Sentry][프론트엔드] source map을 올렸는데 스택트레이스가 안 풀릴 때 확인 순서

Sentry에 source map을 올렸는데도 스택트레이스가 난독화된 채로 남는 경우가 있다. 이때 단순히 업로드가 실패했다고 보기보다, 배포된 JS와 업로드한 sourcemap이 정확히 어떻게 연결되는지부터 봐야 한다. 현재 Sentry JavaScript 문서는 Debug ID 기반 연결을 기본으로 설명한다. 따라서 build 산출물에 Debug ID가 들어갔는지, 업로드 시점이 배포와 맞는지, 이벤트가 같은 릴리즈 산출물을 보고 있는지를 순서대로 확인해야 한다.

목차

1. 개요
2. 어디서 막히는가
3. 실제로 해결하는 순서
4. 화면과 출력으로 확인하기
5. 주의할 점
6. 결론
7. 참고 링크

1. 개요

Sentry에 source map을 올렸는데도 스택트레이스가 난독화된 채로 남는 경우가 있다. 이때 단순히 업로드가 실패했다고 보기보다, 배포된 JS와 업로드한 sourcemap이 정확히 어떻게 연결되는지부터 봐야 한다.

현재 Sentry JavaScript 문서는 Debug ID 기반 연결을 기본으로 설명한다. 따라서 build 산출물에 Debug ID가 들어갔는지, 업로드 시점이 배포와 맞는지, 이벤트가 같은 릴리즈 산출물을 보고 있는지를 순서대로 확인해야 한다.

• 이 글은 현재 공식 문서와 공개 도움말을 다시 확인한 뒤 정리했다.
• 설정 경로, 실패 지점, 검증 결과를 분리해서 읽으면 바로 실행에 옮기기 쉽다.
• 실제 운영에서는 권한, 비용, 배포 로그를 함께 봐야 같은 실수를 반복하지 않는다.

2. 어디서 막히는가

문제가 길게 보이더라도 실제 막힘은 몇 가지 패턴으로 모인다. 아래 증상 중 하나라도 보이면 설정값, 요청값, 실행 결과를 분리해서 기록하는 쪽이 빠르다.

• Sentry CLI upload는 성공했는데 이벤트 화면에서는 여전히 minified frame만 보인다.
• 배포된 JS에는 Debug ID가 없거나 sourcemap 주석이 잘려 있다.
• 릴리즈 이름만 맞추고 실제 build 산출물 버전은 달라 연결이 안 된다.
• CDN 캐시 때문에 새 JS와 옛 sourcemap 조합이 한동안 섞인다.

여기서 가장 흔한 실수는 증상만 보고 권한을 넓히거나 비용 플랜을 올리거나, 별도 로그 없이 다시 시도하는 것이다. 그러면 당장은 지나가도 다음 배포나 다음 운영 시간대에 같은 문제가 다시 나온다.

따라서 먼저 실제 값과 공식 기준이 어떻게 다른지 좁히고, 그 다음에 클릭, 입력, 실행, 저장 순서를 하나씩 재현해야 한다. 이 순서가 있어야 팀원끼리 같은 결과를 볼 수 있다.

문제정의 단계에서는 오류 문구 한 줄만 보는 대신, 어떤 메뉴에서 확인했고 어떤 필드가 비어 있었는지, 어떤 응답 상태가 먼저 나타났는지까지 적어두는 편이 좋다. 그래야 해결 단계에서 값을 바꾼 뒤에도 같은 기준으로 성공과 실패를 다시 비교할 수 있다.

특히 비용 문제나 권한 문제는 겉으로는 비슷하게 보여도 원인이 다르다. 청구 화면, 콘솔 설정, 배포 로그, 브라우저 요청, CLI 출력 가운데 무엇이 기준 화면인지 먼저 정하고 그 화면을 중심으로 확인해야 엉뚱한 메뉴를 오래 헤매지 않는다.

3. 실제로 해결하는 순서

아래 순서는 메뉴를 열고 값을 확인하고 결과를 다시 보는 실무용 순서다. 한 번에 모두 바꾸지 말고 한 단계씩 적용한 뒤 출력과 화면을 확인하는 편이 안전하다.

1. 배포된 JS 파일에 Debug ID가 있는지 먼저 확인한다.
2. Sentry CLI 업로드 로그에서 어떤 파일과 sourcemap이 연결됐는지 본다.
3. 이벤트가 발생한 배포 버전과 sourcemap 업로드 버전이 같은지 맞춘다.
4. 배포 후 캐시 무효화와 새 에러 재발생까지 확인한다.

안전한 예제 코드

npx sentry-cli sourcemaps inject ./dist
npx sentry-cli sourcemaps upload ./dist \
  --org YOUR_ORG \
  --project YOUR_PROJECT

# 배포 전에 dist JS 파일 마지막 부분에 Debug ID가 들어갔는지 확인한다.

CLI 예제는 흐름만 보여준다. 실제 조직명, 프로젝트명, 토큰은 공개 글에 넣지 않는다.

예제 코드는 흐름만 남겼다. 실제 토큰, 계정, 내부 서버 주소, 비공개 저장소 이름은 placeholder로 바꾸고 서버 환경변수나 보안 저장소로 분리한다.

중요한 점은 설정 변경 직후 바로 다음 단계로 넘어가지 않는 것이다. 각 단계마다 어떤 메뉴를 클릭했고, 어떤 값을 입력했고, 어떤 출력이 돌아왔는지 짧게라도 기록해야 한다. 그래야 실패했을 때 마지막으로 바뀐 값이 무엇인지 빠르게 되짚을 수 있다.

또한 해결 절차는 한 번 성공했다고 끝나지 않는다. 같은 절차를 다른 환경이나 다른 브랜치, 다른 계정에서도 다시 실행해 보고 결과가 같은지 확인해야 한다. 운영 환경과 로컬 환경의 URL, 권한, 캐시, 플랜, 리전 차이가 숨어 있으면 여기서 드러나는 경우가 많다.

4. Sentry 화면에서 source map 문제 좁히기

source map을 업로드했는데도 스택트레이스가 풀리지 않으면 업로드 여부만 보면 부족하다. 아래 화면에서는 sourcemap 설정, artifact 업로드, Debug ID, CLI 업로드 순서를 함께 확인한다.

먼저 Source Maps 문서에서 문제의 범위를 확인한다. 빌드 산출물, sourcemap 파일, Sentry release 또는 Debug ID 연결이 같은 흐름 안에 있어야 한다.

Source Maps 문서에서는 읽기 어려운 JavaScript stack trace를 원본 코드로 연결하는 기본 목적을 확인한다.

업로드 섹션에서는 빌드 후 어느 시점에 sourcemap을 올리는지 본다. 배포보다 늦게 올라가면 먼저 발생한 오류는 원본 코드와 연결되지 않을 수 있다.

Uploading Source Maps 화면에서는 배포 파이프라인 안에서 sourcemap 업로드가 들어갈 위치를 확인한다.

문제가 난 뒤에는 artifact가 실제로 올라갔는지 먼저 확인한다. 파일이 없으면 release 이름이나 Debug ID를 보기 전에 업로드 단계부터 고쳐야 한다.

Verify Artifacts Are Uploaded 화면은 Sentry에 sourcemap 산출물이 도착했는지 확인하는 첫 단계다.

Debug ID 방식에서는 번들 파일과 sourcemap의 연결 정보가 중요하다. 빌드 산출물에 주입된 값이 없으면 업로드가 성공해도 매핑이 되지 않는다.

Debug ID injection 설명은 번들 파일과 sourcemap이 같은 식별자로 연결되는지 확인할 때 본다.

마지막으로 CLI 업로드 문서를 확인한다. 직접 업로드하는 팀은 조직, 프로젝트, auth token, 빌드 경로가 CI 환경에서 모두 맞는지 확인해야 한다.

Sentry CLI 화면에서는 artifact bundle 업로드 단계와 배포 파이프라인의 연결 지점을 확인한다.

이 순서로 확인하면 문서의 기능 설명, 설정 범위, 제한 조건, 실제 운영 판단 기준을 한 번에 대조할 수 있다. 화면에서 먼저 볼 항목을 정한 뒤 코드나 콘솔 설정을 수정해야 같은 문제가 반복되지 않는다.

5. 주의할 점

설정을 맞췄더라도 운영에서는 다시 틀어지는 지점이 있다. 아래 항목은 배포 직전과 배포 직후에 꼭 다시 점검할 부분이다.

• 배포 후 다시 오류를 내보지 않으면 수정이 실제로 반영됐는지 알기 어렵다.
• CDN이 이전 JS를 계속 서빙하면 sourcemap 업로드만 다시 해도 해결되지 않는다.
• 릴리즈 이름이 자동으로 바뀌는 파이프라인은 이벤트-맵 매칭을 깨뜨리기 쉽다.

특히 권한, 비용, 캐시, 재시도 정책은 한 번 맞춘 뒤에도 환경이 바뀌면 다시 확인해야 한다. 문서가 바뀌었는지, 콘솔 기본값이 달라졌는지, 팀의 배포 방식이 바뀌었는지도 같이 본다.

6. 결론

업로드가 됐어도 Debug ID가 없으면 가장 먼저 build 파이프라인을 본다.

• 업로드가 됐어도 Debug ID가 없으면 가장 먼저 build 파이프라인을 본다.
• 이벤트 버전과 배포 버전이 다르면 캐시나 릴리즈 관리부터 정리한다.
• sourceMappingURL만 믿지 말고 실제 배포 파일 내용을 직접 본다.

핵심은 추상적인 '좋은 설정'을 찾는 것이 아니라, 지금 내 서비스에서 어떤 값과 어떤 출력이 정답인지 빠르게 확인하는 것이다. 이 글의 순서대로 문서, 설정, 실행 결과를 묶어 보면 같은 문제를 다시 만났을 때 훨씬 빨리 끝낼 수 있다.

7. 참고 링크

1. https://docs.sentry.io/platforms/javascript/sourcemaps/
2. https://docs.sentry.io/platforms/javascript/sourcemaps/troubleshooting_js/
3. https://docs.sentry.io/platforms/javascript/sourcemaps/uploading/cli/