언리얼 엔진 5의 트레이스 | 언리얼 엔진 5.4 문서

트레이스(Trace) 는 실행 프로세스에서 시스템 이벤트를 트레이스하는 구조화된 로깅 프레임워크입니다. TraceLog 모듈과 TraceAnalysis 모듈은 프레임워크를 구성하는 주요 모듈입니다. 언리얼 트레이스 서버(Unreal Trace Server) 는 백그라운드에서 단일 서버 인스턴스로 실행되며 여러 프로젝트나 브랜치 간에 공유할 수 있습니다. 퍼포먼스에 최소한의 영향만을 끼치는 최적화된 프로그램으로, 유저 인터페이스는 포함되어 있지 않습니다.

트레이스 서버는 Engine/Binaries/Win64 디렉터리 폴더에 있는 별도의 서버 프로세스인 UnrealTraceServer.exe 로 자동 실행됩니다.

트레이스 서버에는 다음과 같은 두 컴포넌트가 있습니다.

트레이스 레코더(Trace Recorder) 는 수신되는 트레이스 연결을 위해 1981 포트를 리슨하고 라이브 트레이스 스트림을 기록합니다.
트레이스 스토어(Trace Store) 는 기록된 트레이스를 폴더에 파일로 저장합니다. 트레이스 스토어는 이 폴더에서 변경사항을 감시하고 사용할 수 있는 트레이스 목록을 언리얼 인사이트 UI에 노출합니다.

트레이스 폴더 경로의 예는 다음과 같습니다.

	C:/Users/<user>/AppData/Local/UnrealEngine/Common/UnrealTrace/Store/001/

언리얼 트레이스 서버

언리얼 에디터 빌드는 언리얼 트레이스 세션 브라우저에서 연결할 때 UnrealTraceServer.exe 를 자동으로 실행합니다. 언리얼 트레이스 서버는 백그라운드에서 단일 서버 인스턴스로 실행되며 여러 프로젝트와 브랜치 간에 공유할 수 있습니다.

사용하고 있는 시스템의 태스크 매니저를 이용하여 언리얼 트레이스 서버를 종료할 수 있습니다.

시스템 태스크 매니저는 실행 중인 서버 트레이스를 프로세스 탭에 표시합니다.

언리얼 트레이스 서버는 백그라운드에서 단일 인스턴스로 실행되므로 새 버전을 실행하기 위해 종료할 필요가 없습니다. 동시에 여러 소스에서 데이터를 수신하고 기록할 수 있습니다.

현재는 언리얼 트레이스 서버를 실행 중인 시스템당 한 명의 사용자만 지원합니다. 여러 사용자가 동시에 로그인하면 트레이스는 첫 번째 사용자의 트레이스 디렉터리에 저장되므로 다른 사용자는 트레이스에 액세스할 수 없습니다.

트레이스 인사이트 위젯

트레이스 인사이트 위젯(Trace Insights Widget) 을 사용하면 에디터 인터페이스를 통해 트레이스 데이터(Trace Data) 를 제어하고 관리할 수 있습니다. 에디터의 하단 툴바에서 트레이스 인사이트 위젯 에 액세스할 수 있습니다.

트레이스 데이터

트레이스(Trace) 는 대량의 데이터를 기록할 수 있습니다. 트레이스 채널(Trace Channels)을 사용하여 기록할 데이터 타입을 선택할 수 있습니다.

채널

채널(Channels) 은 트레이스 시 데이터 속도를 제어합니다. 각 이벤트 타입은 하나 이상의 채널에 연결됩니다. 필수 채널이 활성화되지 않은 이벤트는 트레이스 스트림에 송신되지 않습니다.

MemAlloc, MemTag 및 Module 채널은 회색인데, 이러한 채널은 명령 프롬프트에서 실행해야 하기 때문입니다. 명령 프롬프트에서 인사이트 실행을 참조하세요.

채널 프리셋은 채널을 그룹화하여 시나리오 기반 엔트리 포인트를 제공합니다.

