Trace是一种结构化的日志记录框架,用于追踪正在运行流程中的仪表测量事件。 模块TraceLog和TraceAnalysis是构成框架的主要模块。 虚幻Trace服务器作为单一服务器实例会在后台运行,可以由项目的多个实例或分支共享。 这个经优化的程序对性能产生的影响微乎其微,并且不包含用户界面。
Trace服务器由位于Engine/Binaries/Win64目录下的单独服务器进程UnrealTraceServer.exe自动启动。
Trace服务器由两部分组成
Trace Recorder在1981端口监听传入的跟踪连接并记录实时跟踪流。
Trace Store将记录的跟踪信息作为文件存储在一个文件夹中。 它会监测这个文件夹的变化并在Unreal Insights 的用户交互界面显示可用的追踪器列表。
以下是一个追踪文件夹的路径的例子:
C:/Users/<user>/AppData/Local/UnrealEngine/Common/UnrealTrace/Store/001/虚幻Trace服务器(Unreal Trace Server)
当你从虚幻Trace会话浏览器建立连接时,虚幻编辑器构建版本会自动启动UnrealTraceServer.exe。 虚幻Trace服务器作为单一服务器实例会在后台运行,可以由项目的多个实例或分支共享。
你可以通过访问系统的任务管理器并导航到进程选项卡来关闭虚幻Trace服务器。
虚幻Trace服务器在后台作为单独实例运行,无须终止便可启动新版本。 它可以同时从多个来源接收与记录数据。
目前,我们仅支持每台机器一个用户使用虚幻Trace服务器。 如果多个用户同时登录,则追踪将存储在第一个用户的追踪目录中,因此无法供其他用户访问。
Trace Insights控件
Trace Insights控件提供了一种使用编辑器界面来控制和管理Trace数据的方法。 你可以通过导航到底部工具栏并点击Trace按钮从编辑器访问Trace Insights控件。
以下部分描述Trace菜单每个类别中的设置。
Trace数据
Trace数据类别包含有关数据通道、Trace书签、Trace截图等的设置。
通道
Trace能够记录大量的数据。 你可以使用Trace通道来选择记录哪种类型的数据。
通道控制追踪时的数据率。 每个事件类型都与一个或多个通道相关联。 如果没有启用必要的通道,那么该事件将不会被发射到追踪流中。
通道预设将通道组合在一起,提供基于场景的切入点。
| 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
帧
GPU
日志
区域
截屏
MemAlloc、MemTag和Module通道是灰色的,因为它们必须通过命令提示符运行。 请参阅使用命令提示符
你可以使用已添加到Trace.ChannelPresets类别中的配置文件来定义你自己的预设。 有关文档,请参阅Trace开发者指南。
Trace截图
Trace截图在该帧中拍摄你的项目视口的图片,并将其发送给追踪器。 默认情况下,Trace截图在通道面板上是启用的。
你可以用以下两种方式截取Trace截图:
在底部工具栏,点击Trace > Trace截图(Trace Screenshot)。
在控制台中,输入命令
trace.screenshot。
当使用Trace截图时,Timing Insights时间线显示一条垂直线,其中包含当前时间戳,名称为你截图的日期和时间。
Trace书签
Trace书签使用给定的字符串名称发送一个TRACE_BOOKMARK()事件。 当在编辑器中使用时,截图和书签事件都将根据当前的时间戳,根据日期和时间的格式生成名称。
你可以用以下两种方式设置Trace书签:
在底部工具栏,点击Trace > Trace书签(Trace Bookmark)。
在控制台中,输入命令
trace.bookmark。
书签和截图在Timing Insights选项卡中是可见的。 你可以在顶部工具栏中,标尺追踪(ruler track)下方的标记追踪(markers track)中找到它们。 书签在日志视图中是可用的。
统计数据名称事件
统计数据名称事件提供额外的分析指标。 你可以通过点击统计数据名称事件(Stat Named Events)复选框来启用或禁用它们。
Trace目标
在Trace目标类别中,你可以选择存储trace数据的位置。
| 选项 | 说明 |
|---|---|
Trace存储 | 将trace数据写入其管理的trace存储目录中的文件。 |
文件(File) | 将trace数据直接写入指定文件。 |
追踪
追踪类别包含用于开始和停止录制以及保存Trace快照的设置。
开始和停止录制
| 选项 | 说明 |
|---|---|
开始追踪 | 启动一个追踪器,追踪选定的追踪目标。 你可以通过点击开始追踪(Start Trace)按钮使用Trace Insights控件启动追踪器。 |
停止追踪 | 当一个Trace开始时,开始Trace UI图标将显示为红色。 你可以通过点击停止追踪(Stop Trace)按钮停止追踪器进行记录。 |
保存Trace快照
有两种方式保存Trace快照:
在底部工具栏,点击保存Trace快照(Save Trace Snapshot)按钮。
在底部工具栏,点击Trace > 保存Trace快照(Save Trace Snapshot)。
选项
选项类别控制自动化功能,例如自动打开Unreal Insights或目标文件夹。
| 选项 | 说明 |
|---|---|
在追踪开始时打开实时会话 | 当启用时,开始追踪后,实时会话将自动在Unreal Insights中打开。 这个选项只在Trace存储中进行追踪时适用。 |
追踪后打开Insights | 当追踪停止或快照保存后,录制的会话将自动在Unreal Insights中打开。 |
追踪后在资源管理器中显示 | 当追踪停止或快照保存后,包含录制会话的文件夹将自动打开。 |
位置
位置类别控制trace(保存到文件和Trace服务器)的存储位置。
| 选项 | 说明 |
|---|---|
打开追踪存储目录 | 保存在Trace服务器中追踪器的位置。 |
打开分析目录 | 打开当前项目的分析目录。 这是存储文件追踪器的位置。 |
Insights
Insights类别包含打开Unreal Insights、实时会话和录制文件的设置。
| 选项 | 说明 |
|---|---|
Unreal Insights(会话浏览器) | 启动Unreal Insights会话浏览器(Session Browser)。 |
打开实时会话 | 打开当前的实时会话。 这只有在对库进行追踪时才能实现。 |
最近追踪 | 打开记录在追踪库或文件中最近打开的追踪器。 |
Trace状态
你可以通过使用控制台命令Trace.Status检查有关连接、内存使用、重要事件缓存、已发送数据、已启用和可用的追踪通道信息。
使用命令提示符运行Insights
要从命令提示符运行Unreal Insights,请按以下步骤操作:
导航到你的
Engine\Binaries\Win64文件夹并双击UnrealInsights.exe。从操作系统启动命令提示符(Command Prompt)并运行你的项目。 在以下示例中,请将安装路径和项目名称替换为你自己的:
C++cd C:\[MyEngineInstallLocation]\ Samples\Games\Binaries\Win64\[YourProject].exe
尾部追踪
尾部追踪(Tail Tracing)会追踪最近几秒内的事件(取决于缓冲区大小)。 因此所有设备都可以显示出一定的提前量。
缓冲区的默认大小为4MB,但是如果你希望修改或停用它,可以使用控制台命令-tracetailmb=X。
将X设置为0MB可以将其停用,其他数值则会相应地更改缓冲区大小。
延迟连接
虚幻引擎的客户端会将重要事件进行缓存,然后在连接过程中发送至延迟连接的机器。 因此在你可以进行连接之前不会错过一次性的事件(重要事件)。
Insights可以指示远程运行的虚幻引擎实例从其本地UI实例连接到远程跟踪服务器,并且不需要涉及本地机器。
延迟连接可以通过导航到Unreal Insights > Connect启动,或者在编辑器控制台中输入以下任意命令:
"trace.send [ip]" / "trace.start [filename]"-trace.start [file] [channelSet] -tracehost=[ip]-tracefile = [filepath]
Unreal Insights有一个基于文件的缓存系统,使应用程序可以将额外的信息附加到追踪器中。 这可以用来更快地检索以前的计算结果,或储存可能会丢失的数据,如符号。 缓存被存储在trace文件旁边的<code>.ucache</code>文件中。
Trace用户指南
你可以使用不同的工作流程在Unreal Insights中执行追踪。 有关文档,请参阅Trace用户指南。
Trace开发者指南用户指南
你可以在Unreal Insights中开发你自己的追踪器。 有关文档,请参阅Trace开发者指南。