Sentry SDK와 AI 모니터링으로 인게임 예외 로그를 즉시 분석하는 방법
Unity 게임에 Sentry SDK를 연동해 예외·크래시·사용자 흐름을 구조화하고 AI 분석으로 재현 가설과 대응 우선순위를 빠르게 정하는 실전 라이브 운영 절차를 소개합니다.
핵심 요약
인게임 예외를 빨리 해결하려면 try/catch 로그만 쌓지 말고 Sentry SDK가 수집한 스택 트레이스, 릴리스, 사용자 영향도, 브레드크럼을 하나의 이슈로 묶어야 한다. AI는 원인을 확정하는 도구가 아니라 이 컨텍스트를 바탕으로 재현 가설, 유사 이슈, 대응 우선순위를 제안하는 보조 분석기로 사용한다.
Unity C# 기준으로 예외를 구조화해 전송하고 AI 분석이 신뢰할 수 있는 입력을 만드는 최소 운영 흐름을 정리한다.
인게임 예외 로그는 왜 원인을 바로 알려주지 못하는가?
게임 클라이언트의 예외는 발생 시점과 보고 시점이 다르다. 네트워크 재시도, 씬 전환, 비동기 작업, 기기 성능 차이 때문에 같은 NullReferenceException도 서로 다른 문제일 수 있다. 메시지와 스택 트레이스만으로 이슈를 묶으면 잘못된 원인에 시간을 쓰기 쉽다.
| 수집 항목 | 확인할 질문 | AI 분석에 주는 근거 |
|---|---|---|
| 예외 타입·스택 트레이스 | 어느 메서드에서 실패했는가? | 코드 경로와 공통 실패 지점 |
release·environment | 특정 빌드나 배포군에서만 발생하는가? | 회귀 버전 후보 |
| 태그 | 플랫폼·기기·지역 조건이 있는가? | 영향 범위 분류 |
| 브레드크럼 | 실패 직전 사용자가 무엇을 했는가? | 재현 절차 가설 |
| 사용자·세션 수 | 실제 영향도가 큰가? | 대응 우선순위 |
특히 릴리스 식별자가 없으면 패치 후에도 이전 빌드의 이벤트가 섞인다. Sentry 프로젝트 설정과 CI/CD에서 빌드 버전 또는 커밋 SHA를 일관되게 release로 지정하는 일이 먼저다.
Sentry SDK로 Unity 예외 로그를 어떻게 구조화할까?
1. SDK 초기화와 릴리스 정보를 고정한다
Unity 프로젝트 시작 시점에 DSN, 환경, 릴리스 값을 설정한다. 아래 예시는 SDK API의 개념을 보여 주며 실제 초기화 위치는 게임의 부트스트랩 구조에 맞춘다.
using Sentry;
using UnityEngine;
public sealed class SentryBootstrap : MonoBehaviour
{
private void Awake()
{
SentryUnity.Init(options =>
{
options.Dsn = "https://[email protected]/0";
options.Environment = Debug.isDebugBuild ? "development" : "production";
options.Release = Application.version;
options.TracesSampleRate = 0.1;
});
}
}TracesSampleRate = 0.1은 트랜잭션의 10%만 수집한다는 뜻이다. 오류 이벤트는 성능 트레이스와 성격이 다르므로 비용과 진단 가능성을 함께 보고 샘플링 정책을 정해야 한다.
2. 예외 발생 지점에 게임 문맥을 붙인다
PII와 비밀값을 보내지 않는다는 전제에서 원인 규명에 필요한 최소 문맥만 태그와 추가 데이터로 기록한다. 태그는 필터링과 집계에 쓰고 가변적인 세부 값은 SetExtra에 둔다.
using System;
using Sentry;
using UnityEngine;
public static class MatchErrorReporter
{
public static void Capture(Exception exception, string correlationId, int stageId)
{
SentrySdk.ConfigureScope(scope =>
{
scope.SetTag("platform", Application.platform.ToString());
scope.SetTag("game_mode", "ranked");
scope.SetExtra("stage_id", stageId);
scope.SetExtra("correlation_id", correlationId);
});
SentrySdk.CaptureException(exception);
}
}correlation_id에는 개인을 식별할 수 없는 서버 발급 ID를 사용한다. 계정 ID, 인증 토큰, 채팅 원문, 결제 정보처럼 민감한 값을 태그나 추가 데이터에 넣지 않는다.
3. 브레드크럼으로 예외 직전 흐름을 남긴다
예외를 잡는 코드에만 정보를 추가하면 늦다. 로비 진입, 매치메이킹 시작, 씬 로드, 결제 검증 호출처럼 상태가 바뀌는 지점에서 브레드크럼을 남긴다.
SentrySdk.AddBreadcrumb(
message: "Matchmaking started",
category: "game.matchmaking",
level: SentryLevel.Info);브레드크럼에는 인증 토큰이나 사용자 입력 원문을 넣지 않는다. 클라이언트 로그는 외부 전송 데이터라는 기준으로 설계한다.
AI 모니터링은 예외 분석에 어떻게 연결할까?
AI 분석의 입력은 Sentry 이벤트 전체가 아니라 검토 가능한 요약 데이터여야 한다. 이슈별로 예외 타입, 최상위 스택 프레임, 최초·최종 발생 시각, 영향 사용자 수, 릴리스, 태그 분포, 최근 배포 목록을 전달한다.
flowchart LR
A[Unity Sentry SDK] --> B[Sentry Issue 그룹화]
B --> C[이벤트 컨텍스트 정규화]
C --> D[AI 분석]
D --> E[재현 가설과 우선순위]
E --> F[개발자 검토 및 수정]
F --> G[릴리스 배포 후 회귀 확인]AI 결과는 다음 세 가지로 제한하면 운영자가 검증하기 쉽다.
- 요약: 어떤 릴리스와 조건에서 어떤 예외가 증가했는지 한 문장으로 정리한다.
- 가설: 스택 트레이스와 브레드크럼으로 가능한 원인을 최대 3개 제시한다.
- 다음 확인: 재현에 필요한 기기, 씬, API 응답, 비교 대상 릴리스를 명시한다.
예를 들어 InventoryService.ApplyReward()의 NullReferenceException이 1.4.2 배포 직후 Android에서 증가했다면 AI는 보상 응답의 선택 필드 누락을 가설로 제시할 수 있다. 하지만 실제 API 페이로드와 코드 변경분을 확인하기 전에는 결론으로 취급하면 안 된다.
인게임 크래시와 예외의 대응 우선순위는 어떻게 정할까?
단순 이벤트 수는 재시도 루프 때문에 부풀려질 수 있다. 우선순위는 영향을 받은 사용자 수와 세션 비율을 함께 본다.
| 기준 | 높은 우선순위 예시 | 낮은 우선순위 예시 |
|---|---|---|
| 사용자 영향 | 신규 사용자 5% 이상 진행 불가 | 내부 테스트 기기 1대에서만 발생 |
| 기능 영향 | 결제, 로그인, 세이브 실패 | 선택 화면의 시각 효과 실패 |
| 회귀성 | 최신 프로덕션 릴리스부터 급증 | 여러 버전에서 장기간 소량 발생 |
| 재현성 | 동일 브레드크럼 후 반복 발생 | 문맥 없는 단발 이벤트 |
Sentry 알림은 새 이슈마다 모두 보내기보다 production 환경에서 영향 사용자 수 또는 발생 속도가 임계값을 넘는 조건으로 만든다. AI 요약도 같은 기준을 만족한 이슈에만 적용하면 검토량이 줄어든다.
즉시 분석 운영 절차: 3단계
1. 수집 품질을 먼저 점검한다
프로덕션 이벤트에 release, environment, 플랫폼 태그가 들어오는지 확인한다. Android나 iOS처럼 심볼 업로드가 필요한 플랫폼이라면 사람이 읽을 수 있는 스택 트레이스가 보이는지도 확인한다.
2. 이슈 단위로 AI 입력을 제한한다
이슈의 최근 24시간 통계, 영향 사용자 수, 대표 이벤트 1~3개, 브레드크럼, 관련 배포 정보를 정규화한다. 사용자 원문 데이터와 토큰, 이메일은 제외한다.
3. 사람이 판정하고 패치 효과를 측정한다
AI가 제시한 가설을 이슈 링크, 코드 변경분, QA 재현 결과로 검증한다. 패치 뒤에는 동일 이슈의 이벤트 수뿐 아니라 영향 사용자 수와 새 릴리스의 발생 비율이 감소했는지 확인한다.
자주 묻는 질문 (FAQ)
Sentry에 모든 로그를 보내도 될까?
아니다. 오류 분석에 필요한 이벤트와 브레드크럼만 보내고 민감 정보와 고빈도 디버그 로그는 제외해야 한다. 비용과 데이터 보호 정책도 함께 점검한다.
AI가 제시한 원인을 바로 버그 티켓으로 등록해도 될까?
가설로 등록할 수는 있지만 확정 원인으로 처리하면 안 된다. 스택 트레이스, 코드 변경, 재현 결과 중 최소 하나로 근거를 확인한 뒤 우선순위를 정한다.
크래시가 아니라 처리된 예외도 수집해야 할까?
진행 불가, 보상 누락, 저장 실패처럼 사용자 경험을 해치는 처리된 예외는 수집 대상이다. 정상적인 재시도까지 오류로 보내지 않도록 발생 지점을 구분한다.
마무리
Sentry SDK의 핵심 가치는 예외를 전송하는 데 있지 않고 릴리스, 플랫폼, 사용자 흐름을 함께 남겨 이슈를 비교 가능하게 만드는 데 있다. AI 모니터링은 이 구조화된 데이터를 요약하고 조사 순서를 제안하는 데 쓰며 최종 판단은 개발자와 QA의 재현·검증으로 닫는다.
