트레이스(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를 더블클릭합니다.
-
운영 체제에서 명령 프롬프트 를 실행한 다음 해당 프로젝트를 실행합니다.
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 파일로 저장됩니다.
트레이스 사용자 가이드
다양한 워크플로를 사용하여 언리얼 인사이트에서 트레이스를 실행할 수 있습니다. 트레이스 사용자 가이드 문서를 참조하세요.
트레이스 개발자 가이드
언리얼 인사이트에서 자신만의 트레이스를 개발할 수 있습니다. 트레이스 개발자 가이드 문서를 참조하세요.

