[Sentry][프론트엔드] source-map-debug API에서 debug_meta는 맞는데 release artifact가 비어 보일 때 어느 필드부터 다시 확인하나

IT 리서치 노트

[Sentry][프론트엔드] source-map-debug API에서 debug_meta는 맞는데 release artifact가 비어 보일 때 어느 필드부터 다시 확인하나

Sentry에서 이벤트 payload의 debug_meta는 분명히 잡히는데 Source Maps 화면이나 source-map-debug API에서 release artifact가 비어 보이면, 업로드가 실패한 것인지 release 이름 연동이 빠진 것인지, 아니면 그냥 debug ID 경로를 release artifact 화면과 혼동한 것인지 헷갈리기 쉽다. 2026년 7월 5일 기준 Sentry 공식 문서를 다시 보면 debug ID 기반 artifact bundle 경로와 release 기반 artifact 연동은 서로 다른 층위고, source-map-debug API는 이 둘의 존재 여부를 अलग-अलग 플래그로 보여 준다. 이 글은 debug_meta는 맞는데 release artifact가 비어 보일 때 어느 필드부터 다시 읽어야 하는지 정리한 것이다.

목차

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

1. 개요

결론부터 말하면 debug_meta가 있다고 해서 곧바로 release artifact까지 정상이라고 보면 안 된다. 먼저 has_debug_ids와 debug_id_process로 debug ID 경로가 살아 있는지 확인하고, 그다음 project_has_some_artifact_bundle와 release_has_some_artifact를 분리해서 읽어야 한다. release artifact만 비어 있을 때는 release 이름 연동과 생성 타이밍, 업로드 옵션을 먼저 보는 편이 맞다.

이미 mixed path scheme source-map-debug 글이 frame path를 좁혔다면, 이번 글은 artifact 존재 플래그를 좁히는 후속편이다. 또 CDN 경로와 hash drift 글과 dist 운영 기준 글은 파일명과 naming 축이고, 오늘은 release 연동 축이다.

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

실무에서 흔한 막힘은 세 가지다. 첫째, debug_meta가 있으니 업로드는 완벽하다고 가정한다. 둘째, release artifact가 비어 보이면 debug ID 업로드도 실패했다고 바로 단정한다. 셋째, debug ID 기반 artifact bundle과 release 기반 artifact 연동을 같은 화면 기준으로 해석한다.

Sentry troubleshooting 문서는 이벤트 payload에 debug_meta가 있는지 먼저 확인하라고 한다. source-map-debug API 문서는 여기에 더해 project_has_some_artifact_bundle, release_has_some_artifact, has_uploaded_some_artifact_with_a_debug_id를 अलग-अलग 필드로 내려준다. Sentry CLI 문서는 artifact bundle에 release를 추가로 연동할 수 있지만, 이 옵션은 매칭을 더 엄격하게 만든다고 경고한다.

여기에 legacy uploading methods 문서를 같이 보면 예전 release 기반 매칭과 최신 debug ID 기반 매칭이 서로 다른 경로라는 점이 더 분명해진다. 그래서 debug_meta가 맞는데 release artifact가 비어 보이는 상황은 업로드 자체보다는 release 이름 연동, release 생성 타이밍, 또는 UI 해석 순서 문제일 가능성이 크다.

• 증상: debug_meta는 있는데 release artifact가 비어 보인다.
• 실패: artifact bundle 업로드와 release 연동을 같은 성공 조건으로 본다.
• 막힘: debug ID 기반 경로와 release 기반 경로를 섞어 읽는다.
• 누락: source-map-debug API의 상위 플래그를 먼저 보지 않는다.

상황	먼저 볼 것	판단 기준
debug_meta 자체가 없다	SDK 주입과 debug ID 업로드	업로드 이전 단계 문제다
artifact bundle은 있는데 release artifact가 없다	release 이름 연동	event와 upload 옵션의 release가 같은지 본다
release artifact도 있는데 frame이 안 풀린다	matching_source_file_names	파일명과 prefix 매칭 문제로 이동한다

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

