[Sentry][프론트엔드] Debug ID가 번들에 없을 때 source map이 안 풀리는 이유

IT 리서치 노트

[Sentry][프론트엔드] Debug ID가 번들에 없을 때 source map이 안 풀리는 이유

Sentry에서 source map을 올렸는데도 프론트엔드 스택트레이스가 계속 난독화되어 보이면, 최근에는 release 이름보다 Debug ID 쪽을 먼저 봐야 하는 경우가 많다. 2026년 6월 25일 기준 Sentry 공식 문서는 배포된 JavaScript에 Debug ID가 없으면 업로드된 source map이 있어도 매칭할 수 없다고 설명한다. 이 글은 Debug ID가 실제 번들에 없는 상황을 기준으로, build와 inject와 upload와 deploy를 어떤 순서로 나눠 봐야 하는지 정리한 것이다.

목차

1. 개요
2. 어디서 실제로 막히는가
3. 실무에서 적용하는 순서
4. 공식 문서와 예시 화면으로 확인하기
5. 주의사항과 리스크
6. 결론
7. 참고 링크

1. 개요

결론부터 말하면 Debug ID 문제는 'source map 업로드 실패'라기보다 '최종 배포 번들에 식별자가 없거나 다른 산출물이 배포됐다'는 경우가 많다. 그래서 build 디렉터리, Debug ID inject 단계, sentry-cli upload 단계, 최종 deploy 파일을 따로 확인해야 한다. 특히 배포 번들 안에 Debug ID 흔적이 없다면 릴리스 이름이 맞더라도 Sentry가 원본과 난독화 파일을 연결하지 못한다.

이미 source map 일반 점검 글이 경로와 업로드 축을 설명했다면, 이번 글은 그중에서도 Debug ID 누락 상황만 따로 좁혀 보는 후속편이다. 빌드 산출물 검증을 CI 관점으로 보는 감각은 Trusted Publishing 글과도 닿아 있다.

2. 어디서 실제로 막히는가

실무에서는 보통 세 가지 패턴으로 나타난다. 첫째, sentry-cli sourcemaps upload는 성공했는데 Sentry UI에서는 계속 minified stack trace만 나온다. 둘째, 로컬 build 디렉터리에는 Debug ID가 보이는데 CDN에 올라간 최종 파일을 내려받아 보면 그 흔적이 없다. 셋째, bundler 또는 배포 스크립트가 inject 후 파일을 다시 복사하거나 압축하면서 실제 서비스 파일이 바뀐다.

이 문제를 release 이름이나 배포 버전 문제로만 보면 시간이 길어진다. 최신 Sentry 문서는 Debug ID 기반 소스 매핑을 기본 흐름으로 설명하고 있고, troubleshooting 문서도 '배포된 JavaScript에 Debug IDs가 없다'는 문장을 대표 증상으로 내세운다. 즉 업로드 성공 여부보다, 최종 실행 파일 안에 식별자가 살아 있느냐가 더 중요하다.

또 CI 파이프라인이 길수록 산출물 교체 지점이 늘어난다. 예를 들어 build 후 Debug ID를 inject했더라도, 그 뒤 별도 최적화 단계가 새 번들을 만들거나, deploy 단계가 다른 폴더를 올리면 Debug ID가 빠진 파일이 서비스될 수 있다. 그래서 release 화면과 CLI 로그만 보지 말고 실제 서비스 파일을 다시 내려받아 비교해야 한다.

• 증상: source map 업로드는 성공했는데 스택트레이스가 계속 난독화된다.
• 실패: Debug ID inject 이전 파일과 이후 파일을 구분하지 않는다.
• 막힘: 로컬 build 폴더와 실제 배포 파일이 다른데도 같은 것으로 가정한다.
• 누락: CDN에서 다시 받은 번들에 Debug ID가 있는지 확인하지 않는다.

증상	먼저 볼 곳	판단 기준
업로드는 성공했는데 stack trace가 안 풀린다	배포 번들 파일	Debug ID가 실제 파일에 있는지 본다
로컬에서는 괜찮은데 운영에서 안 된다	CDN에서 다시 받은 산출물	배포 경로가 바뀌지 않았는지 본다
릴리스 이름만 계속 손본다	inject와 upload 순서	Debug ID 주입이 먼저 끝났는지 본다

3. 실무에서 적용하는 순서

점검 순서는 네 단계가 가장 짧다. 먼저 최종 배포 대상 디렉터리를 확인한다. 다음으로 그 디렉터리에 Debug ID가 inject됐는지 grep이나 파일 비교로 본다. 세 번째로 같은 디렉터리를 sentry-cli sourcemaps upload에 넘겼는지 로그를 확인한다. 마지막으로 운영 CDN 또는 서버에서 실제 파일을 다시 받아 Debug ID가 남아 있는지 검증한다.

1. 최종 배포 디렉터리가 어디인지 먼저 고정한다.
2. 그 디렉터리에 Debug ID가 inject됐는지 확인한다.
3. 같은 디렉터리를 sentry-cli upload 대상으로 썼는지 본다.
4. 운영 파일을 다시 받아 Debug ID가 남아 있는지 확인한다.

여기서 중요한 것은 inject와 deploy 사이에 파일을 바꾸는 단계가 있는지다. 번들 합치기, 압축, 해시 변경, 정적 파일 복사, CDN 업로드 전 변환 같은 단계가 하나라도 있으면 Debug ID가 빠질 수 있다. 그래서 CI 단계별 아티팩트 경로를 고정하고, upload 직전과 deploy 직전 파일을 같은 해시 또는 같은 grep 결과로 비교하는 편이 좋다.

운영 메모 예시

build_dir=dist/assets
inject_done=true
upload_target=dist/assets
deploy_target=deploy-bundle/assets
verify_cdn=true
grep_debug_id=true

