[Sentry][프론트엔드] Source Map Debug API에서 source file, source map, original source가 다르게 비어 있을 때 어떤 상태 조합으로 먼저 나누나

IT 리서치 노트

[Sentry][프론트엔드] Source Map Debug API에서 source file, source map, original source가 다르게 비어 있을 때 어떤 상태 조합으로 먼저 나누나

Sentry Source Map Debug API를 보기 시작하면 상태 필드가 많아서 오히려 더 헷갈릴 수 있다. 그런데 2026년 7월 15일 기준 Sentry 공식 문서를 다시 보면 API는 source_file_lookup_result, source_map_lookup_result, release_has_some_artifact 같은 전역/프레임 상태를 의도적으로 분리해 돌려준다. 이 글은 source file, source map, original source가 서로 다르게 비어 있을 때 어떤 조합부터 먼저 나눠 읽어야 하는지 정리한 것이다.

목차

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

1. 개요

결론부터 말하면 Source Map Debug API는 먼저 전역 플래그를 보고, 그 다음 frame 단위 상태 조합으로 내려가는 순서가 가장 빠르다. release에 artifact 자체가 없는 문제와, frame URL은 맞는데 map만 못 찾는 문제, 둘 다 찾았는데 original source만 비는 문제는 서로 다른 단계다.

따라서 '소스맵이 안 붙었다'는 한 문장으로 묶지 말고, source file, source map, original source를 अलग 실패면으로 나눠야 한다. 그래야 prefix, sourceMappingURL, sourcesContent, sourceRoot를 어디부터 다시 볼지 선다.

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

실무에서 가장 흔한 오해는 세 가지다. 첫째, source file이 not_found여도 source map이 문제라고 단정한다. 둘째, source file과 source map이 둘 다 found인데 original source code가 비어 있으면 release 업로드 실패라고 오해한다. 셋째, frame 상태를 보기 전에 release_has_some_artifact 같은 전역 플래그를 안 보고 바로 개별 파일 경로만 판다.

Sentry API 문서는 frame마다 source_file_lookup_result와 source_map_lookup_result를 따로 돌려주고, 동시에 release_has_some_artifact와 has_uploaded_some_artifact_with_a_debug_id도 같이 준다. 또 JavaScript sourcemaps 가이드는 Debug ID를 기본 연결 축으로 설명한다. 즉 triage는 legacy release naming, frame URL, Debug ID, original source 포함 여부를 한 번에 다 보는 것이 아니라 단계별로 분리해야 한다.

이 구분이 없으면 같은 증상으로 보이는 세 가지 케이스가 뒤섞인다. app.js 자체를 찾지 못하는 경우, app.js는 찾지만 map 파일 참조가 깨진 경우, app.js와 map은 찾았지만 sourcesContent가 비어 원본 라인이 안 나오는 경우는 해결 경로가 완전히 다르다.

• 증상: source maps는 올린 것 같은데 stack trace가 계속 읽기 어렵다.
• 실패: source file, source map, original source 실패를 한 묶음으로 본다.
• 막힘: 전역 artifact 플래그를 안 보고 frame 경로만 파고든다.
• 누락: Debug ID 축과 release 축을 어느 순서로 자를지 정하지 않는다.

실패 모습	먼저 볼 곳	해석
release_has_some_artifact=false	릴리스 업로드 전체	frame 이전에 artifact 공급 자체가 없다
source file found / source map not_found	sourceMappingURL	map 참조와 업로드 이름이 다를 수 있다
둘 다 found / original source empty	sourcesContent, sourceRoot	원본 소스 포함과 경로 매핑 문제다

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

가장 실용적인 순서는 다섯 단계다. 먼저 release_has_some_artifact와 Debug ID 관련 전역 플래그를 본다. 두 번째로 frame URL 기준 source file lookup 상태를 본다. 세 번째로 source map lookup 상태를 본다. 네 번째로 둘 다 found이면 original source 표시 여부를 본다. 마지막으로 그 상태 조합에 맞는 edge case 문서나 내부 체크리스트를 열고 다시 확인한다.

1. 전역 artifact 플래그를 먼저 본다.
2. source file lookup 상태를 본다.
3. source map lookup 상태를 본다.
4. 둘 다 found이면 original source 표시 여부를 본다.
5. 상태 조합별로 다음 체크 포인트를 고정한다.

triage memo

1. release_has_some_artifact 확인
2. has_uploaded_some_artifact_with_a_debug_id 확인
3. source_file_lookup_result 확인
4. source_map_lookup_result 확인
5. original source 표시 여부 확인

이 순서를 지키면 edge case가 빨리 분리된다. source file이 없으면 prefix와 uploaded artifact naming을 다시 확인하고, source map만 없으면 sourceMappingURL과 map 파일 이름을 다시 비교하면 된다. original source만 비어 있으면 이제 release naming보다 sourcesContent와 sourceRoot를 먼저 확인하면 된다.

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

첫 자료는 Sentry Source Map Debug API 응답 예시다. 문서는 frame마다 source_file_lookup_result와 source_map_lookup_result를 अलग 필드로 돌려준다. 즉 한 화면에서 source file과 source map 실패를 다른 상태로 읽게 설계돼 있다.

