[Sentry][프론트엔드] Debug ID와 legacy release 업로드가 섞인 프로젝트에서 Source Map Debug API 상태를 어떤 순서로 먼저 분리하나

IT 리서치 노트

[Sentry][프론트엔드] Debug ID와 legacy release 업로드가 섞인 프로젝트에서 Source Map Debug API 상태를 어떤 순서로 먼저 분리하나

Sentry sourcemap 운영을 오래 끌고 온 프로젝트에서는 일부 앱은 Debug ID로, 일부 배포 잡은 release artifact로 남아 있는 경우가 의외로 많다. 2026년 7월 15일 기준 Sentry 공식 문서를 다시 보면 최신 JavaScript 흐름은 Debug ID 주입을 기본으로 설명하지만, legacy tooling은 여전히 Releases로 이벤트를 매칭한다. 이 글은 Source Map Debug API를 볼 때 혼합 프로젝트 증상을 어떤 순서로 먼저 분리해야 하는지 정리한 것이다.

목차

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

1. 개요

결론부터 말하면 혼합 프로젝트에서는 frame URL부터 파지 말고, 먼저 현재 배포가 Debug ID 체계인지 legacy release 체계인지부터 분리해야 한다. Source Map Debug API는 그 분기를 위해 전역 플래그와 frame lookup 상태를 같이 돌려준다.

즉 문제는 'source map이 안 풀린다'가 아니라 '이 이벤트가 어느 매칭 체계로 해석돼야 하는데 실제 업로드 체계가 무엇이었나'로 바꿔 묻는 편이 맞다. 이 분기만 제대로 잡아도 naming, dist, original source 점검 순서가 짧아진다.

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

실무에서 가장 흔한 막힘은 세 가지다. 첫째, 업로드 파이프라인은 새 번들러 플러그인을 쓰는데 실제 배포 bundle에는 Debug ID가 안 들어 있다. 둘째, 일부 패키지는 여전히 release 기반 legacy upload인데 프로젝트 전체를 Debug ID 기준으로 가정한다. 셋째, Source Map Debug API를 봐도 release 전역 상태와 frame 단위 상태를 같은 문제로 읽어 버린다.

이런 상황에서는 validate 성공, artifact upload 성공 같은 개별 신호가 오히려 함정이 된다. 최신 체계와 legacy 체계는 같은 자원을 다른 키로 매칭하기 때문에, 성공 로그가 남아도 실제 이벤트에서는 lookup 축이 엇갈릴 수 있다.

• 증상: 일부 에러는 잘 풀리는데 특정 앱이나 특정 번들만 전혀 안 풀린다.
• 실패: release 성공 로그와 Debug ID 주입 여부를 같은 층으로 본다.
• 막힘: Source Map Debug API에서 전역 플래그와 frame 상태를 같이 기록하지 않는다.
• 누락: 런타임 bundle에 실제 Debug ID가 있는지 확인하지 않는다.

신호	먼저 볼 것	의미
Debug ID 관련 플래그는 보이는데 frame lookup이 naming 축에서 실패	런타임 배포물	주입과 실제 배포가 어긋났을 수 있다
release artifact는 있는데 일부 앱만 전혀 안 풀림	legacy release 경로	release/dist 로그가 앱마다 다를 수 있다
프로젝트 전체가 들쭉날쭉함	혼합 파이프라인 여부	매칭 체계가 여러 개일 가능성이 높다

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

운영 순서는 다섯 단계면 충분하다. 먼저 Source Map Debug API 상단의 전역 플래그를 본다. 두 번째로 deployed bundle에 Debug ID가 실제로 들어 있는지 확인한다. 세 번째로 legacy release upload 경로가 남아 있는 앱이나 잡을 따로 적는다. 네 번째로 frame lookup 결과를 본다. 마지막으로 하나의 앱은 하나의 매칭 체계로 단일화한다.

1. 전역 플래그로 Debug ID 계열과 release 계열 신호를 먼저 분리한다.
2. 배포 bundle에 Debug ID가 실제 주입됐는지 확인한다.
3. legacy upload가 남아 있는 앱과 잡을 분리 기록한다.
4. 그다음에야 source_file/source_map lookup 상태를 읽는다.
5. 앱 단위로 매칭 체계를 하나로 고정한다.

mixed project triage memo

1. project_has_some_artifact_bundle 확인
2. has_uploaded_some_artifact_with_a_debug_id 확인
3. deployed bundle Debug ID 주입 여부 확인
4. legacy release/dist 사용 앱 분리
5. frame lookup 상태 읽기

이 순서를 지키면 혼합 프로젝트 문제를 naming 문제로 오인하는 시간을 줄일 수 있다. 앱 하나가 release 기반이면 그 앱의 실패는 release/dist와 artifact 로그에서 먼저 줄여야 하고, Debug ID 기반 앱은 deployed bundle 주입 여부가 먼저다.

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

첫 자료는 Source Map Debug API 응답 필드다. 혼합 프로젝트에서는 frame 단위 lookup 결과와 release 단위 상태를 한 화면에서 같이 봐야 한다.

