게임에 크래시가 발생하면 언리얼 엔진은 크래시 리포트 클라이언트(Crash Report Client) 에 전송할 수 있는 크래시 리포트를 생성합니다. 크래시 리포트 클라이언트는 사용자에게 선택적 코멘트를 제공하고 에픽게임즈에 크래시 리포트 제출 메시지를 표시하는 애플리케이션입니다. 게임에 패키지로 만든 크래시 리포트 클라이언트를 커스터마이징하여 게임 디버깅에 도움이 되는 크래시 리포트 데이터를 자체 서버에 전송할 수 있습니다.
이 가이드에서는 다음과 같은 내용을 다룹니다.
- 크래시 리포트 및 그 콘텐츠에 관한 개요
- 로컬 컴퓨터에 크래시 리포트가 있는 위치 정보
- 크래시 리포팅의 환경설정 변수 레퍼런스 및 프로젝트 세팅
- 패키지로 만든 자체 애플리케이션에 맞게 크래시 리포터 클라이언트(Crash Reporter Client)를 수정하고 환경설정하는 방법
- 원격 서버에서 크래시 리포트를 수신하는 데 사용할 수 있는 크래시 리포트 서비스에 대한 권장 사항
크래시 리포트
크래시 리포트에는 다음과 같은 내용이 포함되어 있습니다.
- 크래시 GUID 라고 하는 고유한 랜덤 크래시 식별자
- 타입(크래시(Crash), 어서트(Assert), 인슈어(Ensure) 등) 또는 크래시 스레드와 다른 모든 스레드의 콜스택 같은 오류에 대한 정보
- 컴퓨터에 대한 시스템 정보 및 빌드 환경설정 같은 애플리케이션 컨텍스트 정보
- 크래시 순간의 로그 출력. 디바이스 런타임 로그일 수도, 프로젝트 에디터 로그일 수도 있습니다.
- 키/값 쌍을 사용하여 게임에서 제공된 추가 컨텍스트
- 사용자가 크래시 리포트 클라이언트를 통해 제공하는 모든 추가 코멘트
다음은 크래시 리포트 클라이언트에 표시되는 크래시 리포트의 예시입니다.

