[Sentry][프론트엔드] sourceMappingURL은 맞는데 CDN이 map 파일을 압축하거나 차단할 때 scraping status와 uploaded artifact를 어떻게 나누나

IT 리서치 노트

[Sentry][프론트엔드] sourceMappingURL은 맞는데 CDN이 map 파일을 압축하거나 차단할 때 scraping status와 uploaded artifact를 어떻게 나누나

Sentry에서 sourceMappingURL도 맞고 uploaded artifact도 있는 것 같은데 소스맵이 계속 안 풀리면, 많은 팀이 release 이름이나 dist부터 다시 본다. 하지만 2026년 7월 12일 기준 Sentry 공식 문서를 다시 보면 source-map-debug API는 `source_map_lookup_result` 같은 uploaded artifact 축과 `scraping_process` 같은 live fetch 축을 분리해 내려준다. legacy sourcemap troubleshooting 문서는 `sourceMappingURL`이 가리키는 경로와 artifact 이름을 맞춰야 한다고 설명하고, 동시에 gzipped 파일 업로드는 해석 문제를 만들 수 있어 `--decompress`를 안내한다. 이 글은 그래서 sourceMappingURL이 맞는 상황에서도 CDN이 `.map` 파일을 압축하거나 차단할 때 uploaded artifact 문제와 scraping 문제를 어떤 순서로 나누는 편이 맞는지 정리한 것이다.

목차

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

1. 개요

결론부터 말하면 Sentry source map 장애는 uploaded artifact 축과 scraping 축을 먼저 분리해야 한다. matching_source_map_name과 source_map_lookup_result가 맞는데 scraping_process.source_map.status가 실패라면, release 이름보다 CDN 접근 정책, .map 응답 차단, 압축 방식, public URL 가용성을 먼저 보는 편이 맞다. 반대로 lookup 자체가 not found면 sourceMappingURL, artifact 이름, release/dist 매칭부터 다시 봐야 한다.

즉 source map이 안 풀린다는 한 문장 안에 두 가지 다른 질문이 들어 있다. 'Sentry가 업로드된 artifact를 찾았는가'와 'Sentry가 live URL에서 파일을 긁어오거나 비교하는 단계가 성공했는가'를 나눠 봐야 한다. 이미 line/column 품질 글이 found/found 뒤 품질 문제를 다뤘다면, 이번 글은 그보다 한 단계 앞의 scraping 성공 여부를 다룬다.

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

현장에서 먼저 꼬이는 지점은 세 가지다. 첫째, sourceMappingURL이 맞다고 확인한 뒤에도 live .map 파일 접근 실패를 artifact 누락으로 오해한다. 둘째, build 산출물이 이미 gzip 등으로 압축된 상태인데 uploaded artifact 자체는 정상이라고 가정한다. 셋째, CDN이 .map 파일을 차단하거나 auth cookie 없이 못 읽게 만들었는데 Sentry UI의 release artifact 탭만 보고 문제 없다고 판단한다.

Sentry source-map-debug API 예시는 이 세 오해를 풀어 주는 단서를 준다. release-process는 matching_source_map_name, source_map_reference, source_map_lookup_result로 업로드된 artifact와 event frame 이름 매칭을 설명한다. scraping-process는 live URL 기준으로 source file과 source map fetch status를 별도로 보여 준다. 즉 두 층은 명시적으로 분리되어 있다.

legacy sourcemap troubleshooting 문서도 같은 맥락을 다른 말로 설명한다. minified file 끝의 sourceMappingURL이 가리키는 경로와 uploaded artifact 이름이 맞아야 하고, gzipped sourcemap 업로드는 해석 문제를 만들 수 있어 --decompress를 쓸 수 있다고 적는다. 이 말은 곧 compression과 path 문제를 같이 보되, uploaded artifact 이름 매칭과 live scraping 실패를 한 원인으로 보지 말라는 뜻이다.

• 증상: sourceMappingURL은 맞는데 Sentry가 map을 못 읽는 것처럼 보인다.
• 실패: release artifact 탭만 보고 CDN 접근 실패를 놓친다.
• 막힘: gzipped upload와 live map 차단을 같은 오류로 본다.
• 누락: source-map-debug API의 release-process와 scraping-process를 같이 저장하지 않는다.

관찰값	먼저 볼 곳	왜 중요한가
lookup_result = found	scraping_process	업로드보다 live fetch 문제일 수 있다
matching_source_map_name 불일치	artifact 경로와 sourceMappingURL	업로드 이름 자체가 틀렸을 수 있다
gzipped artifact 또는 CDN gzip 정책	upload 옵션과 CDN 응답	둘 다 해석 실패를 만들 수 있다

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