점검 순서는 네 단계가 가장 짧다. 먼저 source-map-debug API에서 has_debug_ids와 frame의 debug_id_process를 조회해 debug ID 주입과 업로드 결과를 확인한다. 두 번째로 project_has_some_artifact_bundle와 has_uploaded_some_artifact_with_a_debug_id를 확인해 프로젝트 수준 업로드가 살아 있는지 본다. 세 번째로 release 값과 release_has_some_artifact를 비교해 event의 release와 업로드 시 release 옵션이 맞는지 확인한다. 마지막으로 상위 플래그가 모두 맞으면 matching_source_file_names와 source_file_lookup_result로 내려가 frame 매칭 문제를 조회한다.

1. has_debug_ids와 debug_id_process를 먼저 본다.
2. 프로젝트 수준 artifact bundle 업로드 여부를 본다.
3. release 값과 release_has_some_artifact를 비교한다.
4. 그다음 frame별 lookup 결과로 내려간다.

실무에서는 이 네 단계를 화면과 명령 기준으로도 다시 적어 두는 편이 좋다. Sentry Project Settings의 Source Maps 화면을 열어 artifact bundle이 보이는지 확인하고, source-map-debug API 응답에서 release 문자열을 조회하고, CI의 sentry-cli sourcemaps upload 명령에 --release가 붙었는지 비교하고, 마지막에 matching_source_file_names와 파일 이름을 줄 단위로 확인하면 된다. 이렇게 확인, 조회, 비교, 실행 순서를 고정해 두면 release artifact gap을 다시 재현하기 쉽다.

핵심은 release artifact 화면을 전체 성공 여부의 첫 판단 기준으로 쓰지 않는 것이다. debug ID 기반 매칭이 정상인데 release 연동만 빠졌을 수 있고, 반대로 release는 있어도 frame path가 틀릴 수 있다. 이 해석은 Sentry troubleshooting, source-map-debug API, CLI upload, debug IDs, legacy uploading 문서를 이어 읽은 운영 기준이다.

점검 메모 예시

has_debug_ids=true
project_has_some_artifact_bundle=true
release=frontend@2026.07.05
release_has_some_artifact=false
upload_command=with_debug_ids_without_release
next_step=compare_sdk_release_and_upload_release

이렇게 남겨 두면 '업로드가 아예 안 됐다'와 'release만 연결이 안 됐다'를 분명히 분리할 수 있다.

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

첫 자료는 Sentry troubleshooting 문서의 핵심 지점이다. source map이 안 풀릴 때 이벤트 payload에 debug_meta가 있는지 먼저 보라고 적고 있다.

Sentry troubleshooting 문서는 이벤트 payload에 debug_meta가 있는지부터 확인하라고 안내한다.

이 단계가 통과됐다는 것은 적어도 SDK 쪽 debug ID 주입과 이벤트 첨부가 일부는 살아 있다는 뜻이다. 하지만 여기서 바로 release artifact 문제를 건너뛰면 나중에 업로드 스텝과 매칭 스텝을 섞게 된다.

두 번째 자료는 source-map-debug API response schema다. 여기에는 project_has_some_artifact_bundle, release_has_some_artifact, has_uploaded_some_artifact_with_a_debug_id가 함께 나온다.

Sentry source-map-debug API는 artifact bundle 존재와 release artifact 존재를 서로 다른 필드로 구분해 보여 준다.

즉 debug_meta가 맞는 상황에서도 release artifact가 비어 보이는 이유를 한 줄로 줄일 수 있다. 프로젝트 수준 업로드는 살아 있지만 release 연동만 비어 있을 수 있고, 그 반대도 가능하다.

세 번째 자료는 Sentry CLI의 release association 설명이다. 문서는 artifact bundle에 release를 붙일 수 있지만, 이 단계는 debug ID 업로드와 별도이며 더 엄격한 매칭을 만들 수 있다고 경고한다.

Sentry CLI 문서는 artifact bundle과 release를 추가로 연동할 수 있고, 이 설정은 매칭을 더 엄격하게 만든다고 설명한다.