로컬 크래시 리포트 위치
에디터의 크래시 리포트는 로컬 컴퓨터 프로젝트 폴더의 Saved/Crashes
폴더에 저장됩니다.
또는 사용자의 로컬 컴퓨터 C:\Users[Windows 사용자 이름]\AppData\Local[프로젝트 이름]\Saved\Crashes
폴더에 크래시 리포트가 있을 수도 있습니다.
언리얼 엔진의 일반적인 크래시 원인
다음은 가장 흔히 보이는 크래시 리포트의 원인입니다. 이들 각각은 콜스택 위에 발생한 크래시 유형에 대한 세부 정보를 제공하는 메시지와 함께 크래시 리포터 클라이언트를 시작합니다.
크래시 소스 | 설명 | 예시 이미지(클릭하면 확대됨) |
---|---|---|
크래시(Crash) | 프로그램이 처리할 수 없는 일이 발생하여 프로그램이 종료됩니다. 크래시 발생 이유는 다음과 같습니다.
|
|
어서트(Assert) | 개발자가 특정 조건에 따라 의도적으로 프로그램 크래시를 발생시키기 위해 코드에 넣은 어서트 문으로 인해 발생합니다. 나중에 런타임 중에 문제가 발생할 것으로 예상되는 항목을 확인하여 문제를 조기에 포착하는 데 유용합니다. 그 예시는 다음과 같습니다.
언리얼 엔진의 어서트에 대한 자세한 내용은 어서트 문서 페이지를 참조하세요. |
|
인슈어(Ensure) | 특정 조건을 확인하지만, false를 해결하면 크래시가 발생하지 않습니다. 대신, 출력 로그에 메시지를 생성하고 무인 모드의 크래시 리포터에 리포트를 전송합니다. 모니터링해야 하지만 꼭 크래시 실행이 필요한 것은 아닌 항목에 유용합니다. 그 예시는 다음과 같습니다.
언리얼 엔진의 인슈어에 대한 자세한 내용은 어서트 문서 페이지를 참조하세요. |
인슈어는 개발 툴로만 사용되며 일반적으로 테스트 및 출시 빌드 환경설정에서는 비활성화됩니다. 최종 소비자에게 게임을 퍼블리싱할 때는 항상 출시 환경설정을 사용하는 것이 좋습니다. 크래시 리포터 클라이언트를 수정하지 않은 경우 개발 또는 디버깅 빌드를 배포하면 사용자로부터 에픽게임즈에 무인 크래시 리포트가 전송될 수 있습니다.
크래시 리포트에 커스텀 컨텍스트 추가하기
크래시 리포트에 추가되는 기본 정보 외에도 게임 프로젝트에서 게임 데이터 라고 하는 자체 커스텀 컨텍스트를 추가할 수도 있습니다. 이는 게임 모드에 대한 정보가 될 수도 있고 월드에서 플레이어의 위치나 버그 조사에 반드시 필요한 기타 게임 스테이트가 될 수도 있습니다. 이러한 데이터는 키/값의 쌍 및 FPlatformCrashContext::SetGameData
함수를 사용하여 추가됩니다.
GenericPlatformCrashContext.h
/** 크래시 컨텍스트에 임의의 게임 데이터를 업데이트(아직 없는 경우 추가)합니다(빈 스트링이 전달되면 키가 제거됨). */
CORE_API static void SetGameData(const FString& Key, const FString& Value);
오류 발생 전에 커스텀 컨텍스트가 설정된다는 점에 유의하세요. 크래시 리포트가 수집되면 현재 게임 데이터 값의 스테이트가 캡처되고 리포트에 기록됩니다.
예를 들어, 게임에서 새 게임 모드를 호출할 때마다 수행되는 경우는 다음과 같습니다.
MyGameMode.cpp
void OnEnterMyGameMode()
{
FPlatformCrashContext::SetGameData(TEXT("GameMode"), TEXT("MyGameModeName"));
}
void OnExitMyGameMode()
{
FPlatformCrashContext::SetGameData(TEXT("GameMode"), FString());
}
해당 게임 모드 중에 크래시가 발생하면 다음 XML 데이터가 포함됩니다.
CrashContext.runtime-xml
<GameData>
<GameMode>MyGameModeName</GameMode>
</GameData>
크래시 리포터 인프라
UE의 크래시 리포트 인프라는 다음과 같은 컴포넌트로 구성됩니다.
-
에디터 또는 게임 빌드와 함께 배포되는 사용자 컴퓨터의 크래시 리포트 클라이언트. 크래시 리포트 클라이언트는 엔드포인트에 크래시 덤프 정보를 전송합니다.
-
크래시 리포트를 관리하고 필터를 적용하고 저장하는 컴포넌트 및 애플리케이션이 있는 서버.
아래 섹션에서는 각 컴포넌트와 이러한 컴포넌트를 조직에 맞춰 설정하는 방법에 대해 자세하게 설명합니다.
크래시 리포터 클라이언트
크래시 리포터 클라이언트는 에디터 빌드와 함께 사용되는 별도의 프로그램으로, 사용자 컴퓨터의 런타임 빌드와 함께 선택적으로 패키지가 됩니다. 에디터나 패키지로 만든 애플리케이션에 크래시가 발생하면, 엔진은 크래시 리포트를 생성한 다음 사용할 수 있는 경우 크래시 리포터 클라이언트를 실행합니다. 크래시 리포터가 무인 모드가 아니면 크래시 데이터가 있는 창을 표시하고 사용자에게 리포트 전송 여부를 선택하라는 메시지를 표시합니다.
크래시 리포터 클라이언트를 게임과 함께 패키지로 만들기
기본적으로 크래시 리포터 클라이언트는 패키지로 만든 게임에 포함되지 않습니다. 패키지로 만든 빌드에 추가하려면 다음 방법을 따릅니다.
-
언리얼 에디터에서 프로젝트 세팅(Project Setting) 을 열고 프로젝트(Project) > 패키징(Packaging) 으로 이동합니다.
-
고급(Advanced) 드롭다운을 펼칩니다.
-
크래시 리포터 포함(Include Crash Reporter) 세팅을 활성화합니다.
또는 프로젝트의 Config/DefaultGame.ini
파일에 IncludeCrashReporter=True
를 추가해도 됩니다.
DefaultGame.ini
[/Script/UnrealEd.ProjectPackagingSettings]
IncludeCrashReporter=True
자동 크래시 리포트 환경설정하기
아래의 환경설정 변수가 크래시 리포터가 서버에 자동으로 크래시 리포트를 전송할지 여부를 결정합니다. [CrashReportClient]
카테고리 아래의 Engine.ini
파일에서 이러한 변수를 환경설정할 수 있습니다.
환경설정 변수 | 설명 |
---|---|
bAgreeToCrashUpload |
크래시 리포트 클라이언트의 자동 크래시 이벤트 전송 여부를 제어합니다. 이 변수는 Linux 빌드에서만 사용됩니다. 기본적으로 Windows 및 Mac 빌드에서는 false 지만 Linux 빌드에서는 true 입니다. |
bSendUnattendedBugReports |
크래시 이벤트 무인 전송 여부를 제어합니다. 활성화하면 크래시 리포트 클라이언트는 사용자에게 리포트를 표시하지 않고 자동으로 크래시 이벤트를 서버에 전송합니다. 이 변수 함수는 모든 플랫폼에서 작동하며 기본적으로 true 입니다. |
DefaultEngine.ini
[CrashReportClient]
bAgreeToCrashUpload=false
bSendUnattendedBugReports=false
UE 5.3.2 이전 버전에서는 버그 때문에 크래시 리포터와 함께 패키지로 만든 런타임 빌드에서 bSendUnattendedCrashReports
가 제대로 작동하지 않았습니다. false로 설정해도 크래시 리포터가 인슈어에 대한 리포트를 에픽게임즈에 자동으로 전송합니다. 이 문제는 UE 5.4에서 수정되었습니다.
크래시 리포터 클라이언트 환경설정하기
크래시 리포터 클라이언트를 커스터마이징하여 원하는 서버에 크래시 이벤트를 전송할 수 있습니다. 크래시 리포터를 커스터마이징하려면 다음 방법을 따릅니다.
-
언리얼 엔진 설치 디렉터리를 엽니다.
-
Engine/Programs/CrashReportClient/Config로 이동합니다.
-
DefaultEngine.ini
파일을 엽니다.
이 환경설정 파일에는 크래시 리포터 환경설정에 사용되는 모든 변수가 포함되어 있습니다.
DefaultEngine.ini (Programs/CrashReportClient)
[CrashReportClient]
DataRouterUrl="https://datarouter.ol.epicgames.com/datarouter/api/v1/public/data"
bAllowToBeContacted=true
bSendLogFile=true
CanSendWhenUIFailedToInitialize=true
UIInitRetryCount=10
UIInitRetryInterval=2.0
크래시 리포트가 전송될 URL 변경하기
본인의 조직에 크래시 리포트를 전송하려면 DataRouterURL
변수를 자체 크래시 리포트 서버의 URL로 변경합니다. 이 엔드포인트 설정 방법에 관한 자세한 내용은 아래의 크래시 리포트 섹션을 참조하세요.
환경설정 변수 레퍼런스
크래시 리포터 클라이언트의 환경설정 변수는 다음과 같습니다.
환경설정 변수 | 디폴트 값 | 설명 |
---|---|---|
DataRouterUrl | https://datarouter.ol.epicgames.com/datarouter/api/v1/public/data | 크래시 리포트 서버를 가리키는 URL입니다. |
bAllowToBeContacted | true | 대화창 '연락 허용(Allow to be contacted)' 옵션의 디폴트 스테이트입니다. |
bSendLogFile | true | 크래시 리포트 클라이언트가 크래시와 관련된 로그 파일을 전송할지 여부를 제어합니다. |
CanSendWhenUIFailedToInitialize | true | 크래시 리포트 클라이언트가 UI를 초기화하지 못한 경우, 자동으로 크래시 리포트를 전송할지 여부를 제어합니다. |
UIInitRetryCount | 10 | 크래시 리포트 자동 전송 전에 크래시 리포트 클라이언트 열기를 다시 시도하는 횟수입니다. |
UIInitRetryInterval | 2 | 재시도 간격(초)입니다. |
에디터 빌드에는 항상 크래시 리포트 클라이언트가 포함되지만, 패키지로 만든 빌드에 포함하는 것은 선택 사항입니다.
크래시 리포트 서버
크래시 리포터를 최대한 활용하려면 원격 사용자의 크래시 리포트를 수신하고 이를 기호화할 수 있는 서버를 설정해야 합니다. UE의 소스 코드나 바이너리에는 이러한 컴포넌트가 포함되어 있지 않습니다. 하지만, 크래시 리포트 클라이언트의 소스 코드를 고유한 커스텀 솔루션을 생성하는 시작점으로 사용할 수 있습니다. 또한, 디플로이할 수 있는 몇 가지 타사 크래시 리포트 서비스도 있습니다.
UE 커뮤니티에서는 일반적으로 다음과 같은 크래시 리포트 서비스를 사용합니다. 서비스마다 UE의 크래시 리포트에 통합하는 방법을 다룬 문서가 있습니다.