[Sentry][프론트엔드] debug_id는 맞는데 abs_path canonicalization이 흔들릴 때 rewriteFrames와 frame URL을 어떤 순서로 대조하나

IT 리서치 노트

[Sentry][프론트엔드] debug_id는 맞는데 abs_path canonicalization이 흔들릴 때 rewriteFrames와 frame URL을 어떤 순서로 대조하나

Sentry에서 debug_id와 artifact bundle은 맞아 보이는데도 source map이 안 풀리면, 다음으로는 abs_path canonicalization을 의심해야 하는 경우가 많다. 2026년 7월 7일 기준 Sentry 공식 문서를 다시 보면 source-map-debug API는 abs_path와 matching_source_file_names를 같이 보여 주고, legacy troubleshooting 문서는 event JSON의 abs_path와 artifact 이름을 맞춰 보라고 설명한다. 또 path에 동적 값이 있으면 rewriteFrames로 frame을 바꾸라고 안내한다. 이 글은 debug_id는 맞는데 abs_path canonicalization이 흔들릴 때 rewriteFrames와 frame URL을 어떤 순서로 대조해야 하는지 정리한 것이다.

목차

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

1. 개요

결론부터 말하면 이 문제는 upload가 먼저인지 rewriteFrames가 먼저인지가 아니라, event frame이 최종적으로 어떤 이름으로 canonicalize되는지부터 확인하는 작업이다. 먼저 source-map-debug API 또는 event JSON에서 abs_path를 보고, 그다음 rewriteFrames 적용 후 frame URL을 보고, 마지막에 업로드된 artifact 이름이 그 값과 맞는지 비교하는 순서가 가장 덜 꼬인다.

이미 release_has_some_artifact는 true인데 source_file_lookup_result가 not_found일 때 파일명과 prefix를 다시 확인하는 글이 filename과 prefix 비교를 다뤘다면, 이번 글은 그보다 한 단계 앞의 frame canonicalization 순서다. 또 debug_meta는 맞는데 release artifact가 비어 보일 때 보는 글과도 이어진다.

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

실무에서 자주 꼬이는 지점은 네 가지다. 첫째, debug_id가 맞는다는 이유로 frame URL을 더 이상 보지 않는다. 둘째, artifact 이름을 바꾸기 전에 event frame의 abs_path가 실제로 어떻게 들어오는지 확인하지 않는다. 셋째, rewriteFrames를 넣었지만 어떤 값으로 frame을 바꿨는지 검증하지 않는다. 넷째, ~ prefix와 full URL의 차이를 이해하지 못한 채 둘을 섞어 올린다.

Sentry source-map-debug API는 abs_path, matching_source_file_names, matching_source_map_name, source_file_lookup_result를 같이 보여 준다. legacy troubleshooting 문서는 event JSON의 abs_path를 보고 실제로 어떤 파일을 찾으려 하는지 확인하라고 설명하고, artifact 이름이 그 값과 맞아야 한다고 적는다. 또 dynamic path가 있으면 rewriteFrames를 사용하라고 따로 안내한다. 이 세 문서를 같이 읽으면 문제는 'artifact가 있느냐'보다 'frame이 어떤 이름으로 읽히느냐'로 좁혀진다.

• 증상: debug_id는 맞는데 source file lookup이 흔들린다.
• 실패: abs_path를 보기 전에 url-prefix부터 다시 바꾼다.
• 막힘: rewriteFrames가 실제로 어떤 frame URL을 만들었는지 검증하지 않는다.
• 누락: ~ prefix와 full URL의 역할을 path 특성에 맞게 나누지 않는다.

상황	먼저 볼 곳	판단 기준
debug_id는 성공인데 lookup이 실패한다	abs_path	이벤트가 어떤 최종 URL을 보냈는지 본다
고객 도메인이나 빌드 경로가 섞인다	rewriteFrames	frame canonicalization 규칙이 필요한지 본다
artifact는 있는데 매칭이 들쭉날쭉하다	artifact naming	tilde prefix와 full URL 중 어떤 naming이 맞는지 본다

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

가장 실용적인 순서는 네 단계다. 먼저 source-map-debug API에서 abs_path와 matching_source_file_names를 확인한다. 두 번째로 event frame에 dynamic 값이 있으면 rewriteFrames가 어떤 최종 URL을 만들지 고정한다. 세 번째로 সেই 최종 URL과 artifact 이름이 일치하도록 ~ prefix 또는 full URL naming을 맞춘다. 마지막으로 새 이벤트를 다시 보내 source_file_lookup_result가 바뀌는지 본다.

1. abs_path를 먼저 본다.
2. dynamic path 여부를 보고 rewriteFrames가 필요한지 판단한다.
3. canonicalized frame URL 기준으로 artifact naming을 맞춘다.
4. 새 이벤트에서 lookup 결과가 바뀌는지 확인한다.

실무에서는 source-map-debug API를 조회하고, event JSON의 frame URL을 복사하고, rewriteFrames 설정을 비교하고, 업로드된 artifact 파일명을 다시 확인하는 순서를 운영 메모에 남겨 두는 편이 좋다. 콘솔에서 release를 열고, Source Maps 페이지를 클릭하고, event 화면의 JSON을 열고, 같은 frame을 표로 비교하면 어떤 단계가 어긋났는지 바로 보인다.

curl https://sentry.io/api/0/projects/ORG/PROJECT/events/EVENT_ID/source-map-debug/   -H 'Authorization: Bearer YOUR_INTERNAL_TOKEN'

# compare:
# 1) release_process.abs_path
# 2) matching_source_file_names
# 3) rewriteFrames result
# 4) uploaded artifact name

