[Sentry][프론트엔드] source file과 source map은 found인데 original source만 비어 있을 때 sourcesContent와 original source 업로드를 어떤 순서로 다시 보나

IT 리서치 노트

[Sentry][프론트엔드] source file과 source map은 found인데 original source만 비어 있을 때 sourcesContent와 original source 업로드를 어떤 순서로 다시 보나

Sentry source-map-debug API에서 source file과 source map은 모두 found인데 이벤트 화면에 원본 소스가 비거나 충분히 보이지 않는 경우가 있다. 이때는 prefix나 artifact 이름부터 다시 뒤지기 쉽지만, 2026년 7월 9일 기준 Sentry 공식 문서를 다시 보면 source map에 original source code인 sourcesContent가 있는지, 없으면 original source files를 추가로 업로드했는지, 그리고 line과 column mapping이 로컬에서 실제로 맞는지를 먼저 확인하라고 안내한다. 이 글은 file과 map lookup은 통과했는데 original source만 비는 경우 무엇부터 다시 봐야 하는지 정리한 것이다.

목차

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

1. 개요

결론부터 말하면 source_file_lookup_result=found와 source_map_lookup_result=found가 나왔는데 original source가 비어 있다면, frame 경로 축보다 sourcesContent와 original source files 업로드 여부를 먼저 다시 보는 편이 맞다. file과 map lookup은 이미 통과했기 때문이다. 이 상태에서 release나 prefix를 다시 뒤지는 것보다 source map 내부 내용과 보조 업로드 여부를 먼저 확인하는 편이 훨씬 빠르다.

이미 source file lookup not_found 글과 source map lookup not_found 글이 file과 map 경로 축을 다뤘다면, 이번 글은 그다음인 original source content 축이다.

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

현장에서 자주 나오는 오해는 세 가지다. 첫째, file과 map이 모두 found면 source map 문제가 끝났다고 생각한다. 둘째, original source가 비어도 release나 dist를 다시 맞추면 해결될 것이라 본다. 셋째, source map 안의 sourcesContent가 비어 있는지 확인하지 않고 업로드 도구 설정만 다시 만진다.

하지만 Sentry troubleshooting 문서는 source map이 original source code를 포함하는지 확인하라고 하고, legacy uploading methods 문서는 sourcesContent가 없으면 original source files를 별도로 업로드해야 한다고 적고 있다. 즉 file과 map artifact를 찾는 문제와 original source를 보여 줄 재료가 있는 문제는 다른 축이다.

source-map-debug API에서 file과 map lookup이 모두 found라는 사실은 frame URL, prefix, artifact 이름 축을 어느 정도 통과했다는 뜻이다. 그다음에도 원본 소스가 비면 남는 대표 원인은 둘 중 하나다. source map 자체에 sourcesContent가 빠졌거나, sources만 있고 Sentry가 접근할 original source files가 따로 없다는 것이다. 여기서 계속 prefix를 다시 비교하면 문제 범위만 넓어진다.

• 증상: file과 map은 found인데 원본 소스 코드가 비어 있거나 부족하다.
• 실패: artifact 경로 문제라고만 보고 source map 내부를 안 연다.
• 막힘: sourcesContent와 original source 업로드 여부를 구분하지 않는다.
• 누락: local mapping 검증을 하지 않아 line과 column 품질 문제를 놓친다.

증상	먼저 볼 것	이유
original source가 비어 있다	sourcesContent	source map 내부에 원본이 있는지 확인
sourcesContent가 없다	original source files 업로드	Sentry가 대체 원본을 읽을 재료가 있는지 확인
line / column이 여전히 이상하다	local source map 검증	맵 품질과 빌드 변환 순서 확인

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

가장 빠른 순서는 네 단계다. 먼저 source-map-debug API에서 file과 map lookup이 모두 found인지 확인한다. 두 번째로 배포된 source map 파일을 열어 sources와 sourcesContent를 직접 본다. 세 번째로 sourcesContent가 비어 있으면 original source files를 업로드했는지 확인한다. 마지막으로 local source map 테스트를 돌려 line과 column mapping 품질을 검증한다.

1. source-map-debug API에서 file / map lookup 상태를 확인한다.
2. 실제 map 파일의 sourcesContent 값을 연다.
3. 비어 있으면 original source files 업로드 여부를 확인한다.
4. local mapping 테스트로 line / column 품질을 확인한다.
5. 운영 메모에는 original source 축 점검 결과를 별도 줄로 남긴다.

이 순서가 좋은 이유는 문제 범위를 한 번에 줄여 주기 때문이다. file과 map이 이미 found라면 경로 축은 뒤로 밀린다. 그다음에는 source map payload와 original source 보조 업로드 축만 보면 된다. 이후에도 line이나 column이 틀리면 그때 local mapping 품질과 빌드 순서를 보면 된다.

운영 메모 예시

source_file_lookup=found
source_map_lookup=found
sources_content_present=false
original_source_upload_present=false
local_mapping_check=pending

이 메모만 있어도 운영자는 경로는 맞고, map 안 원본이 없고, 원본 업로드도 없으니 이제 local mapping을 보자라는 순서로 바로 움직일 수 있다. 문제를 다시 release나 prefix로 넓힐 필요가 없다.

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

첫 자료는 source-map-debug API 응답 스키마다. 여기서는 frame 수준에서 source_file_lookup_result를 별도 필드로 내려준다는 점이 중요하다.

