[Sentry][프론트엔드] source map은 found인데 original source code 줄이 일부만 비어 있을 때 inlineSources와 sourceRoot를 어떤 순서로 다시 보나

IT 리서치 노트

[Sentry][프론트엔드] source map은 found인데 original source code 줄이 일부만 비어 있을 때 inlineSources와 sourceRoot를 어떤 순서로 다시 보나

Sentry source-map-debug API에서 source file과 source map이 모두 found인데, 이벤트 화면에서는 original source code 줄이 일부만 비거나 특정 파일만 덜 보이는 경우가 있다. 이때는 prefix나 release 이름부터 다시 뒤지기 쉽지만, 2026년 7월 10일 기준 Sentry 공식 문서를 다시 보면 source map 안의 `sourcesContent`, original source files 업로드, 그리고 TypeScript `inlineSources`와 `sourceRoot` 설정을 먼저 분리해 보라고 읽히는 구간이 분명하다. 이 글은 lookup은 통과했는데 original source code 줄이 일부만 비는 상황에서 inlineSources와 sourceRoot를 어떤 순서로 다시 봐야 하는지 정리한 것이다.

목차

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

1. 개요

결론부터 말하면 original source code 줄이 일부만 비는 경우에는 inlineSources와 sourceRoot를 같은 문제로 섞지 않는 편이 맞다. inlineSources는 source map 안에 원본 코드가 함께 들어 있느냐의 문제이고, sourceRoot는 sources 경로를 어떤 기준으로 해석하느냐의 문제다. 전체 original source가 아예 비는 경우는 먼저 sourcesContent와 original source upload 축을 보면 되지만, 일부 줄만 비는 경우는 sourceRoot와 local mapping 품질까지 함께 봐야 한다.

이미 original source만 비는 경우 점검 글이 sourcesContent와 original source upload 순서를 다뤘다면, 이번 글은 partial line gap에 맞춰 tsconfig와 sourceRoot까지 더 좁히는 후속편이다. 또 source_map_lookup_result not_found 글을 이미 통과했다면, 이번 분기는 경로 발견 이후의 map 품질 축이다.

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

현장에서 흔한 오해는 세 가지다. 첫째, source file과 source map lookup이 모두 found면 sourcemap 설정은 끝났다고 생각한다. 둘째, original source 줄이 일부만 비어도 release나 dist, prefix를 다시 맞추면 해결될 것이라 본다. 셋째, source map payload 안의 sourcesContent와 TypeScript sourceRoot를 구분하지 않고 한 번에 바꾸다가 범위만 넓힌다.

하지만 Sentry troubleshooting 문서는 source map이 원본 코드를 sourcesContent로 포함하는지 확인하라고 하고, line과 column mapping은 로컬에서 검증하라고도 적고 있다. legacy uploading methods 문서는 sourcesContent가 없다면 original source files를 추가로 제공해야 한다고 말한다. TypeScript tsc 가이드는 inlineSources와 sourceRoot를 함께 예시로 보여 준다. 이 세 문장을 묶어 읽으면 일부 줄만 비는 문제는 'upload 실패'보다 'map payload와 경로 해석이 부분적으로 어긋난 경우'에 더 가깝다.

특히 monorepo, generated code, transpiled path alias, dist 경로가 섞인 프론트엔드에서는 sourceRoot 하나 때문에 일부 파일만 비어 보이기도 하고, inlineSources가 빠져 특정 줄만 원본이 비어 보이기도 한다. 그래서 partial gap은 원본 전체 누락과 다른 분기표가 필요하다.

• 증상: source map은 found인데 특정 파일이나 특정 줄만 원본이 비어 보인다.
• 실패: release, dist, prefix를 다시 맞추는 것부터 시작한다.
• 막힘: sourcesContent, inlineSources, sourceRoot, local validate를 한 번에 바꿔 원인을 잃어버린다.
• 누락: partial gap과 complete gap을 서로 다른 triage로 나누지 않는다.