Source Map Debug API는 source_file_lookup_result와 source_map_lookup_result를 별도 상태로 돌려준다.

이 구조를 모르면 '소스맵이 안 붙었다'는 한 문장으로 모든 실패를 뭉개게 된다. 실제로는 파일명 매칭 실패, map 참조 실패, original source 누락이 서로 다른 단계다.

두 번째 자료는 같은 API의 상단 상태 필드다. project_has_some_artifact_bundle, release_has_some_artifact, has_uploaded_some_artifact_with_a_debug_id처럼 전역 상태를 함께 돌려준다. 즉 frame 단위 실패와 release 단위 실패를 한 번에 분리할 수 있다.

API는 frame 상태뿐 아니라 release 단위 artifact 존재 여부도 함께 돌려준다.

이 필드들이 중요하지 않다고 넘기면 frame만 파고들다가 release에 파일 자체가 없는 상황을 늦게 발견하게 된다. 먼저 전역 플래그를 보고, 그 다음 frame 조합으로 내려가는 편이 빠르다.

세 번째 자료는 JavaScript sourcemaps 가이드다. Sentry는 기본적으로 Debug ID를 build output에 주입해서 source map과 minified file을 연결한다고 설명한다. 즉 최신 경로에서는 release 이름뿐 아니라 Debug ID 연결이 기본 축이다.

Sentry는 기본 sourcemap 연결 축을 Debug ID 주입 방식으로 설명한다.

이 설명은 triage 순서를 바꾼다. debug_id_process가 틀리면 release naming이나 sourceMappingURL을 오래 볼 이유가 줄어든다. 먼저 연결 축부터 확인하고 비교해야 한다.

네 번째 자료는 Debug IDs 정의 페이지다. 문서는 transformed JavaScript file과 associated source map을 함께 식별하는 전역 ID라고 적는다. 즉 source file과 source map이 둘 다 found여도 Debug ID 축이 어긋나면 원본 연결이 끝까지 흔들릴 수 있다.

Debug ID는 minified file과 source map을 짝지어 주는 기본 식별자다.

따라서 source file, source map, original source를 나눌 때도 Debug ID 축을 먼저 켜고 가는 편이 좋다. release 기반 legacy 감각으로만 보면 frame별 상태 조합이 계속 헷갈린다.

실무에서는 상태 조합표가 가장 유용하다. source file은 found인데 source map만 not_found인지, 둘 다 found인데 original source만 비어 있는지에 따라 다음 행동이 완전히 달라진다.

Source Map Debug API 상태 조합별로 다음 점검 순서를 고정한 비교표다.

이미 source_map_lookup_result만 not_found인 글과 original source만 비어 있는 글을 읽었다면, 이번 표는 그 edge case들을 하나의 운영 분기판으로 묶는 역할이다.

마지막 자료는 API 응답을 로그에 요약하는 안전한 예시다. project 단위 플래그와 frame 단위 상태를 한 줄에 같이 남기면 어떤 글에서 다룬 edge case인지 즉시 분리할 수 있다.

Sentry Source Map Debug API 응답은 전역 플래그와 frame 상태를 같이 메모해야 재현이 빨라진다.

이 구조를 잡아 두면 라인 매핑 글이나 scraping status 글로 이어질 때도 어떤 축이 먼저 실패했는지 설명이 쉬워진다.

5. 주의사항과 리스크

frame 상태만 보고 전역 플래그를 무시하면 release 자체가 비어 있는 경우를 늦게 잡는다. 반대로 전역 플래그만 보고 frame 상태를 안 보면 prefix나 map 참조가 틀린 작은 문제를 놓친다. 둘을 순서대로 분리해 확인하는 감각이 필요하다.

또 Debug ID 연결 축이 무너졌는데 legacy release 이름만 붙잡고 있으면 해결이 늦어진다. 최신 JavaScript sourcemap 경로에서는 Debug ID 연결이 기본 전제이므로, has_uploaded_some_artifact_with_a_debug_id가 약하면 그 축부터 다시 보는 편이 낫다.

• 주의: 전역 플래그와 frame 상태를 같은 레벨에서 보지 않는다.
• 주의: source file, source map, original source는 서로 다른 실패 단계다.
• 주의: Debug ID 축이 약하면 release naming만으로는 오래 헤맨다.

6. 결론

Sentry Source Map Debug API를 읽을 때는 source file, source map, original source를 अलग 단계로 나눠야 빠르다. release 단위 artifact 플래그를 먼저 보고, 그 다음 frame별 source file과 source map 상태, 마지막으로 original source 노출 여부를 보면 어떤 체크리스트로 내려가야 할지가 바로 선다.

관련 흐름으로는 source map not_found 글, original source missing 글, scraping status와 uploaded artifact 분기 글을 같이 보면 edge case가 분류 체계 안으로 정리된다. 배포 체계가 Debug ID와 legacy release 업로드로 섞인 프로젝트라면 후속편인 혼합 프로젝트 분리 순서 글까지 이어서 보면 실제 운영 분기가 더 짧아진다.

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/
3. https://docs.sentry.io/platforms/javascript/sourcemaps/troubleshooting_js/debug-ids/
4. https://docs.sentry.io/platforms/javascript/sourcemaps/uploading/cli/