Sentry source-map-debug API는 source file lookup 결과를 별도 필드로 보여 준다.

이 필드가 found라는 뜻은 frame 경로와 minified file artifact 축은 어느 정도 맞았다는 뜻이다. 즉 original source 누락 문제를 file not_found와 같은 크기로 볼 필요가 없어진다.

두 번째 자료는 같은 API의 source_map_lookup_result 필드다. source file과 source map이 둘 다 found라는 조합을 먼저 확인해야 이후 original source 누락 문제를 더 좁게 볼 수 있다.

Sentry source-map-debug API는 source map lookup 결과도 별도 필드로 내려준다.

이 두 필드가 모두 found면 frame URL, prefix, artifact 이름 축은 대체로 통과한 셈이다. 남는 주요 의심은 source map 안의 sourcesContent 또는 원본 소스 업로드 경로다.

세 번째 자료는 Sentry JavaScript sourcemap troubleshooting 문서다. 여기서는 source map에 original source code가 들어 있는지, 그리고 line이나 column mapping을 로컬에서 먼저 확인하라고 안내한다.

Sentry troubleshooting 문서는 source map 안의 original source code 포함 여부와 로컬 매핑 검증을 먼저 보라고 설명한다.

즉 file과 map이 found여도 original source가 비면 디버깅 품질은 여전히 떨어질 수 있다. 이때는 배포 artifact 이름보다 source map 내부 내용과 local mapping 검증 쪽으로 시선을 옮겨야 한다.

네 번째 자료는 legacy uploading methods 문서다. 여기서는 source map 파일에 original source code인 sourcesContent가 없으면 original source files를 추가로 업로드해야 한다고 적고 있다.

Sentry legacy sourcemap 문서는 <code>sourcesContent</code>가 없으면 original source files를 추가 업로드하라고 안내한다.

이 문장을 기준으로 보면 file=found, map=found, original source empty 조합은 업로드를 다시 전부 할 문제가 아니라, source map 내부와 original source 보조 업로드 순서 문제로 좁혀진다.

실무에서는 found/found인데 original source만 비는 경우를 별도 표로 두는 편이 좋다. 그래야 file path, map path, source content 문제를 한꺼번에 다시 뒤지지 않게 된다.

source file과 source map은 found인데 original source만 비는 경우의 점검 순서를 정리한 표다.

이 표를 쓰면 운영자가 먼저 sourcesContent 유무를 보고, 그다음 original source 업로드 여부, 마지막으로 local mapping 검증으로 이동하게 된다. 이미 source map lookup만 not_found인 글이 map reference 축을 다뤘다면, 이번 표는 그다음인 original source 축이다.

마지막 자료는 source map 내부 구조 예시다. sources는 있는데 sourcesContent가 비어 있으면 Sentry가 원본 소스 코드를 보여 주지 못할 수 있다.

source map 내부에서 <code>sources</code>와 <code>sourcesContent</code>를 같이 보는 예시다.

이 예시를 보면 file과 map이 모두 found여도 원본 소스가 보이지 않는 이유를 바로 이해할 수 있다. 결국 이 단계에서는 frame URL보다 source map payload 자체를 먼저 열어 봐야 한다.

5. 주의사항과 리스크

첫 번째 리스크는 file과 map lookup 성공을 source map 품질 성공으로 오해하는 것이다. 두 번째 리스크는 sourcesContent가 없는 source map을 그대로 올리고도 original source가 보이길 기대하는 것이다. 세 번째 리스크는 local mapping 검증을 건너뛰어 실제로는 column mapping이 틀린 문제를 original source 누락으로만 본다는 점이다.

운영 전에 확인할 때는 최소한 sourcesContent 유무, original source files 업로드 유무, local mapping 테스트 결과 세 칸을 남겨 두는 편이 좋다. 이 세 칸만 있으면 original source 비어 있음 문제는 대부분 빠르게 갈린다.

• file과 map found는 원본 소스 품질 보장이 아니다.
• sourcesContent와 original source 업로드는 별도 축이다.
• 마지막에는 local line / column mapping도 확인한다.

6. 결론

Sentry에서 source file과 source map은 found인데 original source만 비어 있다면, 먼저 sourcesContent와 original source files 업로드를 다시 보는 편이 맞다. 경로 축은 이미 통과했기 때문이다. source map 내부에 원본이 없으면 보조 업로드가 필요하고, 그다음에도 line이나 column이 이상하면 local mapping 품질을 봐야 한다. 이 순서를 분리해 두면 original source 누락 문제를 훨씬 짧게 진단할 수 있다.

• lookup found 이후에는 source content 축으로 이동한다.
• sourcesContent가 없으면 original source 업로드를 본다.
• 마지막에는 local mapping 품질을 검증한다.

이 분기를 Source Map Debug API 전체 상태표 안에서 다시 보고 싶다면 source file, source map, original source가 다르게 비어 있을 때 상태 조합을 먼저 나누는 글도 함께 보는 편이 좋다. original source missing이 전체 triage 표에서 어느 칸인지 바로 연결된다.

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/
3. https://docs.sentry.io/platforms/javascript/sourcemaps/troubleshooting_js/legacy-uploading-methods/
4. https://www.typescriptlang.org/tsconfig/inlineSources.html