[Sentry][프론트엔드] release artifact bundle이 있는데도 매칭이 안 될 때 확인 순서

IT 리서치 노트

[Sentry][프론트엔드] release artifact bundle이 있는데도 매칭이 안 될 때 확인 순서

Sentry Project Settings에서 release artifact bundle은 보이는데 stack trace가 계속 난독화된 채 남는 경우가 있다. 2026년 6월 26일 기준 Sentry 공식 문서를 다시 보면 bundle 존재 여부만으로는 충분하지 않다. event가 어떤 release와 dist를 보고 있는지, Debug ID가 번들에 들어갔는지, 업로드 시점이 오류보다 앞섰는지를 같이 봐야 한다. 이 글은 그 순서를 정리한다.

목차

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

1. 개요

결론부터 말하면 release artifact bundle이 있다는 사실과 event가 그 bundle을 실제로 매칭했다는 사실은 다르다. 먼저 프로젝트가 Debug ID 기본 흐름인지, legacy release artifact 흐름인지 구분해야 한다. 그다음 event release와 dist, bundle 업로드 시점, Debug ID 주입 여부를 따로 본다.

이미 source map 기본 점검 글이나 Debug ID 누락 글을 읽었다면 이번 글은 그 다음 단계다. bundle 목록이 보이는데도 왜 event가 계속 안 풀리는지 좁히는 흐름을 다룬다.

배포 전에 sentry-cli sourcemaps validate 결과와 release 이름 검증 로그를 같이 남기는 운영 기준이 아직 없다면, 최근에 정리한 Sentry validate와 release 이름 확인 글부터 함께 보는 편이 다음 배포에서 같은 증상을 줄이기 쉽다.

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

현장에서 자주 나오는 증상은 세 가지다. 첫째, Project Settings의 Artifact Bundles 탭에는 bundle이 있는데 event stack trace는 난독화 상태로 남아 있다. 둘째, release 이름은 맞는 것 같은데 event와 bundle이 연결되지 않는다. 셋째, Debug ID 기반 프로젝트와 release artifact 기반 설정이 섞여 있어 어떤 규칙을 기대해야 하는지 애매하다.

Sentry 문서는 기본적으로 Debug ID 주입을 권장한다. 그런데 일부 프로젝트는 아직 release artifact 기반 업로드를 쓰거나, migration 중이라 둘이 섞여 있다. 이 상태에서 bundle 존재 여부만 보면 event release, dist, Debug ID, 업로드 시점 중 무엇이 어긋났는지 놓치기 쉽다.

• 증상: artifact bundle은 보이는데 event stack trace가 계속 난독화돼 있다.
• 실패: release 이름만 보고 dist나 Debug ID를 같이 확인하지 않는다.
• 막힘: 오류 발생 뒤에 bundle을 올리고도 기존 event가 풀릴 것이라 기대한다.
• 누락: Debug ID 기반과 legacy release 기반을 같은 흐름으로 본다.

증상	먼저 볼 곳	판단 기준
bundle은 보이는데 event가 안 풀린다	event release, dist, Debug ID	event가 실제로 같은 식별자를 보고 있는지 본다
release 이름은 같은데 매칭 실패	artifact bundle 연결 방식	legacy release artifact인지 Debug ID 기반인지 먼저 가른다
배포 직후에만 안 풀린다	업로드 시점과 오류 시점	오류 발생 전에 업로드됐는지 확인한다

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

점검 순서는 다섯 단계가 가장 빠르다. 먼저 event detail에서 release와 dist를 확인한다. 둘째, 해당 release에 연결된 artifact bundle 또는 release artifact를 Project Settings에서 확인한다. 셋째, 빌드 산출물에 Debug ID가 주입됐는지 본다. 넷째, 업로드 커맨드가 오류 발생 전에 실행됐는지 배포 로그로 대조한다. 마지막으로 legacy release matching을 쓰는 프로젝트인지 분리한다.

1. event release와 dist를 먼저 확인한다.
2. 해당 release의 artifact bundle을 Project Settings에서 본다.
3. 빌드 결과에 Debug ID가 들어갔는지 확인한다.
4. 업로드 시점이 오류보다 앞섰는지 배포 로그와 맞춘다.
5. legacy release matching 여부를 따로 판단한다.

운영 메모 예시

event_release: frontend@2026.06.26
event_dist: web
bundle_visible: true
debug_id_in_bundle: true
upload_before_errors: false
matching_mode: debug_id

이 메모만 있어도 bundle 존재 여부와 실제 매칭 조건을 분리할 수 있다. 예를 들어 bundle은 보이지만 upload_before_errors가 false라면 release 이름을 더 보정하기보다 업로드 시점을 먼저 고쳐야 한다.

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

첫 화면은 Sentry JavaScript source maps 가이드의 기본 원리다. artifact bundle이 존재해도 매칭이 안 된다면 먼저 현재 프로젝트가 Debug ID 기반인지, release artifact 기반인지 구분해야 한다.

Sentry source maps 가이드는 기본 연결 방식이 Debug ID 주입이라는 점을 먼저 설명한다.

즉 artifact bundle이 보인다는 사실만으로 event와 자동 매칭된다고 보면 안 된다. 빌드 산출물 안의 Debug ID, release 이름, 업로드 시점이 서로 어떻게 연결되는지 먼저 나눠 봐야 한다.