질문	먼저 볼 곳	이유
원본이 map 안에 있나	sourcesContent / inlineSources	원본 포함 여부 질문이다
일부 파일만 왜 비나	sourceRoot + sources 경로	경로 해석 질문이다
줄 번호가 왜 어긋나나	local mapping validate	line/column 품질 질문이다

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

가장 덜 꼬이는 순서는 네 단계다. 먼저 source-map-debug API에서 file/map lookup이 모두 found인지 확인한다. 두 번째로 source map payload에 sourcesContent가 있는지, 즉 inlineSources 계열 문제가 아닌지 본다. 세 번째로 일부 파일이나 일부 줄만 비어 있으면 sourceRoot와 sources 경로를 비교한다. 네 번째로 local source map validate를 돌려 line/column 매핑 품질을 확인한다. 이 순서를 지키면 path 발견 이후에 다시 prefix 진단으로 되돌아가는 낭비를 줄일 수 있다.

1. lookup found 상태를 먼저 고정한다.
2. sourcesContent와 inlineSources를 확인한다.
3. partial gap이면 sourceRoot와 sources 경로를 대조한다.
4. 마지막으로 local mapping validate를 실행한다.
5. 운영 로그에는 partial-gap 여부와 수정 축을 따로 남긴다.

이 순서가 좋은 이유는 문제 범위를 빠르게 줄여 주기 때문이다. 전체 original source가 비는 문제라면 sourcesContent와 original source upload 쪽에서 답이 나는 경우가 많다. 반대로 일부 파일이나 일부 줄만 비는 문제는 '원본 전체 부재'보다 '경로 해석 또는 특정 build 단계 품질' 쪽일 확률이 높다. 그래서 partial gap에서는 inlineSources와 sourceRoot를 따로 보고, 그 뒤에 local validate를 연결하는 편이 훨씬 짧다.

운영 메모 예시

lookup_state=file_found,map_found
sourcesContent_present=true
partial_original_source_gap=true
source_root_checked=/
local_validate_status=pending|passed|failed
fix_axis=inlineSources|sourceRoot|mapping_quality

운영 로그에 이 여섯 칸이 있으면 일부 줄이 비는 문제도 build config, upload payload, local mapping 가운데 어디에서 갈렸는지 금방 추적할 수 있다.

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

첫 자료는 Sentry JavaScript sourcemap troubleshooting 문서다. 여기서는 source map 안에 original source code가 `sourcesContent` 필드로 들어 있는지 먼저 확인하라고 안내한다.

Sentry troubleshooting 문서는 source map에 original source code가 sourcesContent로 들어 있는지 먼저 확인하라고 안내한다.

즉 file과 map lookup이 모두 found여도, source map 안에 실제 원본 코드가 비어 있으면 이벤트 화면의 일부 줄은 여전히 비거나 잘릴 수 있다. 이 경우 문제 축은 경로보다 map 내용이다.

두 번째 자료는 legacy uploading methods 문서다. 여기서는 `sourcesContent`가 없는 source map이라면 original source files를 별도로 제공해야 한다고 적혀 있다.

Sentry legacy sourcemap 문서는 sourcesContent가 없으면 original source files를 추가로 제공해야 한다고 설명한다.

이 문구는 '전체 original source가 완전히 비는 경우'뿐 아니라, 일부 줄이나 일부 파일만 비는 경우에도 source map payload 자체를 먼저 확인해야 하는 이유가 된다. 업로드는 성공했는데 포함된 원본이 조각난 상태일 수 있기 때문이다.

세 번째 자료는 Sentry의 TypeScript tsc 업로드 가이드다. 이 문서에는 `inlineSources`와 `sourceRoot`를 함께 설정하는 예시가 보인다.

Sentry TypeScript tsc 가이드는 inlineSources와 sourceRoot를 함께 설정하는 예시를 제공한다.

