[Sentry][프론트엔드] rewriteFrames를 넣은 뒤에도 app:///와 webpack:/// 경로가 섞일 때 source-map-debug API 필드를 어떤 순서로 읽나

IT 리서치 노트

[Sentry][프론트엔드] rewriteFrames를 넣은 뒤에도 app:///와 webpack:/// 경로가 섞일 때 source-map-debug API 필드를 어떤 순서로 읽나

Sentry에서 rewriteFrames를 넣어 절대 경로를 정리했는데도 일부 이벤트는 app:///, 일부 이벤트는 webpack:///처럼 서로 다른 path scheme을 들고 오면 sourcemap 문제를 어디서 다시 나눠 봐야 할지 헷갈리기 쉽다. 2026년 7월 5일 기준 Sentry 공식 문서를 다시 보면 이벤트 frame의 abs_path, debug_meta 안 code_file, source-map-debug API의 release_process와 matching_source_file_names는 서로 다른 확인 층위다. 이 글은 rewriteFrames를 넣은 뒤에도 app:///와 webpack:/// 경로가 섞일 때 source-map-debug API 필드를 어떤 순서로 읽고 기록하고 비교할지 정리한 것이다.

목차

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

1. 개요

결론부터 말하면 path scheme 혼재는 rewriteFrames 설정만으로 판단하면 늦다. 먼저 debug ID 주입과 업로드가 정상인지 확인하고, 그다음 source-map-debug API에서 frame별 abs_path, matching_source_file_names, source_file_lookup_result를 읽어 어느 frame이 어떤 규칙으로 실패했는지 나눠 보는 편이 맞다. app:///와 webpack:///가 동시에 보이면 하나의 prefix 규칙이 아니라 frame 출처가 다른 문제일 가능성도 크다.

이미 CDN 경로와 해시 파일명 때문에 매칭이 안 될 때 보는 글이 배포 URL과 artifact 이름 비교를 다뤘다면, 이번 글은 같은 이벤트 안에서 frame path가 갈릴 때의 읽기 순서다. 또 dist를 build number와 variant 기준으로 정리한 글은 naming 축이고, 오늘은 frame path 축이다.

frame path는 맞는데 release artifact가 비어 보이는 경우에는 문제 축이 달라진다. 그때는 source-map-debug API에서 debug_meta는 맞는데 release artifact가 비어 보일 때 다시 확인할 필드 정리를 같이 보면 artifact bundle 업로드와 release 연동을 더 짧게 분리할 수 있다.

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

실무에서 흔한 실패는 네 가지다. 첫째, debug ID와 upload가 정상인지 확인하기 전에 rewriteFrames부터 바꾼다. 둘째, 이벤트 한 건 안에서 app:///와 webpack:/// frame이 섞여 있는데 모든 frame이 같은 번들 경로를 쓴다고 가정한다. 셋째, source-map-debug API를 release 하나의 성공 여부로만 보고 frame별 결과를 안 본다. 넷째, webpack:/// 같은 개발 친화적 path를 이벤트에서 보면 무조건 업로드 실패라고 판단한다.

Sentry troubleshooting 문서는 이벤트의 stack frame abs_path가 debug_meta.code_file과 정확히 맞는지 확인하라고 적고, debug IDs 문서는 build 산출물과 source map을 글로벌 식별자로 묶는 구조를 설명한다. rewriteFrames 문서는 path prefix를 바꾸는 방법을 제공하지만, source-map-debug API 문서는 이벤트 frame별로 어떤 abs_path가 왔고 어떤 artifact 이름을 후보로 찾았는지까지 반환한다. 이 네 문서를 함께 읽으면 rewriteFrames는 마지막 조정 단계이지 첫 출발점이 아니라는 점이 보인다.

특히 app:///와 webpack:///가 동시에 보일 때는 브라우저 번들, SSR 번들, 혹은 서로 다른 업로드 규칙이 한 이벤트 안에 공존할 수 있다. 이 경우 path scheme 자체보다 먼저 frame 출처를 구분하고 기록하고 비교해야 문제를 더 짧게 설명할 수 있다.

