[Sentry][프론트엔드] release와 dist가 event와 어긋날 때 validate 다음으로 볼 값을 정리하는 법

IT 리서치 노트

[Sentry][프론트엔드] release와 dist가 event와 어긋날 때 validate 다음으로 볼 값을 정리하는 법

Sentry source map 파이프라인에서 `--validate`를 통과했는데도 이벤트가 계속 난독화되는 경우가 있다. 2026년 7월 2일 기준 Sentry 공식 문서를 다시 보면, release와 dist를 쓰면 artifact lookup이 더 구체적이 되는 대신 더 덜 관대해지고, source-map-debug API는 실제 이벤트 기준으로 release와 dist를 함께 보여 준다. 이 글은 validate 다음 단계에서 무엇을 봐야 하는지 정리한 것이다.

목차

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

1. 개요

결론부터 말하면 Sentry에서 --validate가 통과했는데도 source map이 안 풀리면, 다음에는 이벤트가 기록한 release와 dist를 artifact upload 값과 비교해야 한다. 공식 CLI 가이드는 dist를 쓸 때 SDK에도 같은 release와 dist를 넣어야 한다고 적고 있고, source-map-debug API는 실제 event 기준으로 release, dist, debug ID 매칭 상태를 보여 준다.

이미 validate와 release 검증 글이 배포 전 기본 게이트를 다뤘다면, 오늘 글은 그 뒤의 event 기준 dist 진단이다. 또 artifact bundle 매칭 글과 Debug ID 누락 글 사이를 이어 준다.

event 기준 dist mismatch를 확인하기 전에 dist naming 자체를 build number와 배포 variant 기준으로 고정하고 싶다면 dist를 build number와 배포 variant에 맞추는 운영 기준 글을 먼저 보고 오는 편이 좋다.

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

실무에서 자주 꼬이는 지점은 네 가지다. 첫째, validate 통과만 보고 naming은 항상 맞을 것이라고 생각한다. 둘째, upload에는 --dist를 넣었는데 SDK 이벤트에는 dist를 안 넣거나 다른 값을 넣는다. 셋째, release는 같지만 dist가 달라 artifact lookup이 더 이상 forgiving하지 않다는 점을 놓친다. 넷째, event 기준으로 무엇이 어긋났는지 API나 UI에서 직접 확인하지 않는다.

공식 문서는 dist를 쓰면 artifact upload가 더 specific해지는 대신 process 전체가 less forgiving해질 수 있다고 설명한다. 즉 naming을 더 정밀하게 만들 수 있는 대신, 파이프라인 어디선가 이름이 조금만 달라도 매칭이 바로 실패할 수 있다.

validate는 source map 구조를 보는 단계고, dist mismatch는 이벤트와 artifact lookup을 보는 단계다. 구조 문제와 naming 문제를 구분하지 않으면 한쪽을 고쳤는데도 같은 증상이 반복되는 일이 잦다.

• 증상: validate는 PASS인데 이벤트는 계속 난독화된다.
• 실패: upload와 event의 dist를 로그에 같이 남기지 않는다.
• 막힘: artifact bundle 문제와 naming 문제를 한 번에 고치려 든다.
• 누락: source-map-debug API로 실제 event 기준 진단을 하지 않는다.

증상	먼저 볼 곳	판단 기준
validate PASS, 난독화 지속	event release/dist와 upload release/dist	값이 동일한지 먼저 본다
release는 맞는 듯한데 일부 이벤트만 실패	dist 값	환경별 build variant가 다르지 않은지 본다
artifact bundle은 있는데 원인 불명	source-map-debug API	release lookup, debug ID lookup, dist를 event 기준으로 본다

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

진단 순서는 다섯 단계면 충분하다. 먼저 validate로 구조를 확인한다. 두 번째로 inject와 upload가 정상인지 본다. 세 번째로 upload에 넣은 release와 dist를 기록한다. 네 번째로 SDK 이벤트가 실제로 어떤 release와 dist를 보냈는지 확인한다. 마지막으로 source-map-debug API로 event 기준 lookup 결과를 받아 naming mismatch인지 artifact 문제인지 분리한다.

1. --validate로 source map 구조를 먼저 확인한다.
2. inject와 artifact upload를 확인한다.
3. upload release/dist 값을 로그에 남긴다.
4. SDK 이벤트의 release/dist를 같은 로그에서 확인한다.
5. source-map-debug API로 event 기준 lookup 결과를 본다.

source-map-debug API 호출 예시

curl https://sentry.io/api/0/projects/ORG/PROJECT/events/EVENT_ID/source-map-debug/   -H 'Authorization: Bearer YOUR_TOKEN'

API 응답에서 먼저 볼 값은 release, dist, has_debug_ids, release_has_some_artifact, project_has_some_artifact_bundle다. 이 다섯 값만으로도 dist mismatch인지, release 생성 누락인지, artifact bundle 부재인지 방향을 빠르게 자를 수 있다.

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

첫 화면은 Sentry sourcemap troubleshooting 가이드의 `--validate` 설명이다. source map 구조 검증은 여전히 첫 단계지만, dist와 release mismatch는 그다음 층위라는 점을 같이 봐야 한다.