그래서 debug_meta는 맞는데 release artifact가 비어 보이는 상황은 release 값을 이벤트와 업로드 양쪽에서 동일하게 맞췄는지 먼저 봐야 한다. debug ID path와 release path를 같은 층위로 보면 해결 순서가 엇갈린다.

네 번째 자료는 legacy uploading methods 문서다. 여기서는 debug IDs 대신 release 기반으로 artifact를 매칭하던 예전 경로를 따로 설명한다.

Sentry legacy uploading methods 문서는 debug ID가 아니라 release 기반 매칭이 별도 경로임을 설명한다.

이 비교를 알아야 debug_meta가 살아 있는 최신 경로와 release artifact가 비어 보이는 예전 매칭 습관을 구분할 수 있다. 디버그 ID 경로를 쓰는 팀이 release artifact 화면만 보고 무조건 실패로 오판하는 경우가 줄어든다.

실무에서는 source-map-debug API 응답을 한 번 JSON으로 남겨 두는 편이 좋다. debug_meta는 맞지만 release artifact가 비어 보일 때는 어떤 플래그가 true이고 어떤 플래그가 false인지가 바로 갈린다.

debug_meta는 맞지만 release artifact가 비어 보이는 source-map-debug API 응답 예시다.

이 예시처럼 artifact bundle은 있는데 release artifact만 비어 있다면, 업로드 자체보다 release 이름 연동이나 UI 해석 순서를 먼저 의심하는 편이 맞다. 이미 mixed path scheme source-map-debug 글을 읽었다면, 이번 글은 frame path가 아니라 release artifact 존재 플래그를 좁히는 분기다.

마지막 자료는 release artifact gap을 읽는 순서표다. debug ID와 release 연동, frame lookup을 다른 줄로 두면 어떤 단계가 실제로 비어 있는지 설명이 훨씬 짧아진다.

debug_meta는 맞지만 release artifact가 비어 보일 때 읽는 순서를 정리한 표다.

이 표를 기준으로 보면 artifact bundle 업로드 성공과 release artifact 존재를 같은 성공 조건으로 착각하지 않게 된다. 이전 CDN 경로와 hash drift 글과 dist 운영 기준 글도 함께 연결된다.

5. 주의사항과 리스크

첫 번째 리스크는 debug ID 경로를 쓰면서 release artifact 화면만 보고 실패로 오판하는 것이다. 두 번째 리스크는 release 옵션을 붙였는데 SDK의 release 값과 업로드 release 값이 다른 것을 놓치는 것이다. 세 번째 리스크는 상위 플래그를 안 보고 바로 frame lookup으로 내려가 시간을 쓰는 것이다.

운영 문서에는 최소한 has_debug_ids, project_has_some_artifact_bundle, release_has_some_artifact, release 값을 한 번에 남기는 편이 좋다. 그래야 다음 배포에서도 artifact gap을 같은 위치에서 재현할 수 있다.

• artifact bundle 업로드와 release 연동은 अलग-अलग 단계다.
• release 연동을 쓸 때는 SDK와 upload의 release 값을 같게 둔다.
• 상위 플래그가 맞은 뒤에만 frame lookup으로 내려간다.

6. 결론

Sentry에서 debug_meta는 맞는데 release artifact가 비어 보일 때는 업로드 전체를 다시 의심하기보다 source-map-debug API의 상위 플래그를 먼저 나눠 읽어야 한다. debug ID 경로, artifact bundle 존재, release 연동, frame lookup을 순서대로 분리해 두면 release artifact gap을 훨씬 짧게 설명할 수 있다.

만약 상위 플래그는 맞는데 frame lookup만 not_found라면, 이어서 파일명과 prefix 점검 순서 글처럼 abs_path, 업로드 파일명, url-prefix를 먼저 대조하는 편이 맞다.

• debug ID 경로와 release 경로를 분리해서 본다.
• release_has_some_artifact는 release 연동 문제를 가리킨다.
• 상위 플래그가 맞아야 frame별 lookup으로 내려간다.

7. 참고 링크

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