• 증상: rewriteFrames를 넣었는데도 일부 frame만 계속 난독화된다.
• 실패: source-map-debug API를 frame별이 아니라 이벤트 전체 성공 여부로만 본다.
• 막힘: app:///와 webpack:///를 같은 prefix 문제로만 처리한다.
• 누락: debug ID 주입과 artifact upload를 먼저 확인하지 않는다.

상황	먼저 볼 곳	판단 기준
모든 frame이 안 풀린다	debug_id_process	업로드나 debug ID 주입 문제일 가능성이 큼
일부 frame만 scheme이 다르다	release_process.abs_path	frame 출처와 prefix 규칙을 먼저 나눈다
후보 artifact는 보이는데 매칭이 안 된다	matching_source_file_names	prefix 차이인지 파일명 drift인지 본다

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

점검 순서는 다섯 단계가 가장 실용적이다. 먼저 debug ID 주입과 artifact upload부터 확인한다. 두 번째로 source-map-debug API를 호출해 frame별 결과를 본다. 세 번째로 각 frame의 abs_path가 app:///인지 webpack:///인지, 아니면 다른 절대 URL인지 나눈다. 네 번째로 matching_source_file_names와 source_file_lookup_result를 보고 prefix 문제인지 artifact 이름 문제인지 구분한다. 마지막으로 prefix 차이만 남았을 때 rewriteFrames iteratee를 조정한다. 필요하면 같은 event id로 API를 다시 호출하고, frame별 응답을 저장하고, 콘솔의 Source Maps 화면과 로그를 같이 확인하고, 업로드된 파일 이름을 줄 단위로 비교한다.

1. debug ID 주입과 artifact upload를 먼저 확인한다.
2. source-map-debug API를 frame 기준으로 본다.
3. abs_path scheme을 app:///, webpack://, 절대 URL로 나눈다.
4. matching_source_file_names로 후보 artifact 이름을 비교한다.
5. prefix 차이만 남았을 때 rewriteFrames를 조정한다.

핵심은 path scheme 혼재를 build 성공 여부 하나로 축소하지 않는 것이다. 같은 이벤트 안에서도 frame 출처가 다르면 서로 다른 prefix 규칙을 쓸 수 있고, 이때는 release 하나보다 frame별 결과가 더 중요하다. 이 해석은 Sentry abs_path, debug IDs, rewriteFrames, source-map-debug API 문서를 이어 읽은 운영 기준이다.

frame 판별 메모 예시

frame0.abs_path=app:///app-3f8a.js
frame0.lookup=found
frame1.abs_path=webpack:///src/lib/cart.ts
frame1.lookup=not_found
frame1.matching_source_file_names=[]
rewriteFrames.needs_server_bundle_rule=true

이 정도만 남겨도 어느 frame은 prefix 정규화로 해결되고, 어느 frame은 업로드 artifact naming을 다시 봐야 하는지 짧게 설명할 수 있다.

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

첫 자료는 source map troubleshooting 문서의 핵심 문장이다. Sentry는 이벤트의 stack frame abs_path가 debug_meta 안 code_file과 정확히 맞는지부터 보라고 안내한다.

Sentry troubleshooting 문서는 이벤트의 abs_path와 debug_meta.code_file 매칭을 먼저 확인하라고 설명한다.

즉 release나 dist가 맞더라도 frame path가 다르면 source map은 안 붙을 수 있다. app:///와 webpack:///가 섞일 때도 먼저 어떤 frame이 실제로 어떤 abs_path를 보냈는지 봐야 한다.

두 번째 자료는 debug ID 문서다. Sentry는 debug ID를 변환된 자바스크립트 파일과 source map을 묶는 전역 식별자로 설명한다.

Sentry debug ID 문서는 빌드 산출물과 source map을 식별자로 연결하는 기본 구조를 설명한다.

이 단계가 맞아야 path 해석 문제를 별도로 다룰 수 있다. debug ID 주입이나 업로드 자체가 틀렸다면 app:///와 webpack:/// 혼선처럼 보여도 실제 원인은 그보다 앞단일 수 있다.