이 구조로 남겨 두면 문제 재발 때도 배포 라인 어디서 어긋났는지 빠르게 좁혀진다. 일반 source map 문제와 달리 Debug ID 문제는 '최종 파일'이 기준 화면이라는 점을 잊지 않는 편이 좋다.

4. 공식 문서와 예시 화면으로 확인하기

첫 화면은 Sentry JavaScript source map troubleshooting 문서의 대표 증상이다. 여기서는 배포된 JavaScript에 Debug ID가 없으면 Sentry가 업로드된 source map과 번들을 매칭하지 못한다고 바로 적고 있다.

Sentry는 배포된 번들에 Debug ID가 없으면 source map을 찾아도 적용하지 못한다고 설명한다.

즉 업로드 성공 로그만 보고 끝내면 안 된다. 최종 CDN 또는 서버에 올라간 실제 번들 파일 안에 Debug ID가 살아 있는지까지 확인해야 한다는 뜻이다.

두 번째 자료는 Debug ID 자체가 무엇인지 설명하는 페이지다. Sentry는 Debug ID를 변환된 JavaScript 파일과 대응 source map을 연결하는 고유 식별자로 정의한다.

Debug ID는 변환된 JavaScript 파일과 source map을 연결하는 전역 고유 식별자다.

이 정의를 이해하면 release 이름만 맞췄는데도 스택트레이스가 안 풀리는 이유가 보인다. 예전 릴리스 기반 매칭 감각만으로는 최신 Debug ID 흐름을 설명하기 어렵다.

세 번째 화면은 CLI 업로드 가이드다. 여기서는 먼저 아티팩트에 Debug ID를 inject하고, 그 뒤 업로드하라는 순서를 분명히 적고 있다.

CLI 가이드는 Debug ID를 inject한 뒤 source map과 번들을 업로드하는 순서를 제시한다.

이 순서가 뒤집히면 source map 업로드는 되어도 최종 배포 번들에는 Debug ID가 없을 수 있다. 배포 파이프라인에서 build, inject, upload, deploy 순서를 분리해 남겨야 하는 이유다.

번들 파일을 직접 보면 더 빨리 좁혀진다. inject가 안 된 번들에는 Sentry가 찾는 식별자 조각이 아예 없고, inject가 된 뒤에는 관련 메타데이터가 들어간다.

배포 번들 스니펫을 비교하면 Debug ID 주입 전후 차이를 바로 확인할 수 있다.

실무에서는 minified bundle의 첫 몇 줄이나 마지막 몇 줄만 봐도 신호가 잡힌다. CI가 성공했다고 해서 최종 산출물이 바뀌었다고 가정하면 안 된다.

명령 순서도 한 화면에 고정해 두는 편이 좋다. Debug ID 관련 이슈는 보통 사람마다 어느 단계까지 했는지 기억이 달라서, 실제 명령 이력으로 맞추는 편이 빠르다.

<code>sentry-cli sourcemaps inject</code>와 <code>upload</code> 순서를 남기면 어떤 단계가 빠졌는지 바로 보인다.

여기서 핵심은 upload 전에 inject가 끝났는지, 그리고 deploy 대상 디렉터리가 inject된 파일을 실제로 사용했는지다. 빌드 산출물을 다시 복사하거나 후처리하면 Debug ID가 빠질 수 있다.

마지막 자료는 source map이 안 풀릴 때 가장 먼저 나눠 봐야 할 체크리스트다. release 이름 문제인지, Debug ID 주입 누락인지, 업로드 경로 문제인지 한꺼번에 섞이면 계속 같은 배포를 반복하게 된다.

release, inject, upload, deploy 네 단계를 분리한 체크리스트다.

이 표를 기준으로 보면 post 33의 일반 source map 점검보다 한 단계 더 구체적으로 Debug ID 축을 분리할 수 있다. CI 산출물 검증 감각은 npm provenance 확인 글과도 닿아 있다.

5. 주의사항과 리스크

첫 번째 리스크는 CLI 업로드 성공 메시지를 최종 성공으로 착각하는 것이다. 두 번째 리스크는 inject된 파일이 아닌 다른 파일을 배포해 놓고 릴리스 이름만 계속 수정하는 것이다. 세 번째 리스크는 CDN이나 빌드 후처리 단계가 Debug ID가 들어간 주석 또는 메타데이터를 지웠는데도 그 사실을 로그로 남기지 않는 것이다.

운영 전에는 디버그용 한 파일을 골라 로컬 산출물, upload 대상, 운영 CDN 파일을 세 군데서 모두 비교해 보는 편이 좋다. 한 번만 이 루틴을 만들어 두면 다음 프레임워크나 bundler로 옮겨도 재사용할 수 있다.

• Debug ID 문제는 release 이름보다 최종 번들 파일 확인이 더 중요하다.
• inject 이후 파일을 다시 만드는 후처리 단계가 있으면 재검증이 필요하다.
• 운영 CDN 파일을 다시 내려받아 보는 검증이 가장 확실하다.

6. 결론

Sentry에서 Debug ID가 번들에 없을 때 source map이 안 풀리는 이유는 대개 업로드 실패가 아니라 최종 서비스 파일 불일치다. build, inject, upload, deploy 네 단계를 따로 확인하고, 운영 번들에 Debug ID가 실제로 남아 있는지 보면 원인을 훨씬 빨리 좁힐 수 있다.

• CLI 성공보다 운영 번들 안 Debug ID 존재 여부를 먼저 본다.
• inject와 deploy 사이 파일 교체 단계를 따로 기록한다.
• CDN에서 다시 받은 파일 검증이 마지막 확인 포인트다.

7. 참고 링크

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