두 번째 자료는 Sentry troubleshooting 문서의 기본 점검 순서다. release artifact bundle이 있는데도 매칭이 안 될 때 가장 먼저 확인할 항목은 bundle 존재 여부보다 업로드 시점과 event 발생 시점이다.

Troubleshooting 문서는 오류가 나기 전에 source map과 소스가 업로드돼 있어야 한다고 분명히 적는다.

이 원칙을 놓치면 artifact bundle이 보여도 실제 event는 이미 이전 배포 산출물로 들어온 상태일 수 있다. 그 경우 bundle 목록만 오래 들여다봐도 답이 나오지 않는다.

세 번째 화면은 CLI 업로드 가이드에서 project settings의 Artifact Bundles 탭을 확인하는 구간이다. 여기서는 bundle이 보이는지뿐 아니라 어떤 release와 연결됐는지, 어떤 debug files가 포함됐는지를 같이 봐야 한다.

CLI 가이드는 Project Settings의 Artifact Bundles 화면에서 업로드 결과를 확인하라고 안내한다.

artifact bundle이 있다는 사실과 event 매칭 성공은 다르다. release 속성을 같이 줬는지, bundle 안에 필요한 파일이 들어갔는지까지 확인해야 실제 문제 범위가 줄어든다.

네 번째 자료는 legacy release matching 설명이다. 프로젝트 일부는 Debug ID 기반이고 일부는 release artifact 기반일 수 있으므로, 혼합 상태에서 어떤 매칭 규칙을 기대하는지 먼저 정해야 한다.

legacy uploading 문서는 Debug ID 대신 release 기반으로 artifact를 매칭하는 흐름을 따로 설명한다.

이 비교가 필요한 이유는 release 이름은 맞는데 bundle 매칭이 안 되는 상황이 종종 이중 구성에서 나오기 때문이다. release만 맞추면 끝나는지, Debug ID도 번들 안에 살아 있어야 하는지 프로젝트 방식부터 확인해야 한다.

실무에서는 UI보다 CLI 확인이 빠를 때가 많다. event에 찍힌 release 이름과 Debug ID를 보고 업로드 커맨드가 어떤 release 속성을 가졌는지 같이 대조하면 bundle 존재 여부보다 더 빨리 원인을 좁힐 수 있다.

Sentry CLI 점검 예시는 release 생성, sourcemaps 업로드, 업로드 확인 순서를 한 화면에 정리한다.

중요한 점은 업로드 후 바로 확인 커맨드를 남겨 두는 것이다. 그래야 배포 직후와 장애 시점 사이에 어떤 bundle이 있었는지 다시 비교할 수 있다.

마지막 자료는 매칭 실패 점검표다. release artifact bundle이 이미 보이는 상태라면 이제는 bundle 존재 자체보다 event release, Debug ID 주입, 업로드 시점, dist 값을 따로 확인하는 편이 빠르다.

artifact bundle 매칭 실패 점검표는 bundle 존재 여부와 실제 event 매칭 조건을 분리해서 보게 한다.

이 표를 기준으로 보면 기존의 source map 기본 점검 글과 Debug ID 누락 글을 어느 단계에서 다시 참고해야 하는지 분명해진다.

5. 주의사항과 리스크

첫 번째 리스크는 Artifact Bundles 탭에 항목이 보인다는 이유만으로 매칭이 끝났다고 보는 것이다. 두 번째 리스크는 release 이름만 확인하고 dist와 Debug ID를 함께 보지 않는 것이다. 세 번째 리스크는 migration 중인 프로젝트에서 legacy release artifact와 Debug ID 규칙을 섞어 생각하는 것이다.

운영 전에는 release, dist, Debug ID, 업로드 시점 네 가지를 한 줄 메모로 남기는 편이 좋다. 그래야 bundle이 있는데도 event가 안 풀리는 상황을 다시 만났을 때 문제 범위를 빠르게 줄일 수 있다.

• bundle 존재와 event 매칭 성공은 별개의 조건이다.
• Debug ID 기반인지 legacy release 기반인지 먼저 가른다.
• 오류 발생 전 업로드 여부를 배포 로그로 확인한다.

6. 결론

Sentry에서 release artifact bundle이 보이는데도 stack trace가 안 풀린다면 release 이름만 보지 말고 event release와 dist, Debug ID 주입, 업로드 시점을 같이 봐야 한다. bundle이 있다는 사실보다 event가 어떤 식별자로 그 bundle을 찾는지가 더 중요하다.

증상이 배포 직후 반복된다면 운영 체크를 두 갈래로 나누면 된다. 이 글로 bundle 존재 이후의 매칭 실패를 좁히고, 배포 전 검증은 validate와 release 이름 점검 글 기준으로 남기면 같은 문제를 다음 배포 전에 더 빨리 막을 수 있다.

• event release와 dist를 먼저 본다.
• Debug ID 주입 여부를 bundle 안에서 확인한다.
• 업로드 시점이 오류보다 앞선다는 원칙을 지킨다.

7. 참고 링크

1. https://docs.sentry.io/platforms/javascript/sourcemaps/
2. https://docs.sentry.io/platforms/javascript/sourcemaps/troubleshooting_js/
3. https://docs.sentry.io/platforms/javascript/sourcemaps/troubleshooting_js/debug-ids/
4. https://docs.sentry.io/platforms/javascript/sourcemaps/uploading/cli/
5. https://docs.sentry.io/platforms/javascript/guides/react/sourcemaps/troubleshooting_js/legacy-uploading-methods/