세 번째 자료는 rewriteFrames integration 예시다. Sentry는 기본적으로 절대 경로를 정리해 app:/// 형태로 바꾸는 패턴과, 커스텀 prefix를 두는 방식을 따로 보여 준다.

rewriteFrames 문서는 절대 경로나 prefix 차이를 stack frame 경로 변환으로 정리하는 예시를 제공한다.

이 문서만 보면 모든 경로 문제를 rewriteFrames 하나로 풀 수 있을 것처럼 보이지만, 실제로는 이벤트가 들고 온 frame 종류를 먼저 나눠야 한다. app:///와 webpack:///가 동시에 보인다면 브라우저 번들과 서버 번들, 또는 서로 다른 업로드 규칙이 섞였는지부터 구분하는 편이 낫다.

네 번째 자료는 source-map-debug API 응답 스키마다. 여기서는 release_process.abs_path, matching_source_file_names, source_file_lookup_result처럼 이벤트 기준 경로 판별에 바로 쓰는 필드를 한 번에 볼 수 있다.

Sentry source-map-debug API는 이벤트 frame별 abs_path와 업로드된 source file 매칭 결과를 함께 반환한다.

즉 source-map-debug API는 '이벤트가 어떤 파일명을 들고 왔는지'와 'Sentry가 어떤 업로드 artifact를 후보로 봤는지'를 같은 구조에서 보여 준다. rewriteFrames를 조정할지, 업로드 artifact 이름을 고칠지 판단하는 기준점이 된다.

실무에서는 event 한 건 안에 서로 다른 frame path가 섞이는 경우가 있다. 브라우저 번들은 app:///로 정규화됐는데 SSR이나 번들러 출력은 webpack:///로 남아 있으면, 하나의 규칙만 보고 전부 고치기 어렵다.

같은 이벤트 안에서 app:///와 webpack:/// frame이 섞인 예시다.

이 예시처럼 frame 단위로 path가 갈리면 source-map-debug API 필드를 frame 기준으로 읽어야 한다. release 하나만 보고 결론 내리면 어떤 frame이 실패했는지 놓치기 쉽다.

마지막 자료는 읽기 순서 표다. 어떤 필드를 먼저 볼지 고정해 두면 rewriteFrames와 artifact naming 문제를 섞지 않게 된다.

source-map-debug API 필드를 frame 기준으로 읽는 순서를 정리한 표다.

이 표가 있으면 app:///와 webpack:///가 동시에 보일 때도 어느 frame이 prefix 차이 문제인지, 어느 frame이 업로드 이름 문제인지 더 빨리 분리할 수 있다. 이전 글이 CDN prefix와 hash drift를 다뤘다면, 이번 표는 event frame 혼재를 다룬다.

5. 주의사항과 리스크

첫 번째 리스크는 frame별 결과를 안 보고 rewriteFrames iteratee만 키우는 것이다. 두 번째 리스크는 webpack:/// frame이 보이면 무조건 브라우저 번들 문제라고 단정하는 것이다. 세 번째 리스크는 debug ID와 upload가 틀렸는데 path 문제라고 오판하는 것이다.

운영 문서에는 최소한 frame abs_path, matching_source_file_names, source_file_lookup_result, debug_id_process를 남기는 편이 좋다. 그래야 다음 번에도 CDN prefix 문제와 번들 출처 문제를 같은 말로 설명하지 않게 된다.

• rewriteFrames는 마지막 조정 단계로 쓴다.
• app:///와 webpack:/// 혼재는 frame 출처를 먼저 나눈다.
• debug ID와 artifact upload가 정상인지 먼저 확인한다.

6. 결론

Sentry에서 app:///와 webpack:/// frame이 섞일 때는 rewriteFrames를 바로 바꾸기보다 source-map-debug API를 frame 기준으로 읽어야 한다. abs_path, matching_source_file_names, lookup 결과를 나란히 보면 prefix 차이와 artifact naming 문제를 더 짧게 분리할 수 있다.

• source-map-debug API를 frame 기준으로 읽는다.
• app:///와 webpack:///는 서로 다른 출처일 수 있다고 본다.
• prefix 차이만 남았을 때 rewriteFrames를 손본다.

7. 참고 링크

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