가장 덜 꼬이는 순서는 네 단계다. 먼저 source-map-debug API에서 release-process를 확인해 uploaded artifact lookup이 성립하는지 본다. 두 번째로 같은 응답의 scraping-process를 봐서 source file과 source map URL fetch status가 success인지 확인한다. 세 번째로 sourceMappingURL이 가리키는 경로와 artifact 이름이 맞는지 legacy guide 기준으로 대조한다. 마지막으로 build 산출물과 upload 단계에서 gzip·brotli·사전 압축이 개입했는지 확인한다.

1. release-process에서 artifact lookup부터 본다.
2. scraping-process에서 live fetch status를 본다.
3. sourceMappingURL과 uploaded artifact 이름을 맞춘다.
4. gzip·decompress·CDN 차단 여부를 마지막으로 붙인다.

release-process가 found인데 scraping status가 failed면 우선 CDN과 public fetch 경로를 본다. .map 파일이 403, 404, auth required, bot protection, 잘못된 content-type, 과도한 compression 정책을 타는지 확인한다. 반대로 release-process가 not found면 sourceMappingURL이 가리키는 이름, ~/static/js/... 같은 artifact naming, release/dist 설정부터 다시 본다. 이 순서를 바꾸면 CDN 이슈인데 upload만 다시 반복하거나, upload naming 이슈인데 공개 URL만 계속 열어 보는 낭비가 생긴다.

운영 메모 예시

event_id=abcd1234
matching_source_map_name=~/static/js/main.js.map
source_map_lookup_result=found
scraping_process.source_map.status=failed
artifact_upload_mode=sentry_cli_decompress
next_action=check_cdn_map_access_and_precompressed_artifacts

gzip 문제는 upload와 scraping 두 축 모두에 걸칠 수 있으므로 별도 체크 항목으로 남겨 두는 편이 좋다. build plugin이 미리 gzip한 .map을 sentry-cli로 그대로 올렸다면 uploaded artifact 해석이 틀어질 수 있고, CDN이 .map 응답을 차단하거나 예외적인 compression policy를 쓰면 scraping status만 실패할 수 있다. 문서가 --decompress를 따로 안내하는 이유가 바로 여기 있다.

• release-process found 여부를 먼저 본다.
• 그다음 scraping-process status를 본다.
• gzip은 upload 축과 CDN 축 모두에서 다시 확인한다.

핵심은 sourceMappingURL이 맞다는 사실만으로 live fetch도 성공한다고 가정하지 않는 것이다. source-map-debug API가 이미 두 층을 분리해 보여 주므로, 우리도 같은 순서로 분리해서 봐야 한다.

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

첫 자료는 Sentry source-map-debug API 응답 예시다. 여기서는 `matching_source_map_name`, `source_map_reference`, `source_file_lookup_result`, `source_map_lookup_result` 같은 release-process 필드를 함께 보여 준다. 즉 업로드된 artifact와 event frame 이름이 맞는지부터 별도 층으로 판단할 수 있다.

Sentry source-map-debug API는 uploaded artifact 이름 매칭과 frame-level lookup 결과를 release-process 필드로 따로 보여 준다.

이 필드가 `found`인데도 문제라면, 이제 질문은 uploaded artifact가 없는가가 아니라 다른 층에서 막히는가다. 오늘 글의 핵심은 바로 그 다음 층인 scraping status를 अलग해서 보는 것이다.

두 번째 자료는 같은 API 응답의 `scraping_process` 부분이다. 여기서는 source file과 source map URL 각각에 대해 `status`를 내려준다. 즉 uploaded artifact는 멀쩡한데, Sentry가 live URL에서 파일을 긁어오는 단계가 실패하는지 따로 볼 수 있다.

source-map-debug API의 `scraping_process`는 live URL fetch 성공 여부를 uploaded artifact lookup과 별도로 보여 준다.

이 차이가 중요하다. release-process가 found인데 scraping status가 실패라면 artifact 업로드보다 CDN, public access, compression, response header 쪽 문제를 먼저 의심해야 한다.

세 번째 자료는 Sentry legacy sourcemap troubleshooting의 `sourceMappingURL` 설명이다. 이 문서는 minified file 끝의 `sourceMappingURL`이 가리키는 위치와 uploaded artifact 이름이 맞아야 한다고 직접 설명한다. 즉 이름 매칭 축 자체는 여전히 분리해서 볼 수 있다.

