[Sentry][프론트엔드] sourcemap은 올렸는데 CDN 경로나 해시 파일명 때문에 매칭이 안 될 때 rewriteFrames와 event lookup을 같이 보는 법

IT 리서치 노트

[Sentry][프론트엔드] sourcemap은 올렸는데 CDN 경로나 해시 파일명 때문에 매칭이 안 될 때 rewriteFrames와 event lookup을 같이 보는 법

Sentry sourcemap을 올렸는데도 일부 이벤트만 계속 난독화된 상태로 남으면 release 이름이나 dist mismatch부터 떠올리기 쉽다. 하지만 2026년 7월 4일 기준 Sentry 공식 문서를 다시 보면 build 산출물의 debug ID, 업로드된 artifact 이름, 이벤트가 실제로 들고 온 abs_path는 서로 다른 확인 지점이다. 이 글은 sourcemap은 올렸는데 CDN 경로나 해시 파일명 때문에 매칭이 안 될 때 rewriteFrames와 event lookup을 어떤 순서로 같이 봐야 하는지 정리한 것이다.

목차

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

1. 개요

결론부터 말하면 경로 문제는 release와 dist가 맞다는 사실만으로 해결되지 않는다. 먼저 artifact upload와 debug ID 주입이 끝났는지 확인하고, 그다음 이벤트의 abs_path가 업로드된 artifact 이름과 어디서 어긋나는지 봐야 한다. 호스트 prefix만 다르면 rewriteFrames가 도움이 되지만, 해시 파일명 자체가 다르면 build 산출물과 배포 파일이 다른 문제에 가깝다.

이미 validate와 release 이름 검증 글이 배포 전 기본 게이트를 다뤘다면, 이번 글은 배포 뒤 event-level 경로를 읽는 쪽에 더 가깝다. 또 dist를 build number와 variant 기준으로 정리한 글은 naming 축이고, 오늘은 path 축이다.

같은 이벤트 안에서 app:///와 webpack:/// frame이 섞일 때는 어떤 필드를 먼저 읽어야 하는지까지 더 좁게 보려면 rewriteFrames 뒤에도 app 경로와 webpack 경로가 섞일 때 source-map-debug API를 읽는 글을 같이 보면 흐름이 이어진다.

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

실무에서 흔한 실패는 네 가지다. 첫째, CDN host나 assets prefix가 바뀌었는데 이벤트는 여전히 배포 URL 절대 경로를 들고 온다. 둘째, rewriteFrames는 적용했지만 업로드 artifact 이름은 다른 prefix를 쓴다. 셋째, 해시 파일명이 deploy 과정에서 한 번 더 바뀌어 build 산출물과 실제 배포 파일이 다르다. 넷째, upload는 늦게 됐는데 경로 문제로 오해한다.

Sentry troubleshooting 문서는 먼저 artifact 존재, debug ID 주입, 업로드 시점을 보라고 하고, rewriteFrames 문서는 stack frame 경로를 변환하는 통합을 따로 제공한다. 이 둘을 같이 읽으면 path 문제는 upload 완료 이후의 두 번째 층위라는 점이 보인다.

이때 많은 팀이 이벤트에서 보이는 URL을 업로드 artifact 이름과 바로 비교하지 않는다. 그러면 CDN prefix 문제와 hash drift 문제를 같은 원인처럼 다루게 된다.

• 증상: source map upload는 성공했는데 일부 이벤트만 여전히 난독화된다.
• 실패: event abs_path를 업로드 artifact 이름과 나란히 보지 않는다.
• 막힘: rewriteFrames로 hash drift까지 해결할 수 있다고 기대한다.
• 누락: upload 완료 시점과 이벤트 발생 시점을 구분하지 않는다.

상황	먼저 볼 곳	판단 기준
절대 URL이 다르다	rewriteFrames 설정	prefix만 다르면 경로 정규화로 해결 가능
파일명 hash가 다르다	build 산출물과 deploy 파일	rewriteFrames보다 산출물 동기화 문제에 가깝다
모든 값이 맞는데 초기 이벤트만 안 풀린다	업로드 시점	artifact upload가 이벤트보다 늦었는지 본다

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