Sentry는 `sourcemaps upload --validate`로 source map 구조를 먼저 검증하라고 안내한다.

즉 validate 통과는 출발점일 뿐이다. 구조는 맞는데 이벤트와 artifact bundle이 release 또는 dist에서 어긋나면 여전히 난독화가 남을 수 있다.

두 번째 자료는 CLI upload 가이드의 release/dist 설명이다. 문서는 `--dist`를 쓸 때 SDK 쪽에도 같은 release와 dist를 넣어야 한다고 적고 있다.

Sentry CLI 가이드는 artifact upload에 dist를 붙였다면 SDK 이벤트에도 같은 release와 dist가 있어야 한다고 설명한다.

이 문장을 놓치면 upload는 성공했는데 이벤트가 다른 dist로 기록돼 bundle lookup이 계속 빗나갈 수 있다. validate는 통과했는데 실제 이벤트는 다른 release/dist 조합으로 들어오는 상황을 분리해야 한다.

세 번째 화면은 release와 dist를 쓰면 매칭이 더 엄격해진다는 공식 설명이다. 값이 더 구체적이 되는 대신 파이프라인이 덜 관대해진다는 점을 먼저 받아들여야 한다.

Sentry는 release와 dist를 쓰면 artifact upload가 더 구체적이지만 전체 과정은 덜 관대해진다고 경고한다.

이 말은 dist를 넣는 순간 source map 문제를 더 정확히 좁힐 수 있지만, 배포 파이프라인 어디선가 이름이 조금만 어긋나도 매칭이 깨질 수 있다는 뜻이다. 그래서 release와 dist를 한 로그 묶음으로 남겨야 한다.

네 번째 자료는 Sentry source-map-debug API다. validate 다음 단계에서 실제 event가 어떤 release와 dist로 들어왔는지, release lookup과 debug ID lookup이 어떤 결과를 냈는지 여기서 확인할 수 있다.

Sentry source-map-debug API는 이벤트 기준 release, dist, debug ID 매칭 상태를 한 응답으로 돌려준다.

운영에서는 이 API가 가장 실용적이다. artifact bundle이 존재하는지, debug ID가 맞는지, release lookup이 성공했는지를 같은 event 기준으로 확인할 수 있어 dist mismatch를 구조 문제와 분리해 준다.

다섯 번째 자료는 CI 로그와 source-map-debug API 확인을 묶은 예시다. 배포 직전 validate를 통과했더라도, 실제 event가 다른 dist로 들어오면 이 블록에서 바로 차이가 보이게 만드는 편이 좋다.

validate 결과와 source-map-debug API 응답 핵심 값을 같은 로그에 묶으면 dist mismatch를 설명하기 쉽다.

이미 validate와 release 검증 글을 읽었다면, 이번 예시는 그 다음 단계인 event 기준 dist 진단이라고 보면 된다. 또 artifact bundle 매칭 글과도 바로 이어진다.

마지막 자료는 dist mismatch 진단 순서다. validate, inject, release, dist, source-map-debug API 순서로 보면 구조 문제와 naming 문제를 빠르게 나눌 수 있다.

dist mismatch 진단 체크리스트는 source map 구조 문제와 event naming 문제를 서로 다른 단계로 분리한다.

이 표를 두면 Sentry 프론트엔드 클러스터에서 Debug ID, artifact bundle, validate, dist mismatch가 자연스럽게 연결된다. 후속 내부 링크용 허브로도 쓰기 좋다.

5. 주의사항과 리스크

첫 번째 리스크는 dist를 쓰면서 SDK 이벤트와 upload 값을 따로 관리하는 것이다. 두 번째 리스크는 validate가 통과하면 naming도 맞을 것이라고 가정하는 것이다. 세 번째 리스크는 source-map-debug API를 보지 않고 artifact bundle UI만 반복해서 확인하는 것이다.

운영 메모에는 최소한 upload release/dist, event release/dist, source-map-debug API 핵심 필드를 함께 남겨 두는 편이 좋다. 그래야 source map 구조 문제와 event naming 문제를 같은 배포 로그 안에서 분리할 수 있다.

• validate는 구조 확인 단계다.
• dist mismatch는 event naming 단계다.
• API 응답으로 event 기준 값을 확인한다.

6. 결론

Sentry에서 validate 다음 단계는 이벤트가 실제로 어떤 release와 dist를 보냈는지 확인하는 일이다. dist를 쓰면 더 정확해지는 대신 덜 관대해지므로, source-map-debug API로 event 기준 lookup을 확인해야 naming mismatch를 구조 문제와 분리할 수 있다.

• validate 다음에는 release/dist를 본다.
• event 기준으로 lookup 결과를 확인한다.
• 구조 문제와 naming 문제를 분리한다.

7. 참고 링크

1. https://docs.sentry.io/platforms/javascript/sourcemaps/troubleshooting_js/
2. https://docs.sentry.io/platforms/javascript/sourcemaps/uploading/cli/
3. https://docs.sentry.io/api/events/get-debug-information-related-to-source-maps-for-a-given-event/