여기서 중요한 점은 둘이 같은 문제가 아니라는 것이다. inlineSources는 원본 코드를 map 안에 실을지, sourceRoot는 sources 경로를 어떤 기준으로 쓸지의 문제다. 일부 줄만 비는 경우에는 이 두 축을 같은 순서로 다시 보지 않으면 범위가 계속 넓어진다.

실무에서는 tsconfig diff가 가장 빠른 단서가 된다. inlineSources와 sourceRoot를 같이 본 tsconfig 예시를 남겨 두면, next build에서 어떤 설정이 빠졌는지 운영자가 바로 찾을 수 있다.

inlineSources와 sourceRoot를 함께 보는 tsconfig 예시다.

이 diff는 original source가 완전히 비는 경우 점검 글이 원본 업로드 축을 다뤘다면, 이번 글은 partial original-source 줄 누락을 tsconfig 레벨로 더 좁히는 역할을 한다.

마지막 자료는 partial gap triage 표다. 전체 original source가 비는 경우와 일부 줄만 비는 경우는 먼저 볼 곳이 다르다.

partial original-source 줄 누락에서 inlineSources와 sourceRoot를 나눠 보는 순서표다.

이 표처럼 나눠 두면 source map lookup not_found 글의 경로 축과, abs_path canonicalization 글의 frame path 축을 이미 통과한 뒤 어디로 들어가야 하는지 더 빨라진다.

5. 주의사항과 리스크

첫 번째 리스크는 partial original-source gap을 complete gap과 같은 문제로 다뤄 prefix나 release 진단을 반복하는 것이다. 두 번째 리스크는 inlineSources를 끈 상태에서 sourceRoot만 계속 바꿔 map payload 안의 원본 부재를 놓치는 것이다. 세 번째 리스크는 sourceRoot를 손본 뒤 local mapping validate를 건너뛰어 실제로는 line/column 매핑 품질 문제였다는 사실을 뒤늦게 발견하는 것이다.

운영 전에 확인할 때는 최소한 sourcesContent_present, source_root_checked, partial_original_source_gap, local_validate_status 네 칸을 한 표에 남기는 편이 좋다. 이 네 칸만 있어도 partial gap은 대부분 짧게 갈린다.

• inlineSources와 sourceRoot는 같은 종류의 문제가 아니다.
• partial gap은 complete gap보다 local validate 중요도가 높다.
• path 발견 이후에는 map 내용과 경로 해석 축으로 좁혀야 한다.

6. 결론

Sentry에서 source map은 found인데 original source code 줄이 일부만 비면, 먼저 inlineSources와 sourcesContent로 원본 포함 여부를 보고, 그다음 sourceRoot와 sources 경로를 보고, 마지막에 local mapping validate로 line/column 품질을 확인하는 편이 맞다. partial gap은 전체 업로드 실패가 아니라 map payload와 경로 해석의 부분 불일치인 경우가 많기 때문이다.

debug API에서 source_file_lookup_result=found와 source_map_lookup_result=found까지 확인됐는데도 라인 매핑이 어긋난다면, 새로 정리한 sourcesContent와 column mapping 후속 글으로 바로 넘어가면 된다. 이 글이 partial original-source gap을 다뤘다면, 후속 글은 found/found 이후에 column mismatch를 어디서 먼저 좁혀야 하는지에 집중한다.

• partial gap은 inlineSources 확인부터 시작한다.
• 일부 파일 누락이면 sourceRoot와 sources 경로를 본다.
• 일부 줄 어긋남은 local validate로 닫는다.

7. 참고 링크

1. https://docs.sentry.io/platforms/javascript/sourcemaps/troubleshooting_js/
2. https://docs.sentry.io/platforms/javascript/sourcemaps/troubleshooting_js/legacy-uploading-methods/
3. https://docs.sentry.io/platforms/javascript/guides/connect/sourcemaps/uploading/typescript/