여기서 순서를 뒤집으면 rewriteFrames와 url-prefix를 번갈아 바꾸다가 원인 파악 범위만 더 불명확해지기 쉽다. 공식 문서가 말하는 핵심은 event frame이 실제로 어떤 이름으로 해석되는지를 먼저 확인하라는 것이다. source-map-debug API는 그 해석 결과를 바로 보여 주므로, 이 단계부터 보는 편이 가장 빠르다.

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

첫 자료는 source-map-debug API 응답의 release_process 필드다. 여기에는 abs_path와 matching_source_file_names, matching_source_map_name, source_file_lookup_result가 같이 나온다.

Sentry source-map-debug API는 abs_path, matching_source_file_names, matching_source_map_name, source_file_lookup_result를 한 응답에 보여 준다.

debug_id가 맞더라도 release_process에서 frame path가 어떤 artifact 이름으로 해석되는지 먼저 봐야 한다. 이 응답이 있으면 '업로드는 됐는데 왜 안 풀리냐'는 질문을 더 좁게 자를 수 있다.

두 번째 자료는 Sentry가 권장하는 가장 기본 점검 구간이다. 문서는 uploaded artifact names가 stack trace frame 값과 맞아야 한다고 분명히 적고 있다.

Sentry legacy sourcemap troubleshooting 문서는 artifact 이름이 stack trace frame과 맞아야 한다고 설명한다.

즉 debug_id, dist, release가 모두 맞아도 frame URL이 artifact naming과 엇갈리면 deminify는 여전히 실패할 수 있다. post 113이 filename과 prefix 비교를 다뤘다면, 이번 글은 frame canonicalization 순서를 더 좁게 본다.

세 번째 자료는 abs_path를 어디서 읽어야 하는지 설명하는 문장이다. Sentry는 event JSON에서 abs_path를 보고 실제로 어떤 파일을 찾으려 하는지 확인하라고 안내한다.

Sentry 문서는 event JSON의 abs_path를 보고 실제로 어떤 파일을 찾으려 하는지 확인하라고 설명한다.

source-map-debug API가 있더라도 핵심은 같다. frame이 실제로 어떤 URL이나 scheme으로 찍히는지 확인하지 않으면 url-prefix와 rewriteFrames를 바꾸는 순서가 계속 흔들린다.

네 번째 자료는 dynamic path와 rewriteFrames의 연결을 설명하는 구간이다. Sentry는 경로 안에 동적인 값이 있으면 rewriteFrames로 abs_path를 바꾸라고 권한다.

Sentry 문서는 path에 동적 값이 있으면 rewriteFrames integration으로 abs_path를 바꾸라고 안내한다.

이 조언의 핵심은 rewriteFrames가 업로드 이름을 맞추는 마법이 아니라, 이벤트 프레임을 업로드된 artifact naming에 맞게 canonicalize하는 단계라는 점이다.

다섯 번째 자료는 rewriteFrames integration 자체의 정의다. Sentry는 이 integration을 stack trace 각 frame에 변환을 적용하는 도구라고 설명한다.

Sentry rewriteFrames 문서는 각 stack trace frame에 transformation을 적용하는 integration이라고 설명한다.

즉 rewriteFrames는 artifact 업로드 단계가 아니라 event frame canonicalization 단계다. 이 순서를 이해해야 debug_id가 맞는데도 abs_path가 계속 엇나가는 상황을 줄일 수 있다.

마지막 자료는 실제 비교 순서를 코드와 표로 남긴 예시다. abs_path를 먼저 고정하고, 그다음 rewriteFrames와 url-prefix를 맞춰야 같은 증상을 반복해서 줄일 수 있다.

debug_id는 맞는데 abs_path canonicalization이 흔들릴 때 frame URL과 rewriteFrames를 대조하는 예시다.

이 구조를 쓰면 source-map-debug API에서 debug_id는 성공인데 source lookup이 흔들릴 때, frame canonicalization과 artifact naming 중 어디가 어긋났는지 더 빨리 보인다. 이미 app:///와 webpack:/// 경로를 읽는 글을 읽었다면, 이번 예시는 그 뒤의 canonicalization order다.

5. 주의사항과 리스크

rewriteFrames를 너무 일찍 넣으면 실제 abs_path가 어떤 문제를 갖고 있었는지 가려질 수 있다. 반대로 dynamic path가 분명한데도 rewriteFrames를 안 쓰면 고객 도메인, CDN prefix, app scheme 때문에 artifact naming을 계속 늘려야 할 수 있다. ~ prefix는 호스트를 무시하는 용도이므로 path 자체가 같을 때만 써야 한다는 점도 놓치기 쉽다.

• 주의: debug_id 성공은 frame URL 문제까지 해결됐다는 뜻이 아니다.
• 주의: rewriteFrames는 upload 단계가 아니라 event frame canonicalization 단계다.
• 리스크: dynamic path가 아닌데 과하게 rewriteFrames를 넣으면 다른 frame까지 같이 바뀔 수 있다.
• 리스크: ~ prefix를 경로가 다른 artifact에 남용하면 오히려 매칭이 더 모호해질 수 있다.

6. 결론

Sentry sourcemap 문제에서 debug_id가 맞는데도 안 풀리는 경우, 다음으로 볼 것은 abs_path canonicalization이다. source-map-debug API의 abs_path와 matching_source_file_names를 먼저 보고, rewriteFrames로 frame URL을 고정한 뒤, 그 최종 URL에 맞춰 artifact naming을 다시 보는 순서가 가장 안정적이다.

이전 단계 글로는 filename과 prefix를 다시 확인하는 글과 app:///와 webpack:/// 경로를 읽는 글이 같이 맞물린다. 이번 글은 그 둘 사이에서 frame canonicalization 순서를 고정하는 보강편이다.

7. 참고 링크

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