[Sentry][프론트엔드] source map과 release는 맞는데 local validate만 column mismatch일 때 어떤 transform부터 다시 보나

IT 리서치 노트

[Sentry][프론트엔드] source map과 release는 맞는데 local validate만 column mismatch일 때 어떤 transform부터 다시 보나

Sentry에서 source map과 release 연결은 맞는데 local validate만 column mismatch로 남는 상황은 생각보다 자주 온다. 이때 release, dist, uploaded artifact를 다시 만지기 시작하면 범위만 커진다. 2026년 7월 12일 기준 Sentry 공식 문서를 다시 보면 source-map-debug API는 연결 상태를 좁혀 주고, troubleshooting 페이지는 업로드와 연결을 먼저 확인하라고 안내하며, TypeScript 업로드 가이드는 build 파이프라인 안에서 source map 생성과 업로드를 다루게 만든다. 이 글은 연결 계층이 이미 맞는 상황에서 local validate만 틀릴 때 어떤 transform부터 다시 보는 편이 빠른지 정리한 것이다.

목차

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

1. 개요

결론부터 말하면 source map과 release 연결이 이미 맞다면 local validate column mismatch는 build transform 순서를 먼저 본다. 원본 source map 생성, bundler merge, minifier 또는 post-process transform 순서로 내려가고, release나 prefix는 그 뒤에 남겨 둔다. line은 맞고 column만 어긋나는 문제는 연결 계층보다 변형 계층에서 더 자주 생긴다.

이미 sourcesContent와 column mapping 순서 글이 found/found 뒤 품질 축을 설명했다면, 이번 글은 그중에서도 local validate mismatch만 남을 때의 transform 우선순위를 더 좁힌 후속편이다.

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

현장에서 흔한 실수는 세 가지다. 첫째, local validate mismatch가 남으면 다시 release 이름이나 CDN prefix부터 고친다. 둘째, sourceRoot, inlineSources, minifier 설정, chunk merge를 한 번에 바꾼다. 셋째, local validate가 어떤 산출물을 기준으로 실행됐는지 기록하지 않는다. 이 세 가지가 겹치면 원인은 하나인데 수정 범위만 계속 커진다.

Sentry source-map-debug API는 연결 상태를 확인하는 용도이고, troubleshooting 페이지는 source map이 적용되지 않을 때 업로드와 연결을 먼저 확인하라고 말한다. 이 두 축이 이미 통과한 상태라면 다음 질문은 '어느 transform 뒤에 mapping이 틀어졌는가'여야 한다. TypeScript 업로드 가이드를 보면 source map 생성과 업로드가 build 파이프라인 안에 있고, 그 사이에 bundler나 minifier가 추가될 수 있다는 전제가 자연스럽게 드러난다.

• 증상: source map lookup은 맞는데 local validate에서만 column mismatch가 난다.
• 실패: release와 prefix를 다시 만지며 transform 원인을 놓친다.
• 막힘: sourceRoot, inlineSources, minifier 설정을 한 번에 바꾼다.
• 누락: validate가 어느 산출물 기준인지 메모를 남기지 않는다.

상태	먼저 볼 것	의미
debug API에서 found/found	local build chain	서버 연결보다 transform이 우선이다
line은 맞고 column만 틀림	minifier / post-process	후반 transform drift 가능성이 높다
prod build에서만 mismatch	prod-only plugin chain	개발 빌드와 다른 변형이 개입했을 수 있다

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

가장 덜 꼬이는 순서는 네 단계다. 먼저 source-map-debug API로 release와 uploaded artifact 연결이 실제로 맞는지 고정한다. 두 번째로 local validate 대상이 원본 tsc 산출물인지, bundler 뒤 산출물인지, minified prod 산출물인지 명시한다. 세 번째로 line은 맞고 column만 틀리면 후반 transform, 특히 minifier나 post-process plugin을 먼저 의심한다. 마지막으로 sourceRoot나 inlineSources 같은 경로 보조 설정은 transform 체인이 정리된 뒤에만 다시 본다.

1. debug API로 연결 성공 상태를 먼저 고정한다.
2. local validate가 어떤 산출물 기준인지 적는다.
3. column mismatch면 후반 transform부터 본다.
4. sourceRoot와 inlineSources는 마지막에 다시 본다.

이 순서가 좋은 이유는 단계가 서로 덮어쓰지 않기 때문이다. release와 artifact 연결이 맞다는 전제가 있어야 transform 원인에 집중할 수 있다. 반대로 이 전제가 없는데 local validate만 계속 돌리면 path 문제와 build 문제를 섞게 된다. 또 line은 맞고 column만 틀리는 경우는 compression, minify, transpile reordering 같은 후반 변형에서 더 자주 나타난다.

운영 메모 예시

debug_api=found/found
validate_target=prod_minified_bundle
transform_chain=tsc -> bundler -> minifier -> debug_id_inject
line_match=true
column_match=false

실무에서는 preview build나 no-minify build를 하나 더 만들어 local validate 결과를 비교하는 편이 좋다. no-minify에서는 맞고 prod-minify에서만 틀리면 변형 범위가 금방 줄어든다. 반대로 tsc 출력부터 틀리면 sourceRoot나 TypeScript source map 생성 설정을 더 먼저 봐야 한다.

• 연결 성공 상태를 먼저 고정한 뒤 transform을 본다.
• column mismatch는 후반 transform에서 먼저 의심한다.
• sourceRoot와 inlineSources는 마지막 단계에서 다시 본다.

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

첫 자료는 Sentry source-map-debug API 예시 응답이다. 여기에는 matching_source_map_name, source_file_lookup_result, source_map_lookup_result 같은 필드가 같이 보인다. 이 단계에서 source map과 release 연결이 맞다는 신호를 확인해야 이후 local validate 문제를 path mismatch와 구분할 수 있다.

