Unity 인게임 버그 리포터 직접 만들기 — 어디까지 만들고 어디서 멈출까
트리거·수집·전송·식별 네 가지 결정과 난도 곡선, 흔히 밟는 함정까지 — 버그 리포터를 직접 만들 때 지도로 쓰는 글.
- unity
- bug-report
- qa
"버그 리포터를 만든다"는 하나의 작업처럼 들리지만 실제로는 서로 독립적인 네 가지 결정입니다. 어느 하나를 대충 정하면 나머지가 아무리 잘 만들어져도 리포트는 쓸모없어집니다. 이 글은 그 네 결정과, 그중 하나가 왜 난도가 자릿수째 다른지를 지도처럼 정리합니다.
결정 1. 트리거 — 어떻게 부르나
가장 흔한 선택은 개발 빌드의 핫키입니다. 문제는 릴리스 빌드에서 QA 나 플레이어가 이 핫키에 접근할 방법이 없다는 것입니다. 모바일이면 흔들기 제스처나 3손가락 탭, PC 타이틀이면 인게임 메뉴의 버튼이 현실적인 대안입니다. 크래시 직전 상태를 잡고 싶다면 별도 트리거 없이 예외 발생 자체를 트리거로 삼는 경로도 필요합니다 — 사용자가 버튼을 누를 겨를도 없이 앱이 죽는 경우가 실제로 더 흔합니다.
핫키를 쓴다면 게임 자체의 입력 바인딩과 충돌하지 않는지부터 확인해야 합니다. 인벤토리를 여는 키와 겹치면 QA 는 매번 두 번 누르는 법을 익혀야 합니다.
결정 2. 수집 — 무엇을 담나, 그리고 난도가 갈리는 지점
스크린샷과 로그까지는 하루면 붙습니다. 로그 콜백 후킹과 최근 N줄을 링 버퍼에 담는 코드는 최소 구현 가이드에 그대로 있습니다. 게임 상태 — 씬 이름, 진행도, 최근 입력 — 를 뭘 담을지는 별도 글에서 다룹니다.
영상은 자릿수가 다릅니다. 화면 픽셀을 GPU 에서 읽어오는 것부터 공짜가 아니고(AsyncGPUReadback 을 써도 파이프라인 스톨을 피하려면 별도 설계가 필요합니다), 실시간으로 인코딩하려면 플랫폼마다 다른 하드웨어 인코더에 접근해야 합니다. 여기에 최근 N초를 항상 들고 있는 링 버퍼 메모리 관리까지 얹히면, 스크린샷+로그 리포터를 만드는 것과 이 기능까지 포함한 리포터를 만드는 것은 사실상 다른 프로젝트입니다. 로그와 상태만으로도 재현율은 눈에 띄게 오릅니다 — 이 항목은 "언젠가"로 미뤄도 됩니다.
결정 3. 전송 — 어디로 보내나
이메일, 웹훅, 이슈 트래커 직접 연동, 자체 백엔드 중 선택지가 갈립니다. 각각 인증 난도와 유지비가 다르고, 이 선택이 QA 팀의 실제 워크플로에 가장 직접 영향을 줍니다. 네 방식의 용량·인증·검색성·유지비 비교는 별도 글에서 표로 정리했습니다.
결정 4. 식별 — 누가 언제 어느 빌드에서
리포트가 쌓이기 시작하면 "이 버그가 어느 빌드에서 시작됐나"를 답하지 못하는 순간이 옵니다. Application.version, 빌드 번호, 세션 ID, 디바이스 식별자를 기본으로 심어야 하고, 이 중 디바이스 식별자는 플랫폼 정책과 개인정보 규정을 먼저 확인해야 하는 항목입니다. 익명 세션 ID 로 시작해서 필요할 때만 사용자 동의를 받고 확장해야 안전합니다.
흔한 함정 세 가지
| 함정 | 증상 | 대응 |
|---|---|---|
| 리포트 UI가 자기 자신을 찍음 | 스크린샷에 버그 리포트 버튼·오버레이가 그대로 찍힘 | 캡처 직전 리포터 UI 를 숨기고 한 프레임 뒤 캡처 |
| 전송 실패 시 리포트 유실 | 오프라인·서버 다운 상황에서 조용히 사라짐 | 로컬 큐에 적재 후 재시도, 성공 시에만 삭제 |
| 리포터 자체가 크래시를 유발 | 버그를 잡으려던 코드가 새 버그를 만듦 | 수집·전송 코드는 전부 방어적으로 감싸고 실패해도 게임은 죽지 않게 |
세 번째가 가장 치명적입니다. 버그를 리포트하려다가 리포터가 죽으면 정작 필요한 순간에 아무것도 남지 않습니다.
어디서 멈출까
모든 걸 다 만들 필요는 없습니다. 판단 기준은 대체로 셋입니다.
- 팀 규모와 QA 인원: QA 가 1~2명이면 웹훅으로 즉시 알림 받는 것만으로 충분한 경우가 많습니다. 인원이 늘수록 검색·이력 관리가 필요해집니다.
- 플랫폼 수: 단일 플랫폼이면 캡처 SDK 옵션이 열려 있습니다. 멀티 플랫폼이면 자체 구현이 오히려 통합 비용을 줄이기도 합니다.
- 재현 실패 빈도: "재현 안 됨"으로 닫히는 티켓이 체감상 많다면 영상까지 투자할 가치가 있습니다. 그렇지 않다면 로그와 상태만으로 충분할 수 있습니다.
정리
트리거·수집·전송·식별은 각각 따로 결정해도 되는 독립 변수입니다. 스크린샷과 로그, 게임 상태까지는 하루 이틀 안에 끝나는 작업이고, 영상은 그 자체로 별도 프로젝트입니다. 전송 경로 비교는 3편, 상태 스냅샷 설계는 4편에서 이어집니다. Unity 공식 리포팅 패키지로 이 네 결정 중 얼마를 대신할 수 있는지는 2편에서 실사했습니다. 녹화 방법 자체의 비교는 별도 글로 다룰 예정입니다.
저희 Rekon은 이 네 결정을 이미 내려서 하나로 묶어 둔 선택지입니다 — 핫키 하나로 영상·로그·게임 상태가 같은 시간축으로 캡처됩니다. 직접 만들기로 했다면 위 순서대로, 영상은 가장 마지막에 붙이시길 권합니다.