[Sentry][프론트엔드] release_has_some_artifact=false인데 Debug ID artifact는 보일 때 어느 업로드 경로부터 다시 보나

카테고리 없음 2026. 7. 16. 09:12

IT 리서치 노트

[Sentry][프론트엔드] release_has_some_artifact=false인데 Debug ID artifact는 보일 때 어느 업로드 경로부터 다시 보나

Sentry Source Map Debug API를 볼 때 `release_has_some_artifact=false`인데 `has_uploaded_some_artifact_with_a_debug_id=true`가 같이 나오면, 많은 팀이 release artifact가 비었으니 release 업로드부터 다시 붙인다. 하지만 2026년 7월 16일 기준 Sentry 공식 문서를 다시 보면 JavaScript sourcemap의 기본 권장 경로는 Debug ID 기반이고, legacy uploading methods는 release artifact 매칭과 별도 경로다. 이 글은 두 flag가 엇갈릴 때 어느 업로드 경로부터 다시 봐야 시간을 덜 쓰는지 정리한 것이다.

1. 개요

결론부터 말하면 release_has_some_artifact=false와 has_uploaded_some_artifact_with_a_debug_id=true 조합이 보일 때는 release 업로드부터 고치기보다 현재 이벤트가 Debug ID 파이프라인을 타는지부터 확인하는 편이 빠르다. Debug ID artifact가 이미 있다는 것은 현재 권장 경로 일부가 살아 있다는 뜻이고, release artifact flag는 legacy 경로의 잔존 여부를 보여 줄 수 있다.

즉 이번 문제는 Sentry가 sourcemap을 못 읽는 한 가지 원인이라기보다, 서로 다른 업로드 경로가 프로젝트 안에 같이 남아 있는지의 문제다. 먼저 이벤트를 어느 파이프라인이 설명하는지 분리해야 한다.

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

실무에서 가장 헷갈리는 상황은 세 가지다. 첫째, Source Map Debug API에서 Debug ID 관련 flag는 true인데 release artifact flag는 false다. 둘째, CI에는 아직 sentry-cli releases files upload-sourcemaps 흔적이 남아 있는데 빌드 단계에서는 Debug ID injection도 같이 돌고 있다. 셋째, 팀원마다 release 이름과 bundle 업로드 여부를 서로 다른 로그로 확인해 한 이벤트를 두 파이프라인으로 해석한다.

이때 release artifact만 채우면 문제가 풀릴 것처럼 보일 수 있다. 하지만 Sentry JavaScript sourcemaps 문서는 기본 경로가 Debug ID injection과 artifact bundle upload라고 설명하고, legacy uploading methods 문서는 Releases 기반 매칭이 별도 흐름이라고 선을 긋는다. 즉 Debug ID artifact가 이미 있다면 현재 이벤트는 release artifact보다 Debug ID 경로에서 먼저 설명될 수 있다.

문제는 혼재다. 같은 프로젝트에서 어떤 배포는 Debug ID만, 어떤 배포는 release artifacts만, 어떤 배포는 둘 다 남길 수 있다. 그래서 release_has_some_artifact=false라는 한 줄만 보고 release 업로드를 복구하면, 실제로는 Debug ID pipeline이 맞는데 오래된 CI 경로만 더 복잡하게 만들 수 있다.

증상: release flag는 false인데 Debug ID artifact는 true다.
실패: 현재 이벤트가 어떤 업로드 체계를 탔는지 분리하지 않는다.
막힘: CI에 legacy release upload와 Debug ID upload가 같이 남아 있다.
누락: deploy 로그에 활성 sourcemap 경로를 별도 기록하지 않는다.

신호	먼저 볼 것	판단 기준
debug_id=true	Debug ID injection, artifact bundle upload	현재 기본 경로가 살아 있는지 본다
release=false	legacy release upload 잔존 여부	구식 경로를 아직 기대하고 있는지 본다
팀 문서가 둘을 혼용함	CI 메모와 배포 로그	한 deploy에 한 경로만 남기도록 정리한다

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

가장 빠른 점검 순서는 다섯 단계다. 먼저 Debug API flag 조합을 적는다. 두 번째로 현재 이벤트가 Debug ID injection을 탄 build인지 확인한다. 세 번째로 artifact bundle upload가 성공했는지 CLI 로그를 본다. 네 번째로 release artifact를 아직 요구하는 CI 경로나 문서가 남아 있는지 확인한다. 마지막으로 한 deploy에 한 sourcemap 업로드 체계만 남기도록 메모를 정리한다.

Source Map Debug API flag 조합을 먼저 기록한다.
Debug ID injection과 artifact bundle upload 성공 여부를 본다.
현재 이벤트가 어느 배포에서 왔는지 release/log와 대조한다.
legacy release upload 스크립트가 남아 있는지 확인한다.
한 deploy에 한 업로드 경로만 유지하도록 CI를 정리한다.

재점검 메모

1. debug API에서 release/debug_id flag 조합 기록
2. sentry-cli sourcemaps inject 실행 여부 확인
3. artifact bundle upload 성공 로그 확인
4. legacy release upload job 잔존 여부 확인
5. 현재 배포는 debug_id pipeline만 유지

이 순서가 중요한 이유는 방향을 거꾸로 잡지 않기 위해서다. Debug ID artifact가 이미 보이는데도 release upload 복구부터 시작하면, 실제 문제는 bundle upload 이후 frame path나 source file 상태였는데 release naming만 건드리고 끝날 수 있다. 업로드 체계 분리가 먼저다.

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