Sentry source-map-debug API는 <code>matching_source_map_name</code>, <code>source_file_lookup_result</code>, <code>source_map_lookup_result</code>를 함께 보여 주며 release와 artifact 연결 상태를 좁히게 한다.

즉 이번 글의 출발점은 found/found 또는 그에 준하는 연결 성공 상태다. 이 상태라면 prefix, release, uploaded artifact보다 local build 결과와 transform 순서를 먼저 보는 편이 맞다.

두 번째 자료는 Sentry troubleshooting 페이지의 기본 분기다. 문서는 source maps가 적용되지 않으면 업로드 시점과 디버그 연결부터 먼저 확인하라고 안내한다. 반대로 그 단계가 이미 맞다면 남은 문제는 build output 품질 쪽으로 좁혀진다.

Sentry troubleshooting 문서는 source map 적용 여부를 먼저 업로드·연결 단계에서 확인하라고 안내한다.

이 문장 때문에 path와 release가 이미 맞는 상황에서는 같은 축을 다시 만지는 시간이 줄어든다. 이번처럼 local validate만 column mismatch일 때는 연결 계층보다 transform 계층을 먼저 보라는 뜻이 된다.

세 번째 자료는 Sentry TypeScript source map 업로드 가이드다. 이 문서는 tsc 기반 업로드가 따로 존재한다는 점을 보여 주고, source map 생성과 업로드가 build 단계에 붙어 있어야 한다는 전제를 준다. column mismatch가 local validate에서만 남는다면 실제 변형 단계가 tsc 뒤에 무엇이 또 붙는지 보는 편이 중요해진다.

Sentry TypeScript 가이드는 source map 생성과 업로드가 build 파이프라인의 일부여야 한다는 전제를 다시 확인하게 만든다.

즉 tsc가 source map을 만든 뒤 번들러, minifier, 추가 rewrite가 이어지는지 확인해야 한다. local validate mismatch는 종종 이 뒤쪽 단계에서 생긴다.

네 번째 자료는 Sentry CLI release management 문서다. 여기서는 release 관련 단계가 별도 관리 축이라는 점을 다시 보여 준다. release가 이미 맞는다는 가정이 확보되면, 남은 의심 대상은 transform과 local mapping 품질 쪽으로 더 빨리 좁혀진다.

Sentry CLI 문서는 release management를 별도 단계로 분리해 보여 주므로, release가 맞는 상황에서는 transform 품질 쪽으로 관심을 옮기게 한다.

따라서 column mismatch에서 release 이름을 다시 바꾸기 전에, 실제 build 체인에서 어떤 단계가 line은 유지하고 column만 밀어내는지부터 확인해야 한다.

실무에서는 transform 체인을 순서표로 남겨 두는 것이 가장 빠르다. source map 생성 시점, bundler 결합 시점, minifier 적용 시점, sentry upload 시점을 같은 줄에 놓으면 local validate mismatch가 어느 구간에서 생겼는지 좁히기 쉽다.

local validate만 column mismatch일 때 먼저 의심할 transform 순서를 정리한 표다.

이 표를 기준으로 보면 release와 sourceRoot를 한 번에 다시 바꾸지 않게 된다. 이미 line 매핑 mismatch 글이 sourcesContent와 column mapping 분기를 다뤘다면, 이번 글은 그 안에서 local validate만 어긋날 때의 transform 순서를 더 좁힌 후속편이다.

마지막 자료는 build chain을 텍스트로 기록한 예시다. 같은 line mapping이라도 어느 transform이 끝난 뒤 validate했는지 남기지 않으면, 팀원마다 서로 다른 build 산출물을 기준으로 column mismatch를 이야기하게 된다.

source map 생성 시점과 validate 시점을 함께 적은 build chain 메모 예시다.

이런 메모가 있으면 column mismatch를 release나 CDN 경로 문제로 되돌아가지 않고 local build 결과 문제로 바로 좁힐 수 있다. 또 scraping status와 uploaded artifact 글처럼 서버 측 연결 문제가 아닌 경우를 더 빠르게 제외할 수 있다.

5. 주의사항과 리스크

첫 번째 리스크는 found/found 상태에서도 release 문제라고 단정하고 다시 naming을 흔드는 것이다. 두 번째 리스크는 sourceRoot와 minifier를 동시에 바꿔 어떤 수정이 효과가 있었는지 잃는 것이다. 세 번째 리스크는 local validate가 dev build와 prod build 중 무엇을 기준으로 했는지 기록하지 않는 것이다.

운영 전에 확인할 때는 최소한 debug_api, validate_target, transform_chain, line_match, column_match 다섯 칸을 같은 표에 남겨 두는 편이 좋다. 이 다섯 칸이 없으면 column mismatch가 경로 문제인지 변형 문제인지 다음 배포에서도 다시 추측해야 한다.

• release가 맞는 상황에서는 naming을 다시 만지기 전에 transform을 본다.
• column mismatch는 sourceRoot보다 후반 변형일 확률이 높다.
• validate 기준 산출물을 항상 남긴다.

6. 결론

Sentry에서 source map과 release 연결이 맞는데 local validate만 column mismatch라면 build transform 순서를 먼저 본다. debug API로 연결 성공을 고정하고, local validate 대상 산출물을 분명히 적고, 후반 minify 또는 post-process 단계부터 좁혀 나가면 release나 prefix를 다시 흔드는 불필요한 왕복이 줄어든다.

• 연결 성공을 먼저 확인한다.
• validate 기준 산출물을 분명히 적는다.
• column mismatch는 transform 후반부터 좁힌다.

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/sourcemaps/uploading/typescript/
4. https://docs.sentry.io/cli/releases/