점검 순서는 다섯 단계가 가장 실용적이다. 먼저 artifact bundle upload가 끝났는지 확인한다. 두 번째로 배포 파일에 debug ID 주석이 있는지 본다. 세 번째로 이벤트의 abs_path와 release/dist를 기록한다. 네 번째로 이벤트 경로와 업로드 artifact 이름을 나란히 비교한다. 마지막으로 prefix 차이만 남았을 때 rewriteFrames를 적용하거나 수정한다.

1. upload 성공과 artifact 존재부터 확인한다.
2. 배포된 소스 파일의 debug ID 주석을 본다.
3. 이벤트의 abs_path, release, dist를 기록한다.
4. 업로드 artifact 이름과 이벤트 경로를 직접 비교한다.
5. prefix 차이만 남았을 때만 rewriteFrames를 손본다.

핵심은 path 문제와 build 문제를 섞지 않는 것이다. rewriteFrames는 이벤트 경로를 정규화하는 도구이지, deploy 시점에 다른 해시 파일이 올라간 문제를 대신 고쳐 주지는 않는다. 이 해석은 Sentry troubleshooting, CLI upload, rewriteFrames 문서를 함께 읽은 운영 기준이다.

path 비교 메모 예시

event.abs_path=app:///app-3f8a.js
artifact.name=app:///app-3f8a.js
deployed.url=https://cdn.example.com/assets/app-3f8a.js
rewriteFrames.prefix=https://cdn.example.com/assets/
debug_id.present=true

이 정도만 남겨도 event lookup 단계에서 경로 차이와 hash 차이를 빠르게 분리할 수 있다.

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

첫 자료는 troubleshooting 가이드의 artifact 확인 구간이다. sourcemap 업로드가 끝났는지부터 보지 않으면 CDN 경로 문제와 업로드 누락을 구분하기 어렵다.

Sentry troubleshooting 문서는 먼저 업로드된 artifact 존재 여부를 확인하라고 안내한다.

즉 CDN 경로나 해시 파일명 문제를 보기 전에 번들이 실제로 올라갔는지 먼저 자르는 편이 낫다. 이미 artifact bundle이 있는데도 매칭이 안 될 때 보는 글을 읽었다면, 이번 글은 그다음 단계인 경로 해석에 더 가깝다.

두 번째 자료는 CLI 가이드의 debug ID 검증 구간이다. 배포된 소스 파일 끝에 debug ID 주석이 실제로 남았는지 이 단계에서 다시 확인할 수 있다.

Sentry CLI 문서는 artifact에 debug ID가 실제로 주입됐는지 파일 내용으로 다시 확인하라고 안내한다.

즉 CDN 경로와 rewriteFrames 문제는 debug ID가 정상 주입됐다는 전제 위에서만 좁혀진다. 이 단계가 빠지면 경로 문제처럼 보여도 실제 원인은 build pipeline일 수 있다.

세 번째 자료는 CLI 업로드 가이드의 debug ID 주입 단계다. deploy 전에 번들에 어떤 식별자를 넣는지 기준을 다시 맞출 수 있다.

Sentry CLI 가이드는 sourcemap upload 전에 artifact에 debug ID를 주입하는 단계를 별도로 둔다.

경로 문제를 볼 때도 이 단계가 기준점이 된다. build 산출물에 debug ID가 잘 들어갔고 upload도 끝났다면, 그다음부터는 event 쪽 경로와 abs_path를 볼 차례다.

네 번째 자료는 rewriteFrames usage 예시다. Sentry는 stack frame 경로를 바꾸는 통합을 따로 제공하고 있고, CDN prefix나 절대 경로 차이를 이 지점에서 정리할 수 있다.

rewriteFrames integration 문서는 stack frame 경로를 변환하는 예시를 제공한다.