첫 자료는 Sentry Source Map Debug API 응답 스키마다. 여기에는 `release_has_some_artifact`와 `has_uploaded_some_artifact_with_a_debug_id`가 따로 나온다.

Source Map Debug API는 release artifact 경로와 Debug ID artifact 경로를 별도 flag로 보여 준다.

즉 release artifact가 false인데 Debug ID 쪽은 true라면, 같은 프로젝트 안에 서로 다른 업로드 체계가 섞여 있다는 신호로 읽는 편이 맞다. 이 상태를 한 줄로 뭉개면 디버그 흐름이 계속 흔들린다.

두 번째 자료는 JavaScript sourcemaps 문서다. Sentry는 기본 경로로 Debug IDs를 빌드 산출물에 주입해 매칭한다고 설명한다.

현재 기본 sourcemap 매칭 경로는 Debug ID 기반이며, release artifact 방식과는 별도다.

즉 최신 파이프라인은 Debug ID artifact bundle 쪽으로 정렬돼 있고, release artifact flag는 과거 업로드 방식과 연결해 읽어야 한다. 둘을 같은 경로처럼 다루면 triage 순서가 어긋난다.

세 번째 자료는 legacy uploading methods 문서다. 이 문서는 Debug IDs 대신 Releases를 써서 이벤트 스택 프레임과 artifacts를 맞추는 방식을 설명한다.

Legacy uploading 문서는 release 기반 artifact 매칭이 Debug ID 경로와 별도임을 분명히 보여 준다.

따라서 `release_has_some_artifact=false`가 보일 때는 release-based upload 경로가 비었는지 먼저 볼 수 있다. 다만 Debug ID artifact가 이미 있다면, 곧바로 release를 고치기보다 어떤 이벤트가 어느 파이프라인으로 들어왔는지 분리하는 편이 빠르다.

네 번째 자료는 CLI 업로드 문서다. Debug IDs를 주입한 뒤 artifact bundle을 업로드하는 현재 경로가 여기에 나온다.

Sentry CLI 문서는 Debug ID 주입 후 artifact bundle 업로드를 현재 권장 흐름으로 설명한다.

즉 Debug ID artifact가 보인다면 적어도 이 파이프라인 일부는 살아 있다는 뜻이다. 문제는 release artifact를 기대하는 팀 로그나 CI가 여전히 남아 있는지, 그리고 어떤 deploy가 어떤 경로를 썼는지다.

실무에서는 두 업로드 경로를 같은 표로 분리해야 한다. 그래야 Debug ID bundle은 살아 있는데 release artifact flag가 비어 있는 상태를 빠르게 해석할 수 있다.

release artifact 경로와 Debug ID artifact 경로를 나눠 보는 triage 표다.

이미 Debug ID와 legacy release 업로드 혼재 글이 큰 분류를 다뤘다면, 이번 표는 그중에서도 `release_has_some_artifact=false` 조합을 먼저 읽는 버전이다.

마지막 자료는 CI 메모 예시다. 동일 프로젝트에서 Debug ID와 release 업로드 스크립트를 동시에 남겨 두면 나중에 어떤 deploy가 어떤 경로를 탔는지 추적하기 어려워진다.

CI에서 현재 활성화된 sourcemap 업로드 경로를 분리해 기록하는 예시다.

이 메모를 남겨 두면 status combination 분기 글처럼 여러 flag 조합을 읽을 때도 어떤 deploy가 어느 업로드 방식을 썼는지 빨리 좁힐 수 있다.

5. 주의사항과 리스크

첫 번째 리스크는 Debug ID와 release artifact를 같은 경로라고 가정하는 것이다. 두 번째 리스크는 현재 배포는 Debug ID bundle을 쓰는데, 오래된 release upload job을 되살려 설정을 더 복잡하게 만드는 것이다. 세 번째 리스크는 deploy 로그에 활성 sourcemap pipeline을 남기지 않아 나중에 이벤트와 업로드 체계를 다시 연결하지 못하는 것이다.

운영 전에는 최소한 CI에 debug_id pipeline인지 legacy release pipeline인지 명시하는 로그를 남기는 편이 좋다. 그래야 Source Map Debug API flag를 봤을 때 어떤 경로를 기준으로 triage해야 하는지 바로 정해진다.

Debug ID와 release artifact는 같은 매칭 경로가 아니다.
현재 이벤트가 어떤 업로드 체계를 탔는지 먼저 분리한다.
한 deploy에는 한 sourcemap 업로드 경로만 남긴다.

6. 결론

release_has_some_artifact=false인데 Debug ID artifact가 보일 때는 release 업로드를 무조건 복구하기보다 현재 이벤트가 Debug ID 파이프라인으로 설명되는지부터 확인하는 편이 빠르다. Source Map Debug API flag를 업로드 체계 분리 신호로 읽으면, mixed project에서도 어디부터 다시 봐야 하는지 훨씬 선명해진다.

관련 흐름으로는 status combination 분기 글, Debug ID와 legacy release 혼재 글, scraping status와 uploaded artifact 분기 글을 같이 보면 upload path, frame 상태, artifact 상태가 한 줄로 이어진다.

이 흐름의 다음 단계로는 Source Map Debug API에서 source_file_lookup_result가 not_found이고 scraping status도 실패할 때 frame URL prefix와 artifact bundle을 어떻게 다시 볼지를 이어 읽는 편이 좋다. 오늘 글은 업로드 경로 분리까지, 새 글은 frame URL prefix와 public scraping 분리까지 범위를 한 단계 더 좁힌다.

ABOUT ME

FullStack Lab FullStack Lab