채널	설명
Animation	Animation Insights 플러그인입니다.
AssetLoadTime	`UObject::Serialize` 에 대한 명명된 CPU 타이머를 포함합니다.
AssetMetadata	메모리 할당을 위한 메타데이터로서의 에셋 이름 및 클래스 이름입니다. Metadata 채널이 필요합니다. Memalloc 채널에서 사용합니다.
Audio	Audio Insights 플러그인입니다.
AudioMixer	AudioMixer Insights 플러그인입니다.
Bookmark	중요 트랜지션을 나타내는 저주파 마커입니다. Bookmark를 통해 레벨 로딩 또는 엔진 부팅 단계 같은 기능을 빠르게 살펴볼 수 있습니다.
Callstack	콜스택 설명입니다. 할당을 콜스택과 연결할 수 있습니다.
ContextSwitch	트레이스 컨텍스트 스위치 이벤트입니다. Windows에서 게임/에디터 런타임은 관리자 권한으로 실행되어야 합니다.
Cook	쿠킹에 관련된 명명된 CPU 타이머를 표시합니다. CPU 채널을 활성화해야 합니다. Cook은 `CookByTheBook` 및 `SaveCookedPackage` CPU 타이밍 이벤트를 모두 추가합니다.
Counters	일반 카운터입니다. 시간 경과에 따른 실수 및 정수 값을 트레이스합니다. 카운터 트레이스 API입니다. CSV 프로파일러 트레이스를 활성화합니다.
CPU	명명된 CPU 타이머입니다. 인사이트 위젯에서 통계 명명된 이벤트(Stat Named Events) 채널을 활성화하거나 `-statnamedevents` 명령줄 실행인자를 사용하여 타이머를 더 추가할 수 있습니다.
File	Open, ReOpen, Read, Write, Close 이벤트를 포함하고 있는 파일 I/O 트레이스 채널입니다.
Frame	게임 및 렌더링 프레임입니다.
GPU	명명된 GPU 타이머입니다. GpuProfiler 데이터를 기반으로 합니다.
LoadTime	에셋 로딩 인사이트(Asset Loading Insights) 트레이스 채널입니다. pak/iostore에서 런타임을 로드하는 경우에만 작동합니다. [#INCLUDE:testing-and-optimizing-your-content/unreal-insights/trace-in-unreal-engine#로드시간채널세팅]
Log	메시지를 로그합니다.
MemAlloc	메모리 할당입니다. Module 및 Callstack을 사용합니다.
MemTag	메모리 태그 통계입니다. 정규 속도로 태그당 메모리 사용량 스냅샷을 트레이스합니다. 트레이스를 위해 LLM 서브시스템에 의존합니다. '-llm'을 의미합니다. `Init()` 뒤에 사용할 수 있습니다.
Messaging	UDP Messaging 플러그인입니다.
Metadata	일반 메타데이터 범위를 지원합니다.
Module	모듈 로딩 정보입니다.
Net	네트워킹 트레이스 채널입니다. [#INCLUDE:testing-and-optimizing-your-content/unreal-insights/trace-in-unreal-engine#네트워킹명령]
Niagara	Niagara 플러그인입니다.
Object	GameplayInsights/RewindDebugger 플러그인입니다. `UObject` 클래스, 월드, 인스턴스 및 이벤트입니다.
Physics	카오스 비주얼 디버거입니다.
RDG	RDG Insights 플러그인입니다.
RHICommands	RHI 명령에 대한 명명된 CPU 및 GPU 타이머입니다.
RenderCommands	렌더링 스레드에서 실행되는 명령에 대한 명명된 CPU 및 GPU 타이머입니다.
SaveTime	패키지 저장에 관련된 명명된 CPU입니다.
Screenshot	`Trace.Screenshot` 콘솔 명령이나 `TRACE_SCREENSHOT()` API를 사용하여 트리거되는 스크린샷을 캡처합니다.
Slate	Slate Insights 플러그인입니다.
StackSampling	Windows용 이벤트 트레이스(Event Tracing for Windows, ETW)를 기반으로 한 트레이스 스택 샘플링 이벤트입니다.
Stats	통계 카운터입니다. 통계 시스템을 기반으로 합니다.
Task	태스크 그래프(Task Graph) 트레이스 채널입니다.
VisualLogger	비주얼 로거(Visual Logger)가 파일에 기록을 시작합니다.

[Trace.ChannelPresets] 카테고리에 추가된 환경설정 파일을 사용하여 자신만의 프리셋을 정의할 수 있습니다. 트레이스 개발자 가이드 문서를 참조하세요.

위의 이미지에서 Bookmark, CPU, Frame, GPU 및 Log 채널이 활성화되었습니다. 이러한 채널은 기본적으로 사용할 수 있습니다.

트레이스 스크린샷

트레이스 스크린샷(Trace Screenshot) 은 해당 프레임 동안 프로젝트 뷰포트의 사진을 찍어 트레이스에 전송합니다. 기본적으로 트레이스 스크린샷은 채널 패널에서 활성화됩니다. 다음과 같은 방식으로 트레이스 스크린샷을 찍을 수 있습니다.

인사이트/트레이스 위젯을 클릭하고 트레이스 스크린샷 (Ctrl+F9) 을 클릭합니다.
trace.screenshot 콘솔 명령을 사용합니다.

트레이스 스크린샷 사용 시 타이밍 인사이트 타임라인은 스크린샷의 날짜와 시간을 사용하여 현재 타임스탬프를 기반으로 생성된 이름이 포함된 수직선을 표시합니다.

트레이스 북마크

트레이스 북마크(Trace Bookmark) 는 주어진 스트링 이름으로 TRACE_BOOKMARK() 이벤트를 송신합니다. 에디터에서 사용할 때는 스크린샷 이벤트와 북마크 이벤트 모두 날짜 및 시간 포맷을 사용하여 현재 타임스탬프를 기반으로 이름을 생성합니다.

북마크와 스크린샷은 타이밍 인사이트 창에 표시되며 눈금자 트랙 아래의 상단 툴바에 도킹된 마커 트랙 에서 확인할 수 있습니다. 북마크는 로그 뷰에서 사용할 수 있습니다.

통계 명명된 이벤트

통계 명명된 이벤트(Stat Named Events) 는 체크박스를 클릭하여 활성화하거나 비활성화할 수 있는 추가 프로파일링 메트릭을 제공합니다.

트레이스 대상

트레이스 대상(Trace Destination) 을 설정하여 트레이스 데이터 저장 위치를 선택할 수 있습니다.

트레이스 스토어 파일

대상	설명
트레이스 스토어(Trace Store)	트레이스 스토어를 대상으로 설정합니다. 트레이스 스토어를 대상으로 사용하면 서버는 트레이스 데이터를 서버의 관리되는 트레이스 스토어 디렉터리에 있는 파일에 기록합니다.
파일(File)	파일을 대상으로 설정합니다. 파일을 대상으로 사용하면 지정된 파일에 트레이스 데이터가 바로 기록됩니다.

트레이싱

트레이스 시작/중지

트레이스 시작(Start Trace)	선택한 트레이스 대상에 대한 트레이스를 시작합니다. 트레이스 인사이트 위젯에서 트레이스 시작 버튼을 클릭하여 트레이스를 시작할 수 있습니다.
트레이스 중지(Stop Trace)	트레이스가 시작되면 트레이스 시작 UI 아이콘이 빨간색으로 표시됩니다. 트레이스 중지 버튼을 클릭하여 트레이스 기록을 중지할 수 있습니다.

트레이스 스냅샷 저장

다음 절차에 따라 인사이트 위젯의 트레이스 스냅샷(Trace Snapshot) 을 저장할 수 있습니다.

트레이스 스냅샷 저장(Save Trace Snapshot) 버튼을 클릭합니다.

트레이스 드롭다운 메뉴를 클릭한 다음, 트레이싱(Tracing) > 트레이스 스냅샷 저장 으로 이동합니다.

옵션

옵션	설명
트레이스 시작 시 라이브 세션 열기(Open Live Session on Trace Start)	true로 설정하면 트레이스를 시작할 때 언리얼 인사이트에서 해당 라이브 세션이 자동으로 열립니다. 이 옵션은 트레이스 스토어에서 트레이스할 때만 적용됩니다.
트레이스 후 인사이트 열기(Open Insights after Trace)	true로 설정하면 트레이스가 중지되거나 스냅샷이 저장될 때 언리얼 인사이트에서 해당 세션이 자동으로 열립니다.
트레이스 후 탐색기에 표시(Shown in Explorer after Trace)	true로 설정하면 트레이스가 중지되거나 스냅샷이 저장될 때 기록된 세션이 포함된 폴더가 자동으로 열립니다.

위치

옵션	설명
트레이스 스토어 디렉터리 열기(Open Trace Store Directory)	트레이스 서버에 대한 트레이스 저장 위치입니다.
프로파일링 디렉터리 열기(Open Profiling Directory)	현재 프로젝트의 프로파일링 디렉터리를 엽니다. 파일에 대한 트레이스 저장 위치입니다.

인사이트

옵션	설명
언리얼 인사이트(세션 브라우저)(Unreal Insights(Session Browser))	언리얼 인사이트 세션 브라우저를 실행합니다.
라이브 세션 열기(Open Live Session)	현재 라이브 세션을 엽니다. 스토어를 트레이스할 때만 이용할 수 있습니다.
최신 트레이스(Recent Traces)	해당 트레이스 스토어나 파일로 기록된 최신 트레이스를 엽니다.

트레이스 상태

다음 명령으로 연결(Connection), 사용된 메모리(Memory Used), 중요 이벤트 캐시(Important Events cache), 전송된 데이터(Sent data), 활성화(Enabled) 및 사용 가능(Available) 트레이스 채널에 대한 정보를 확인할 수 있습니다.

	Trace.Status

명령 프롬프트에서 인사이트 실행

Engine\Binaries\Win64 폴더로 이동한 다음 UnrealInsights.exe를 더블클릭합니다.

unreal-insights-executable-in-binaries-folder

운영 체제에서 명령 프롬프트 를 실행한 다음 해당 프로젝트를 실행합니다.
```
         cd C:\MyEngineInstallLocation\
		
         Samples\Games\Binaries\Win64\YourProject.exe
```
cd C:\MyEngineInstallLocation\ Samples\Games\Binaries\Win64\YourProject.exe

파일 디렉터리 경로는 로컬 설치 경로에 맞게 변경해야 합니다.

테일 트레이싱

테일 트레이싱(Tail Tracing) 은 버퍼 크기에 따라 지난 몇 초간의 이벤트를 트래킹합니다. 따라서 리드업을 표시할 수 있는 모든 머신에서 가능합니다.

버퍼 기본 크기는 4MB지만 명령줄에 다음 명령을 입력하여 이를 수정하거나 비활성화할 수 있습니다.

		`-tracetailmb=x`

X 를 0MB 로 설정하면 비활성화되며, 다른 값을 입력하면 해당 값으로 버퍼 크기가 변경됩니다.

늦은 연결

중요 이벤트 는 언리얼 엔진 클라이언트 측에 캐시되었다가 연결 중 늦게 연결되는 머신에 전송되므로, 연결할 수 있게 되기 전에 일회성 이벤트(중요 이벤트)를 놓칠 일이 없습니다.

인사이트는 로컬 머신에 관여할 필요 없이 로컬 UI 인스턴스로부터 원격 트레이스 서버에 연결하도록 원격에서 실행되는 언리얼 엔진 인스턴스에 지시할 수 있습니다.

늦은 연결은 언리얼 인사이트 > 연결 로 이동하거나 에디터 명령 콘솔(Editor cmd console) 에서 다음 명령을 입력하여 개시할 수 있습니다.

		`"trace.send [ip]" / "trace.start [filename]"

		-trace.start[file][channelSet] -tracehost=[ip]		

		-tracefile = [filepath]

언리얼 인사이트에는 애플리케이션이 트레이스에 추가 정보를 어태치할 수 있는 파일 기반 캐싱 시스템이 있습니다. 이를 사용하여 전에 계산한 결과를 더 빠르게 가져오거나 심볼처럼 손실될 수 있는 데이터를 저장할 수 있습니다. 캐시는 트레이스 파일 옆에 .ucache 파일로 저장됩니다.

트레이스 사용자 가이드

다양한 워크플로를 사용하여 언리얼 인사이트에서 트레이스를 실행할 수 있습니다. 트레이스 사용자 가이드 문서를 참조하세요.

트레이스 개발자 가이드

언리얼 인사이트에서 자신만의 트레이스를 개발할 수 있습니다. 트레이스 개발자 가이드 문서를 참조하세요.