해시 파일명 자체를 rewriteFrames로 해결할 수는 없지만, CDN prefix나 빌드 경로 차이처럼 abs_path가 어긋나는 문제는 여기서 좁혀진다. 이 부분이 release와 dist mismatch를 event 기준으로 보는 글과 자연스럽게 이어진다.

실무 코드에서는 어떤 CDN prefix를 정규화해 앱 내부 경로로 통일할지 명시해 두는 편이 좋다. 이 값이 event abs_path와 업로드 artifact 이름을 잇는 기준이 된다.

CDN 경로를 앱 기준 path로 정리하는 rewriteFrames 예시다.

이런 설정이 있으면 deploy host가 바뀌어도 stack frame 경로를 일정하게 유지하기 쉽다. 또 dist를 build number와 variant 기준으로 정리한 글과 함께 보면 naming 축과 path 축을 따로 관리할 수 있다.

다섯 번째 자료는 event lookup 기준표다. 문제를 path, hash, upload 누락 중 어디서 볼지 바로 나누려면 event abs_path와 업로드 artifact 이름을 나란히 적는 편이 낫다.

deployed URL, event abs_path, uploaded artifact path를 함께 보는 비교표다.

이 표가 있으면 '업로드는 됐는데 왜 이벤트만 안 풀리지'라는 질문을 더 빨리 세 갈래로 자를 수 있다. path prefix 문제인지, 해시 파일 자체가 다른지, 아니면 upload 시점이 늦었는지가 구분된다.

마지막 자료는 event 기준 확인 순서다. release, dist, debug ID가 맞아도 실제 이벤트가 어떤 파일명을 들고 왔는지 확인하지 않으면 CDN 경로 문제를 놓치기 쉽다.

event lookup과 path 확인 순서를 정리한 운영 메모 예시다.

이 메모가 있으면 validate 기록, dist 기준, event-level 경로 진단을 하나의 체크 흐름으로 묶을 수 있다. 이전 글들이 naming을 정리했다면 이번 흐름은 path를 정리하는 역할이다.

5. 주의사항과 리스크

첫 번째 리스크는 rewriteFrames를 너무 일찍 건드려 업로드 누락이나 debug ID 누락을 가리는 것이다. 두 번째 리스크는 CDN 경로와 build output 경로를 운영 문서에 따로 남기지 않는 것이다. 세 번째 리스크는 hash drift 문제를 path 정규화로 해결하려고 하는 것이다.

운영 로그에는 최소한 release, dist, deployed URL, event abs_path, uploaded artifact path를 같이 남기는 편이 좋다. 그래야 다음 장애 때 같은 경로 문제인지, 다른 빌드 산출물 문제인지 곧바로 비교할 수 있다.

• debug ID와 upload 완료를 먼저 확인한 뒤 path를 본다.
• rewriteFrames는 prefix 차이를 정리할 때만 쓴다.
• hash drift는 deploy 산출물 동기화 문제로 따로 본다.

6. 결론

Sentry sourcemap이 일부 이벤트에서만 안 풀릴 때는 release나 dist만 다시 보지 말고 event abs_path와 업로드 artifact 이름을 직접 비교해야 한다. debug ID와 upload가 정상이라는 전제 위에서 CDN prefix 차이만 남았다면 rewriteFrames가 도움이 되고, 해시 파일명이 다르면 build와 deploy 경로를 다시 맞춰야 한다.

• artifact upload와 debug ID를 먼저 본다.
• event abs_path와 artifact 이름을 나란히 비교한다.
• prefix 차이만 남았을 때 rewriteFrames를 적용한다.

7. 참고 링크

1. https://docs.sentry.io/platforms/javascript/guides/nextjs/sourcemaps/troubleshooting_js/
2. https://docs.sentry.io/platforms/javascript/sourcemaps/uploading/cli/
3. https://docs.sentry.io/platforms/javascript/configuration/integrations/rewriteframes/
4. https://docs.sentry.io/api/events/get-debug-information-related-to-source-maps-for-a-given-event/