-
[Sentry][프론트엔드] dist를 build number와 배포 variant에 맞추는 기준을 sourcemap 운영 기준으로 정리기타개발지식/풀스택개발 2026. 7. 3. 20:13
IT 리서치 노트
[Sentry][프론트엔드] dist를 build number와 배포 variant에 맞추는 기준을 sourcemap 운영 기준으로 정리
Sentry sourcemap 운영에서 release 이름은 맞는데 dist가 자꾸 흔들리면 validate와 debug ID를 아무리 봐도 일부 이벤트만 계속 난독화될 수 있다. 2026년 7월 3일 기준 Sentry 공식 문서를 다시 보면 dist는 build number나 deployment variant를 구분하는 값으로 쓰이고, upload와 SDK 이벤트의 release/dist 값은 동일해야 하며, source-map-debug API는 실제 이벤트 기준 dist를 다시 보여 준다. 이 글은 dist를 build number와 배포 variant에 맞추는 기준을 운영 관점에서 정리한 것이다.
1. 개요
결론부터 말하면 dist는 '있으면 좋고 없어도 되는 값'이 아니라, 여러 빌드나 여러 배포 variant가 같은 release 이름을 공유할 때 번들을 분리하는 키다. 하나의 release에 실제 배포 아티팩트가 하나뿐이면 dist를 생략해 naming 축을 줄이는 편이 낫고, build number나 채널별 번들이 갈리면 dist를 명시적으로 고정하는 편이 안전하다.
이미 validate와 release 검증 글이 배포 전 기본 게이트를 다뤘다면, 이번 글은 dist를 언제 naming 축으로 써야 하는지에 더 가깝다. 또 release와 dist mismatch 글을 같이 보면 사전 naming 기준과 사후 event 진단이 연결된다.
dist 이름을 맞췄는데도 일부 이벤트만 계속 난독화된다면, 이어서 CDN 경로와 해시 파일명 때문에 매칭이 안 될 때 rewriteFrames와 event lookup을 같이 보는 글로 넘어가 보는 편이 낫다. 이 글이 naming 축을 정리했다면, 후속 글은 path 축을 정리한다.
validate와 dist naming을 맞춘 뒤에도 event frame이 안 풀린다면, 다음 단계로는 artifact bundle은 있는데 dist mismatch 때문에 event frame이 안 풀릴 때 어떤 로그 필드를 남겨야 하는지 다룬 후속 글을 같이 보는 편이 좋다. 지금 글이 dist naming 기준을 고정했다면, 후속 글은 event-level triage 로그를 고정한다.
2. 어디서 실제로 막히는가
실무에서 먼저 꼬이는 지점은 세 가지다. 첫째, 같은 release 이름 아래 staging, production, 모바일 build를 모두 넣어 두고 dist는 환경에 따라 제각각 쓴다. 둘째, upload에는 dist를 넣었는데 SDK 이벤트에는 release만 넣는다. 셋째, dist가 꼭 필요한 상황이 아닌데도 모든 빌드에 무조건 dist를 붙여 naming 조합만 늘린다.
Sentry release 문서는 dist를 build number나 deployment variant 구분값으로 설명하고, JavaScript sourcemap upload 문서는 SDK 옵션과 upload 값이 identical해야 한다고 적는다. source-map-debug API는 실제 event 기준 dist와 release를 다시 보여 준다. 이 셋을 같이 읽으면 dist는 '추가 메타데이터'가 아니라 event lookup 키라는 점이 분명해진다.
- 증상: release는 맞는데 일부 배포 채널만 난독화가 남는다.
- 실패: build number와 deployment variant를 dist에 섞어 쓴다.
- 막힘: upload dist와 SDK dist를 같은 로그에 남기지 않는다.
- 누락: event 기준 source-map-debug API로 실제 dist를 확인하지 않는다.
상황 dist 필요성 먼저 볼 기준 단일 웹 배포 낮음 release만으로 충분한지 본다 staging/prod 동시 운영 높음 variant 이름을 dist에 고정한다 모바일 build 반복 배포 높음 build number를 dist로 본다 3. 실무에서 적용하는 순서
운영 기준은 네 단계면 충분하다. 먼저 하나의 release에 실제 번들이 몇 종류인지 센다. 두 번째로 번들이 여러 종류면 dist에 build number 또는 deployment variant 중 하나만 고정한다. 세 번째로 upload와 SDK 이벤트가 같은 release/dist를 쓰게 한다. 마지막으로 event가 생기면 source-map-debug API로 실제 dist가 그 값으로 들어왔는지 확인한다.
- release 하나에 번들이 몇 종류인지 먼저 센다.
- dist가 필요하면 build number 또는 variant 한 축만 택한다.
- upload와 SDK 이벤트에 같은 값을 넣는다.
- event 기준 source-map-debug API로 다시 확인한다.
핵심은 dist를 습관적으로 늘리지 않는 것이다. variant를 굳이 구분할 필요가 없으면 release 하나만 쓰는 편이 단순하고, variant를 꼭 구분해야 하면 naming 축을 하나로 고정하는 편이 맞다.
이렇게 두면 validate 이후에 naming mismatch를 봐야 할지, artifact bundle 자체를 봐야 할지 방향이 빨리 정리된다.
4. 공식 문서와 예시 화면으로 확인하기
첫 자료는 Sentry release management 문서의 `dist` 설명이다. 문서는 dist를 build number나 deployment variant를 구분하는 값으로 쓸 수 있다고 적고 있다.
즉 dist는 단순 부가 태그가 아니라, 같은 release 안에서 어떤 번들이 실제로 배포됐는지 가르는 키다. 같은 파일명이 여러 variant에 걸쳐 재사용될수록 중요해진다.
두 번째 화면은 JavaScript sourcemap upload CLI 가이드다. release와 dist를 upload에 넣었다면 SDK 옵션에도 같은 값을 넣으라고 명시한다.
여기서 build number를 dist로 쓸지, 배포 채널명을 dist로 쓸지 먼저 정하지 않으면 팀마다 naming이 흔들린다. validate가 통과해도 event 매칭은 실패할 수 있다.
세 번째 자료는 source-map-debug API 응답 예시다. 이 응답에는 event 기준 release와 dist, debug ID lookup 결과가 같이 들어간다.
즉 dist naming이 맞는지 확인할 때는 upload 로그만 보는 대신 event가 실제로 어떤 dist를 보냈는지까지 같이 봐야 한다.
dist를 무엇으로 잡을지 정할 때는 build number와 deployment variant를 한 표에 놓고 비교하는 편이 빠르다. 둘을 섞어 쓰면 일부 환경만 매칭이 어긋나기 쉽다.
이미 release와 dist mismatch 글이 event 진단을 다뤘다면, 이번 표는 dist naming 자체를 사전에 고정하는 단계다.
마지막 자료는 release/dist 운영 메모 예시다. upload 값과 SDK 이벤트 값을 같은 줄에 남기면 validate 이후에 naming mismatch를 더 빨리 좁힐 수 있다.
이 메모가 있으면 post 80의 validate 기록, post 83의 event 기준 dist 진단, post 50의 artifact bundle 진단을 한 흐름으로 묶기 쉽다.
5. 주의사항과 리스크
첫 번째 리스크는 dist를 build number와 variant 두 뜻으로 섞어 써서 naming이 매 배포마다 바뀌는 것이다. 두 번째 리스크는 SDK에는 dist를 안 넣고 upload에만 넣는 것이다. 세 번째 리스크는 단일 번들 배포인데도 dist를 강제해 불필요한 mismatch 지점을 만드는 것이다.
운영 메모에는 최소한 release, dist, upload 명령, event 기준 dist를 같이 남기는 편이 좋다.
- dist가 필요 없는 상황에는 release만 쓴다.
- dist가 필요하면 naming 축을 하나로 고정한다.
- event 기준 dist를 API로 다시 확인한다.
6. 결론
Sentry dist는 여러 번들 variant를 같은 release 아래서 구분할 때만 명시적으로 쓰는 편이 좋다. build number와 deployment variant 중 어떤 축을 dist로 쓸지 먼저 고정하고, upload와 SDK 이벤트에 같은 값을 넣으면 validate 이후의 매칭 실패를 훨씬 덜 만들 수 있다.
- 단일 번들이면 dist를 생략해도 된다.
- 여러 variant면 dist를 naming 키로 고정한다.
- source-map-debug API로 event 기준 값을 확인한다.
7. 참고 링크
'기타개발지식 > 풀스택개발' 카테고리의 다른 글
