트레이스(Trace)는 실행 프로세스에서 시스템 이벤트를 트레이스하는 구조화된 로깅 프레임워크입니다. TraceLog 모듈과 TraceAnalysis 모듈은 프레임워크를 구성하는 주요 모듈입니다. 언리얼 트레이스 서버는 백그라운드에서 단일 서버 인스턴스로 실행되며 여러 프로젝트나 브랜치 간에 공유할 수 있습니다. 퍼포먼스에 최소한의 영향만을 끼치는 최적화된 프로그램으로, 유저 인터페이스는 포함되어 있지 않습니다.
트레이스 서버는 Engine/Binaries/Win64 디렉터리 폴더에 있는 별도의 서버 프로세스인 UnrealTraceServer.exe로 자동 실행됩니다.
트레이스 서버에는 다음과 같은 두 컴포넌트가 있습니다.
트레이스 레코더(Trace Recorder)는 포트 1981에서 유입되는 트레이스 연결을 수신하고 라이브 트레이스 스트림을 기록합니다.
트레이스 스토어(Trace Store)는 기록된 트레이스를 폴더에 파일로 저장합니다. 이 폴더를 감시해 변경 사항이 있는지 확인하며, 사용 가능한 트레이스 목록을 언리얼 인사이트(Unreal Insights) UI에 노출합니다.
트레이스 폴더 경로의 예는 다음과 같습니다.
C:/Users/<user>/AppData/Local/UnrealEngine/Common/UnrealTrace/Store/001/언리얼 트레이스 서버
언리얼 에디터 빌드는 언리얼 트레이스 세션 브라우저에서 연결할 때 UnrealTraceServer.exe를 자동으로 실행합니다. 언리얼 트레이스 서버는 백그라운드에서 단일 서버 인스턴스로 실행되며 여러 프로젝트와 브랜치 간에 공유할 수 있습니다.
사용하고 있는 시스템의 작업 관리자(Task Manager)를 열고 프로세스(Processes) 탭으로 이동해서 언리얼 트레이스 서버를 종료할 수 있습니다.
언리얼 트레이스 서버는 백그라운드에서 단일 인스턴스로 실행되므로 새 버전을 실행하기 위해 종료할 필요가 없습니다. 동시에 여러 소스에서 데이터를 수신하고 기록할 수 있습니다.
현재 언리얼 트레이스 서버는 머신당 한 명의 사용자만 지원합니다. 여러 사용자가 동시에 로그인하면 트레이스는 첫 번째 사용자의 트레이스 디렉터리에 저장되므로 다른 사용자는 트레이스에 액세스할 수 없습니다.
트레이스 인사이트 위젯
트레이스 인사이트 위젯(Trace Insights Widget)을 사용하면 에디터 인터페이스를 통해 트레이스 데이터(Trace Data)를 제어하고 관리할 수 있습니다. 에디터에서 하단 툴바로 이동하여 트레이스(Trace) 버튼을 클릭하면 트레이스 인사이트 위젯(Trace Insights Widget)에 액세스할 수 있습니다.
다음 섹션에서는 트레이스 메뉴의 각 카테고리에 있는 세팅에 대해 설명합니다.
트레이스 데이터
트레이스 데이터(Trace Data) 카테고리에는 데이터 채널, 트레이스 북마크, 트레이스 스크린샷 등에 대한 세팅이 포함되어 있습니다.
Channels
트레이스(Trace)는 대량의 데이터를 기록할 수 있습니다. 트레이스 채널(Trace Channels)을 사용하여 기록할 데이터 타입을 선택할 수 있습니다.
채널(Channels)은 트레이스 시 데이터 속도를 제어합니다. 각 이벤트 타입은 하나 이상의 채널에 연결됩니다. 필수 채널이 활성화되지 않은 이벤트는 트레이스 스트림에 송신되지 않습니다.
채널 프리셋은 채널을 그룹화하여 시나리오 기반 엔트리 포인트를 제공합니다.
| Channel | Description |
|---|---|
Animation | Animation Insights Plugin. |
AssetLoadTime | Contains named CPU timers for |
AssetMetadata | Asset Names and Class Names as metadata for memory allocations. Requires Metadata channel. Used by Memalloc channel. |
Audio | Audio Insights Plugin. |
AudioMixer | AudioMixer Insights Plugin. |
Bookmark | Low-frequency markers to signify important transitions. Bookmarks provide a quick overview of features such as level loading or engine boot phases. |
Callstack | Callstack descriptions. Allows allocations to be associated with callstacks. |
ContextSwitch | Trace context switch events. On Windows, game or editor runtime should be run as administrator. |
Cook | Displays named CPU timers specific to cooking. This requires the CPU channel to be enabled. Cook will add the both the |
Counters | Generic counters. Traces float and integer values over time. Counters Trace API. It enables the CSV Profiler Trace. |
Cpu | Named CPU timers. Additional timers can be added by enabling the Stat Named Events channel from the Insights Widget or using the |
File | File I/O trace channel that contains Open, ReOpen, Read, Write, Close events. |
Frame | Game and Rendering frames. |
Gpu | Named GPU timers. Based on GpuProfiler data. |
LoadTime | Asset Loading Insights trace channel. Only works for runtime loading from the pak/iostore. |
Log | Logs Messages. |
MemAlloc | Memory allocations. Uses Module and Callstack. |
MemTag | Memory tag statistics. Traces snapshots of memory usage per tag at regular rate. Relies on LLM subsystem for tracing. Implies "-llm". Available after |
Messaging | UDP Messaging plugin. |
Metadata | Support for generic metadata scopes. |
Module | Module loading information. |
Net | Networking trace channel. |
Niagara | Niagara Plugin. |
Object | GameplayInsights/RewindDebugger plugin. |
Physics | |
RDG | RDG Insights Plugin. |
RHICommands | CPU or GPU named timers for RHI commands. |
RenderCommands | CPU or GPU named timers for commands executed on the rendering thread. |
SaveTime | Named CPU timers specific to package saving. |
Screenshot | Captures screenshots triggered with |
Slate | Slate Insights Plugin. |
StackSampling | Trace stack sampling events based on Event Tracing for Windows (ETW). |
Stats | Stats counters. Based on the Stats system. |
Task | Task Graph trace channel. |
VisualLogger | Visual Logger starts recording to file. |
다음 채널은 기본적으로 활성화되어 있습니다.
북마크
Cpu
Frame
Gpu
Log
리전
스크린샷
MemAlloc, MemTag 및 Module 채널은 회색인데, 이러한 채널은 명령 프롬프트에서 실행해야 하기 때문입니다. 명령 프롬프트에서 실행을 참조하세요.
[Trace.ChannelPresets] 카테고리에 추가된 환경설정 파일을 사용하여 자신만의 프리셋을 정의할 수 있습니다. 트레이스 개발자 가이드 문서를 참조하세요.
스크린샷 트레이스
트레이스 스크린샷(Trace Screenshot)은 해당 프레임 동안 프로젝트 뷰포트의 사진을 찍어 트레이스에 전송합니다. 기본적으로 트레이스 스크린샷은 채널 패널에서 활성화됩니다.
두 가지 방법으로 트레이스 스크린샷을 찍을 수 있습니다.
하단 툴바에서 트레이스(Trace) > 트레이스 스크린샷(Trace Screenshot)을 클릭합니다.
콘솔에
trace.screenshot명령을 입력합니다.
트레이스 스크린샷 사용 시 타이밍 인사이트 타임라인은 스크린샷의 날짜와 시간을 사용하여 현재 타임스탬프를 기반으로 생성된 이름이 포함된 수직선을 표시합니다.
Trace Bookmark
트레이스 북마크(Trace Bookmark)는 주어진 스트링 이름으로 TRACE_BOOKMARK() 이벤트를 송신합니다. 에디터에서 사용할 때는 스크린샷 이벤트와 북마크 이벤트 모두 날짜 및 시간 포맷을 사용하여 현재 타임스탬프를 기반으로 이름을 생성합니다.
트레이스 북마크는 두 가지 방법으로 설정할 수 있습니다.
하단 툴바에서 트레이스(Trace) > 북마크 트레이스(Trace Bookmark)를 클릭합니다.
콘솔에서
trace.bookmark명령을 입력합니다.
북마크와 스크린샷은 타이밍 인사이트(Timing Insights) 탭에 표시됩니다. 상단 툴바의 눈금자 트랙 아래에 도킹되어 있는 마커 트랙에서 확인할 수 있습니다. 북마크는 로그 뷰에서 사용할 수 있습니다.
통계 명명된 이벤트
통계 명명된 이벤트(Stat Named Events)는 추가적인 프로파일링 지표를 제공합니다. 통계 명명된 이벤트 체크박스를 클릭하여 활성화하거나 비활성화할 수 있습니다.
트레이스 대상
트레이스 대상(Trace Destination) 카테고리에서 트레이스 데이터를 저장할 위치를 선택할 수 있습니다.
| 옵션 | 설명 |
|---|---|
트레이스 스토어(Trace Store) | 서버의 관리되는 트레이스 스토어 디렉터리에 있는 파일에 트레이스 데이터를 기록합니다. |
파일(File) | 트레이스 데이터를 지정된 파일에 직접 기록합니다. |
트레이싱
트레이싱(Tracing) 카테고리에는 녹화 시작 및 중지, 트레이스 스냅샷 저장에 대한 세팅이 포함되어 있습니다.
녹화 시작 및 중지
| 옵션 | 설명 |
|---|---|
트레이스 시작(Start Trace) | 선택된 트레이스 대상을 트레이싱하기 시작합니다. 트레이스 인사이트 위젯에서 트레이스 시작 버튼을 클릭하여 트레이스를 시작할 수 있습니다. |
트레이스 중지(Stop Trace) | 트레이스가 시작되면 트레이스 시작 UI 아이콘이 빨간색으로 표시됩니다. 트레이스 중지 버튼을 클릭하여 트레이스 기록을 중지할 수 있습니다. |
트레이스 스냅샷 저장
트레이스 스냅샷(Trace Snapshot)을 저장하는 방법은 두 가지입니다.
하단 툴바에서 트레이스 스냅샷 저장(Save Trace Snapshot) 버튼을 클릭합니다.
하단 툴바에서 트레이스(Trace) > 트레이스 스냅샷 저장(Save Trace Snapshot)을 클릭합니다.
옵션
옵션(Options) 카테고리는 언리얼 인사이트 또는 대상 폴더를 자동으로 여는 등 자동화를 제어합니다.
| 옵션 | 설명 |
|---|---|
트레이스 시작 시 라이브 세션 열기(Open Live Session on Trace Start) | 트레이싱이 시작되면 언리얼 인사이트에서 라이브 세션이 자동으로 열립니다. 이 옵션은 트레이스 스토어에서 트레이스할 때만 적용됩니다. |
트레이스 후 인사이트 열기(Open Insights after Trace) | 트레이싱이 중지되거나 스냅샷이 저장되면 언리얼 인사이트에서 녹화된 세션이 자동으로 열립니다. |
트레이스 후 탐색기에 표시(Shown in Explorer after Trace) | 트레이싱이 중지되거나 스냅샷이 저장되면 녹화된 세션이 포함된 폴더가 자동으로 열립니다. |
위치
위치(Locations) 카테고리는 트레이스(파일 및 트레이스 서버에 저장)가 저장되는 위치를 제어합니다.
| 옵션 | 설명 |
|---|---|
트레이스 스토어 디렉터리 열기(Open Trace Store Directory) | 이 위치에는 트레이스 서버에 저장된 트레이스가 저장됩니다. |
프로파일링 디렉터리 열기(Open Profiling Directory) | 현재 프로젝트의 프로파일링 디렉터리를 엽니다. 파일에 대한 트레이스 저장 위치입니다. |
Insights
인사이트(Insights) 카테고리에는 언리얼 인사이트, 라이브 세션 및 녹화된 파일을 여는 세팅이 포함되어 있습니다.
| 옵션 | 설명 |
|---|---|
언리얼 인사이트(세션 브라우저)(Unreal Insights(Session Browser)) | 언리얼 인사이트 세션 브라우저를 실행합니다. |
라이브 세션 열기(Open Live Session) | 현재 라이브 세션을 엽니다. 스토어를 트레이스할 때만 이용할 수 있습니다. |
최신 트레이스(Recent Traces) | 트레이스 스토어에 기록되거나 파일로 저장된 최신 트레이스를 엽니다. |
트레이스 상태
콘솔 명령 Trace.Status를 사용하여 연결(Connection), 사용된 메모리(Memory Used), 중요 이벤트 캐시(Important Events cache), 전송된 데이터(Sent data), 활성화(Enabled) 및 사용 가능(Available) 트레이스 채널에 대한 정보를 확인할 수 있습니다.
명령 프롬프트에서 인사이트 실행
명령 프롬프트에서 언리얼 인사이트를 실행하는 절차는 다음과 같습니다.
Engine\Binaries\Win64폴더로 이동한 다음UnrealInsights.exe파일을 더블클릭합니다.운영 체제에서 명령 프롬프트(Command Prompt)를 실행하고 다음 프로젝트를 실행합니다. 다음 예시에서 설치 경로와 프로젝트 이름을 원하는 경로와 이름으로 교체하세요.
C++cd C:\[MyEngineInstallLocation]\ Samples\Games\Binaries\Win64\[YourProject].exe
테일 트레이싱
테일 트레이싱(Tail Tracing)은 버퍼 크기에 따라 지난 몇 초 동안의 이벤트를 추적합니다. 따라서 리드업을 표시할 수 있는 모든 머신에서 가능합니다.
버퍼 기본 크기는 4MB지만 명령줄에 -tracetailmb=X를 입력하여 이를 수정하거나 비활성화할 수 있습니다.
X를 0MB로 설정하면 비활성화되며, 다른 값을 입력하면 해당 값으로 버퍼 크기가 변경됩니다.
늦은 연결
이제는 중요 이벤트가 언리얼 엔진 클라이언트 측에 캐시된 다음, 연결되는 동안 연결이 늦어진 머신에 전송됩니다. 따라서 연결할 수 있게 되기 전에 일회성 이벤트(중요 이벤트)를 놓칠 일이 없습니다.
인사이트는 로컬 머신의 관여 없이 로컬 UI 인스턴스로부터 원격 트레이스 서버에 연결하도록 원격 실행 언리얼 엔진 인스턴스에 지시할 수 있습니다.
늦은 연결을 시작하려면 언리얼 인사이트(Unreal Insights) > 연결(Connect)로 이동하거나 에디터 콘솔에서 다음 명령 또는 실행인자 중 하나를 입력합니다.
"trace.send [ip]" / "trace.start [filename]"-trace.start [file] [channelSet] -tracehost=[ip]-tracefile = [filepath]
언리얼 인사이트에는 애플리케이션이 트레이스에 추가 정보를 어태치할 수 있는 파일 기반 캐싱 시스템이 있습니다. 이는 이전에 계산된 결과를 더 빨리 가져오거나 기호 등 다른 방식으로는 손실될 데이터를 저장하는 데 유용합니다. 캐시는 트레이스 파일 옆에 .ucache 파일로 저장됩니다.
트레이스 사용자 가이드
언리얼 인사이트에서 트레이스를 실행하는 워크플로는 다양합니다. 트레이스 사용자 가이드 문서를 참조하세요.
트레이스 개발자 가이드
언리얼 인사이트에서 직접 트레이스를 개발할 수도 있습니다. 트레이스 개발자 가이드 문서를 참조하세요.