스마트 버그 라이브 모니터링: Sentry/Crashlytics 연동으로 유저 크래시 로그 수집

유저 크래시 모니터링의 필요성과 라이브 버그 트래킹

게임 개발 과정에서 내부 QA나 스튜디오 내부 테스트를 아무리 철저히 거치더라도 실제 유저에게 서비스가 시작되면 예상치 못한 오류와 크래시가 빈번하게 발생합니다. 유저들의 하드웨어 사양, OS 버전, 그래픽 드라이버, 네트워크 상태 등이 제각각이기 때문에 개발 환경에서는 결코 재현되지 않던 예외 상황이 터지게 됩니다.

과거에는 유저가 캡처한 화면이나 텍스트 형태의 제보에 의존해 버그를 추적하곤 했습니다. 하지만 이러한 방식은 호출 스택(Callstack)이나 당시의 게임 상태 메모리를 확인하기 어려워 문제 원인을 파악하는 데 막대한 시간이 소요됩니다. 라이브 버그 모니터링 도구인 Sentry나 Firebase Crashlytics를 연동하면 크래시 발생 순간의 스택 트레이스뿐만 아니라 디바이스 정보, 유저 동선(Breadcrumb), 환경 변수까지 실시간으로 수집할 수 있습니다.

버그 수집 파이프라인은 클라이언트 게임 엔진에서 발생하는 예외를 감지하여 메타데이터와 함께 백엔드 모니터링 서버로 전달하는 구조로 작동합니다.

flowchart LR
    A[클라이언트 게임 실행] --> B{크래시 및 예외 감지}
    B -->|SDK 캡처| C[브레드크럼 및 컨텍스트 수집]
    C --> D[모니터링 백엔드로 전송]
    D --> E[콜스택 복원 및 이슈 그룹핑]

크래시율을 관리할 때는 단편적인 크래시 건수보다 일간 활성 유저 대비 발생 비율인 크래시율(Crash Rate)을 주요 지표로 활용합니다.

$$CrashRate = \frac{Total Crashes}{Daily Active Users} \times 100$$

---

Sentry vs Crashlytics: 게임 엔진별 플랫폼 선택 가이드

라이브 모니터링 솔루션을 도입할 때 가장 먼저 고민하게 되는 것은 도구의 선정입니다. 게임 산업에서 주로 활용되는 두 솔루션인 Sentry와 Firebase Crashlytics는 각각 뚜렷한 장단점을 가지고 있습니다.

1. Sentry

• 강점: C#, C++, Python 등 다양한 언어와 엔진(Unity, Unreal Engine)을 깊이 있게 지원합니다. 세밀한 Scope 설정, Rich Context 첨부, 브레드크럼 트래킹 기능이 뛰어납니다.
• 적합한 프로젝트: PC, 콘솔, 멀티플랫폼 게임 및 C++ 네이티브 덤프 분석이 중요한 프로젝트.

2. Firebase Crashlytics

• 강점: 모바일(Android, iOS) 환경에 최적화되어 있으며 Google Cloud 및 Firebase 생태계와 강력하게 연동됩니다. 기본 무상 제공량이 넉넉합니다.
• 적합한 프로젝트: 모바일 전용 타이틀 및 Google Analytics 연동이 주요한 프로젝트.

비교 항목	Sentry	Firebase Crashlytics
주요 타깃 플랫폼	PC, 콘솔, 모바일, 웹 전체	Android, iOS 중심 모바일
주요 엔진 SDK 지원	Unity SDK, Unreal SDK 공식 지원	Unity SDK 지원 (Unreal 제한적)
네이티브 덤프 수집	Minidump, Crashpad 지원	Android NDK, iOS dSYM 지원
이슈 그룹핑 및 알림	고도화된 규칙 기반 알림 및 이슈 관리	디바이스 및 OS 버전별 분포 위주

---

Sentry SDK 연동과 컨텍스트 기반 로그 수집 (Unity)

Unity 프로젝트에서 Sentry SDK를 활용해 예외 상황에 유용한 메타데이터를 추가하는 실전 코드 예시입니다. 단순 에러 텍스트만 전송하는 대신 유저의 현재 스테이지, 캐릭터 아이디, 메모리 상태 등의 컨텍스트를 동봉하면 디버깅 속도가 크게 향상됩니다.

using System;
using UnityEngine;
using Sentry;