Sentry 문서는 `sourceMappingURL`이 가리키는 경로와 uploaded artifact 이름이 일치해야 한다고 설명한다.

따라서 먼저 release-process에서 이름 매칭이 성립하는지 보고, 그다음에 scraping status가 실패하는지 봐야 한다. 두 질문을 바꾸어 물으면 같은 `not working` 증상도 훨씬 짧게 좁혀진다.

네 번째 자료는 gzip 이슈를 upload 단계와 scraping 단계로 분리한 표다. Sentry 문서가 `--decompress`를 별도로 안내하는 이유와, CDN이 `.map` 응답을 변형하거나 차단할 때 live fetch가 따로 실패하는 이유를 한 장에서 같이 볼 수 있다.

gzip 이슈를 uploaded artifact 해석 축과 live fetch scraping 축으로 나눈 점검표다.

이 표처럼 보면 compression은 한 원인이 아니라 두 질문으로 쪼개야 한다. 빌드 산출물 업로드에서 이미 꼬였는지, CDN 응답 정책 때문에 live fetch가 막혔는지를 나눠 보면 triage 순서가 훨씬 빨라진다.

실무에서는 uploaded artifact 축과 scraping 축을 분리한 표가 필요하다. source_map_lookup_result가 found인지, scraping_process.source_map.status가 success인지, matching_source_map_name이 기대 경로와 맞는지를 한 번에 놓아야 CDN 이슈와 artifact 이슈를 헷갈리지 않는다.

Sentry source-map 장애를 uploaded artifact 축과 scraping status 축으로 나눈 분기표다.

이 표처럼 보면 이미 line/column 품질 글이 다룬 found/found 품질 축과 오늘 글의 scraping 축이 분명히 분리된다. 오늘은 '찾았는데 왜 live fetch가 안 되지'라는 새 질문이다.

마지막 자료는 최소 재현 명령 예시다. source-map-debug API 응답과 sourcemaps upload 옵션을 같이 남겨 두면, lookup 축과 scraping 축을 사람 기억이 아니라 출력 기준으로 비교할 수 있다.

source-map-debug API와 `sentry-cli sourcemaps upload --decompress`를 같이 적는 점검 예시다.

이 형태를 유지하면 release-process와 scraping-process를 따로 복기할 수 있다. CDN 정책이 원인이면 live URL fetch를, artifact 업로드가 원인이면 release 이름과 upload 옵션을 먼저 손대면 된다.

5. 주의사항과 리스크

첫 번째 리스크는 lookup_result가 found인데도 artifact 업로드만 다시 반복하는 것이다. 두 번째 리스크는 CDN이 .map을 막는 문제를 sourceMappingURL 문자열 문제로 오해하는 것이다. 세 번째 리스크는 압축된 산출물 업로드를 허용한 채 --decompress 같은 보정 단계를 남기지 않는 것이다.

운영 전에 확인할 때는 최소한 matching_source_map_name, source_map_lookup_result, scraping_process.source_map.status, artifact_upload_mode, cdn_map_access 다섯 칸을 같은 메모에 남겨 두는 편이 좋다. 이 다섯 칸이 없으면 release artifact 문제와 CDN scraping 문제를 계속 섞어 읽게 된다.

• lookup과 scraping은 서로 다른 단계다.
• sourceMappingURL이 맞아도 live fetch는 실패할 수 있다.
• compression은 upload와 CDN 양쪽에서 다시 확인한다.

6. 결론

Sentry source map 문제를 줄이려면 uploaded artifact 축과 scraping status 축을 먼저 분리해야 한다. source_map_lookup_result가 found인데 scraping이 실패하면 CDN과 public .map 접근을 먼저 보고, lookup 자체가 안 되면 sourceMappingURL과 artifact naming부터 다시 보는 편이 맞다. 여기에 gzip 업로드와 --decompress 여부까지 같이 적어 두면 같은 장애를 훨씬 짧게 재현할 수 있다.

• release-process와 scraping-process를 분리해 본다.
• sourceMappingURL과 artifact 이름을 먼저 맞춘다.
• gzip과 CDN 차단은 별도 체크 항목으로 둔다.

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/guides/connect/sourcemaps/troubleshooting_js/
3. https://docs.sentry.io/platforms/javascript/guides/connect/sourcemaps/troubleshooting_js/legacy-uploading-methods/