Source Map Debug API는 frame lookup 필드와 release 전역 상태를 한 응답에서 분리해 돌려준다.

즉 단순히 source map이 안 풀렸다는 결과만으로는 부족하다. 어떤 frame이 어느 체계로 매칭을 시도했는지부터 나눠야 다음 조치가 짧아진다.

두 번째 자료는 Debug ID 설명이다. 최신 흐름에서는 이벤트 stack frame과 minified file, source map을 release 이름이 아니라 Debug ID로 연결한다.

Sentry는 최신 JavaScript sourcemap 연결을 Debug ID 중심으로 설명한다.

여기서 중요한 점은 upload 성공 여부보다 deployed code에 Debug ID가 실제로 들어 있느냐다. 업로드만 최신으로 하고 런타임 bundle이 예전 상태면 혼합 증상이 남는다.

세 번째 자료는 legacy uploading methods다. 여기서는 Debug ID 대신 Releases로 매칭한다고 분명히 적는다.

Legacy 업로드 방식은 Debug ID가 아니라 release 이름과 artifact로 이벤트를 매칭한다.

이 페이지를 보면 release 체계와 Debug ID 체계는 보조 옵션 차이가 아니라 아예 매칭 축이 다르다는 점이 분명하다. 혼합 프로젝트는 둘을 동시에 성공시키려 하지 말고, 현재 어떤 경로가 실제 배포를 대표하는지 먼저 정해야 한다.

네 번째 자료는 기본 Source Maps 가이드다. 최신 가이드는 기본값 자체를 Debug ID 주입으로 놓고 있다.

최신 Source Maps 가이드는 기본 흐름을 Debug ID 주입과 업로드로 설명한다.

따라서 번들러 플러그인이나 CLI 설정이 새 버전인데도 프로젝트 일부가 release 기반으로만 남아 있다면, 그 부분이 혼합 증상의 첫 후보가 된다.

실무에서는 혼합 프로젝트 분기표가 가장 먼저 필요하다. frame 상태를 보기 전에 프로젝트 단위로 어떤 매칭 체계가 살아 있는지 분리해야 한다.

Debug ID 중심 경로, legacy release 경로, 혼합 증상을 빠르게 가르는 분기표다.

이미 상태 조합 분기 글을 읽었다면, 이번 표는 그 조합을 ‘혼합 프로젝트’라는 운영 원인까지 끌어올리는 용도다.

마지막 자료는 안전한 운영 로그 예시다. 혼합 프로젝트는 한 줄짜리 success/fail 로그로는 절대 다시 복기되지 않는다.

혼합 프로젝트 분리를 위해 남겨 둘 최소 로그 필드 예시다.

이렇게 남겨 두면 source map lookup not_found 글이나 original source 비어 있음 글으로도 자연스럽게 이어 붙일 수 있다.

5. 주의사항과 리스크

가장 큰 리스크는 새 플러그인을 도입했다는 사실만으로 전체 프로젝트가 Debug ID 체계로 전환됐다고 착각하는 것이다. 실제로는 특정 앱, 특정 배포 잡, self-hosted 제약 때문에 legacy 방식이 남아 있을 수 있다.

또 혼합 프로젝트는 한 번 설정을 맞췄다고 끝나지 않는다. 앱이 여러 개면 새 앱이 예전 release 템플릿을 복제해 들어오는 경우가 많아서, CI 단계에서 어떤 매칭 체계를 쓰는지 함께 기록해 두는 편이 안전하다.

• 주의: upload 성공은 실제 이벤트 sourcemap 성공과 같은 뜻이 아니다.
• 주의: Debug ID와 release artifact는 보조 옵션 차이가 아니라 매칭 키가 다르다.
• 주의: 앱 단위 단일화 없이 두 체계를 병행하면 복구 시간이 길어진다.

6. 결론

혼합 프로젝트에서 Source Map Debug API를 짧게 읽으려면 먼저 Debug ID 체계인지 legacy release 체계인지부터 나눠야 한다. 전역 플래그, deployed bundle 주입 여부, 남아 있는 legacy upload 경로를 분리한 뒤에 frame lookup 상태를 읽으면 naming과 original source 점검이 훨씬 짧아진다.

관련 흐름으로는 상태 조합 분기 글, source map lookup not_found 글, original source 비어 있음 글을 같이 보면 API 상태, naming 축, original source 축이 한 줄로 이어진다. 여기서 release_has_some_artifact=false와 Debug ID artifact 조합 글까지 이어 읽으면 mixed project에서 어느 업로드 경로부터 다시 봐야 하는지 더 선명해진다.

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/sourcemaps/troubleshooting_js/debug-ids/
3. https://docs.sentry.io/platforms/javascript/sourcemaps/troubleshooting_js/legacy-uploading-methods/
4. https://docs.sentry.io/platforms/javascript/sourcemaps/
5. https://docs.sentry.io/platforms/javascript/sourcemaps/uploading/cli/