public class CrashMonitoringManager : MonoBehaviour
{
    private void Awake()
    {
        // 1. Sentry SDK 초기화
        SentrySdk.Init(options =>
        {
            options.Dsn = "https://[email protected]/project-id";
            options.Debug = false;
            options.TracesSampleRate = 1.0;
            options.AutoSessionTracking = true;
        });

        // 2. 글로벌 전역 컨텍스트 설정
        SentrySdk.ConfigureScope(scope =>
        {
            scope.SetTag("game_version", Application.version);
            scope.SetTag("platform", Application.platform.ToString());
            scope.User = new User { Id = "User_94821" };
        });
    }

    // 유저의 주요 행동 경로를 브레드크럼으로 기록
    public void RecordBreadcrumb(string message, string category = "gameplay")
    {
        SentrySdk.AddBreadcrumb(
            message: message,
            category: category,
            level: BreadcrumbLevel.Info
        );
    }

    // 핸들링된 예외 발생 시 수동 캐치 및 전송
    public void LogHandledException(Exception ex, string currentStageName)
    {
        SentrySdk.WithScope(scope =>
        {
            scope.SetExtra("current_stage", currentStageName);
            scope.SetExtra("memory_usage", GC.GetTotalMemory(false).ToString());
            SentrySdk.CaptureException(ex);
        });
    }
}

위 예시처럼 AddBreadcrumb을 통해 장비 교체, 던전 입퇴장, 결제 시도 등의 주요 이벤트를 남겨두면 크래시 직전 유저가 수행했던 작업 순서를 시퀀스 형태로 복원할 수 있습니다.

---

네이티브 크래시와 심볼 파일(PDB/dSYM) 자동 업로드 파이프라인

Unity의 IL2CPP 빌드나 Unreal Engine의 C++ 빌드에서는 최적화를 위해 심볼 정보가 제거된 바이너리가 생성됩니다. 이 상태에서 네이티브 크래시(Access Violation, Segmentation Fault 등)가 발생하면 모니터링 대시보드에는 알아볼 수 없는 메모리 오프셋 주소(0x00007FFF8B2A1042)만 표시됩니다.

이를 함수 이름과 소스 코드 라인 번호로 복원하는 과정을 심볼리케이션(Symbolication)이라고 부릅니다. 이를 자동화하기 위해 CI/CD 파이프라인(GitHub Actions 또는 Jenkins) 구축 시 빌드 과정에서 생성되는 PDB(Windows), dSYM(iOS), so.debug(Android) 파일들을 모니터링 서버에 자동 업로드해야 합니다.

sentry-cli를 활용한 빌드 자동화 스크립트 예시는 다음과 같습니다.

# Sentry CLI 인증 및 조직/프로젝트 지정
export SENTRY_AUTH_TOKEN="your_auth_token"
export SENTRY_ORG="your_organization"
export SENTRY_PROJECT="your_game_project"

# 빌드 결과물 디렉토리의 심볼 파일 업로드 (PDB 및 dSYM)
sentry-cli debug-files upload --include-sources ./BuildOutput/Symbols

이러한 자동 업로드 프로세스가 구축되어야 라이브 디버깅 도중 어느 파일 몇 번째 줄에서 Null Pointer 참조가 일어났는지를 즉시 확인하고 빠르게 핫픽스 패치를 배포할 수 있습니다.

---

실무 적용 시 고려해야 할 핵심 요소

1. 개인정보 및 민감 데이터 필터링 계정 토큰, 결제 정보, 유저의 실명이나 이메일 등이 브레드크럼이나 Extra 데이터에 그대로 노출되지 않도록 데이터 마스킹(Sanitizer) 로직을 거쳐야 합니다.

2. 네트워크 호출 및 쿼터 관리 프레임마다 호출되는 Update() 함수 내에서 예외가 폭발적으로 일어날 경우 초당 수천 건의 로그가 전송되어 서비스 할당량이 급격히 소모될 수 있습니다. SDK의 SampleRate 조절 및 동일 예외 수신 제어(Deduplication)를 적절히 설정해야 합니다.

3. 심볼 파일 보안 PDB 및 dSYM 파일에는 소스 코드 구조와 함수명이 노출되어 있으므로 외부로 유출되지 않도록 모니터링 서버의 접근 권한 관리를 엄격히 유지합니다.