企业官网建设流程全解析

Tracy 帧分析器保存 Trace 完整指南：界面操作、压缩选项与后台写盘机制

【免费下载链接】tracyFrame profiler项目地址: https://gitcode.com/GitHub_Trending/tr/tracy

将应用程序的跟踪数据（Trace）保存为.tracy文件，是 Tracy 帧分析器使用流程中的关键一环：无论是为了日后回看、对比优化前后的性能差异，还是把文件发给同事与朋友协作分析，都需要先掌握正确的保存方式。本文以 Tracy 仓库中的官方文档 SaveTrace.md 为骨架，结合 TracyView.cpp、TracyView_ConnectionState.cpp、TracySafeFileWrite.hpp 等源码实现，完整讲解从界面入口到后台落盘的整条链路，包括四种压缩算法的取舍、Zstd 级别与压缩流数量如何配置、后台线程保存机制，以及分享 trace 文件时必须注意的隐私风险。

一、为什么要把 Trace 保存到磁盘

保存 Trace 最直接的价值是保留一份可反复查看的性能快照：

• 优化效果对比：保存优化前的 Trace，完成优化后再采集一份，两者放在一起即可直观比较各 Zone 耗时、帧时间、CPU 占用等指标的变化，验证优化是否真正生效。
• 问题追溯：某些性能问题只在特定数据、特定负载下出现，现场排查往往来不及，落盘后可以随时离线复盘，不再依赖被测程序持续运行。
• 团队协作与分享：Trace 文件是自包含的二进制文件，不依赖原始被测程序即可在 Tracy 中完整回放，因此可以发给同事或同事一起分析瓶颈（详见后文"安全与隐私"一节的注意事项）。

需要说明的是，保存动作不要求跟踪会话已经结束。正如官方文档所述，你可以在跟踪过程中随时保存当前已采集到的数据。

二、保存 Trace 的操作入口

保存入口位于屏幕左上角的 Connection 图标（跟踪连接面板）内。具体路径如下：

1. 点击左上角 Connection 图标，打开连接信息面板；
2. 在面板中找到Save trace…按钮并点击；
3. 在弹出的系统文件选择对话框中指定保存路径与文件名；
4. 确认后在弹出的小窗口中微调压缩参数并点击Save trace完成保存。

对应源码位于 TracyView_ConnectionState.cpp。其中有两个值得注意的实现细节：

（1）保存按钮与保存线程状态联动：按钮的可用性受m_saveThreadState状态机约束，只有当状态为Inert（空闲）时点击才会触发文件选择器，避免在上一次保存尚未结束时再次发起保存。

（2）.tracy扩展名自动补全：文件选择回调会检查用户输入的文件名结尾 6 个字符是否为.tracy，若不符合则自动追加该扩展名：

const auto sz = strlen( fn ); if( sz < 7 || memcmp( fn + sz - 6, ".tracy", 6 ) != 0 ) { char tmp[1024]; sprintf( tmp, "%s.tracy", fn ); m_filenameStaging = tmp; }

此外，若在编译期定义了TRACY_NO_FILESELECTOR（禁用系统文件选择器的构建配置），则跳过文件选择流程，直接以默认文件名trace.tracy触发保存。用户数据会记录保存路径（m_userData.SetFilePath( fn )），便于再次打开时定位上次使用的目录。

三、保存设置弹窗：压缩参数详解

点击 Save trace… 后弹出的模态窗口（对应 TracyView.cpp）会先显示目标路径，随后是一个Trace compression折叠面板，用于配置保存时的压缩策略。

3.1 四种压缩算法：速度与体积的取舍

压缩算法的定义位于 TracyFileWrite.hpp：

enum class FileCompression { Fast, Slow, Extreme, Zstd };

弹窗中对应的选项名称与说明（来自 TracyView.cpp）整理如下：

四种模式在 WriteStream 构造函数 中分别初始化 LZ4 流、LZ4 HC 流（Extreme 模式强制使用最高压缩级别LZ4HC_CLEVEL_MAX）以及 Zstd 压缩流，压缩动作在WriteStream::Compress()中按块执行。

一句话选型建议：追求保存速度选 LZ4，追求加载速度且不介意保存稍慢选 LZ4 HC，追求最小文件体积选 Zstd。Zstd 是默认选中项，兼顾体积与均衡的加载表现。

3.2 Zstd level：压缩强度滑条

选中 Zstd 后，可以拖动Zstd level滑条（范围 1～22，默认 3）调整压缩级别。界面上给出的提示是：Increasing level decreases file size, but increases save and load times（级别越高文件越小，但保存与加载时间都变长）。该值在底层直接传入ZSTD_CCtx_setParameter( ..., ZSTD_c_compressionLevel, level )设置 Zstd 压缩级别。

3.3 Compression streams：并行压缩流

Compression streams滑条（范围 1～64，默认 4）控制压缩流的并行度。界面提示Parallelize save and load at the cost of file size（以文件体积为代价并行化保存与加载）。增大流数量可以显著加快大 Trace 的保存与重新加载速度，代价是文件头部需要额外保存多流索引与元数据，文件体积略有增加。

3.4 Build frame images dictionary：帧图像字典

只有当当前 Trace 中包含帧图像（Frame Image）数据时，该复选框才会出现（判断条件为m_worker.GetFrameImageCount() != 0）。勾选后会在保存时为帧图像构建共享字典，官方说明为Decreases run-time memory requirements（降低运行时内存需求），适合采集了密集帧图像的长 Trace。

3.5 参数记忆行为

comp、zlvl、streams、buildDict在 TracyView.cpp 中声明为函数内的static变量，意味着这些选择会在一次 profiler 会话中跨多次保存被记住，无需每次重新设置。

四、保存按钮与失败处理

设置完成后点击Save trace按钮（TracyView.cpp），流程如下：

saveFailed = !Save( fn, comp, zlvl, buildDict, streams ); m_filenameStaging.clear(); ImGui::CloseCurrentPopup(); Achieve( "saveTrace" );

• 保存成功会触发成就系统（Achievements）中的saveTrace成就，该成就文本定义于 TracyAchievementData.cpp；
• 若Save()返回失败，会弹出Save failed模态窗口，提示Could not save trace at the specified location. Try again somewhere else.（无法在指定位置保存，请换一个位置重试），点击 "Oh well" 关闭；
• 窗口同时提供Cancel按钮，可放弃本次保存。

五、后台线程写盘与原子提交机制

Trace 保存不是阻塞 UI 的同步操作。View::Save()（TracyView.cpp）的实现揭示了完整的后台写盘链路：

bool View::Save( const char* fn, FileCompression comp, int zlevel, bool buildDict, int streams ) { std::unique_ptr<SafeFileWrite> f( SafeFileWrite::Open( fn, comp, zlevel, streams ) ); if( !f ) return false; m_filename = fn; if( m_stcb ) UpdateTitle(); m_userData.StateShouldBePreserved(); m_userData.SetFilePath( fn ); m_saveThreadState.store( SaveThreadState::Saving, std::memory_order_relaxed ); m_saveThread = std::thread( [this, f{std::move( f )}, buildDict] { Worker::MainThreadDataLockGuard lock = m_worker.ObtainLockForMainThread(); m_worker.Write( f->File(), buildDict ); f->File().Finish(); const auto stats = f->GetCompressionStatistics(); m_srcFileBytes.store( stats.first, std::memory_order_relaxed ); m_dstFileBytes.store( stats.second, std::memory_order_relaxed ); f->Commit(); m_saveThreadState.store( SaveThreadState::NeedsJoin, std::memory_order_release ); } ); return true; }

该实现的关键点：

• 临时文件 + 原子重命名：SafeFileWrite::Open()（TracySafeFileWrite.hpp）实际是先向<文件名>.tmp写入数据，全部写完后在Commit()中通过std::filesystem::rename原子地改名为最终文件。这意味着即使保存中途崩溃，也不会留下一个残缺的"正式" trace 文件。
• 后台线程序列化：数据写入在独立线程中执行，并通过Worker::MainThreadDataLockGuard获取主线程数据锁，保证与 UI 渲染线程的读写互斥、避免数据竞争。UI 侧通过m_saveThreadState（Inert/Saving/NeedsJoin）状态机跟踪保存进度。
• 保存进度可见：保存期间，通知区域会显示Saving trace…指示（TracyView_NotificationArea.cpp），并在结束后更新压缩前后字节数统计（m_srcFileBytes/m_dstFileBytes），这些数据用于在界面中展示压缩率。

六、保存之后的衍生操作

保存完成后，.tracy文件可以与 Tracy 的其他配套工具协同使用，进一步放大其价值：

• 重新加载：通过 profiler 主界面打开已保存的.tracy文件即可离线回放完整分析（打开方式与保存对应，见 TracyView_ConnectionState.cpp 中的连接/加载逻辑）。
• 升级转换：保存弹窗中注明压缩方式Can be changed later with the upgrade utility（之后可用升级工具更改），即仓库中的 update/ 工具（update.cpp）可以离线调整旧 trace 文件的压缩格式与级别。
• 合并与导出：仓库还提供 merge/（合并多个 trace，merge.cpp）与 csvexport/（导出为 CSV，csvexport.cpp）等工具，可基于保存的 trace 文件做二次加工。

七、安全与隐私：分享 Trace 前请三思

官方文档对分享 Trace 给出了明确的警告，这也是本文最需要强调的一点：

Warning：Trace 文件可能包含关于应用程序的敏感信息，例如程序代码，甚至是源文件的内容。与他人分享时务必小心。

Tracy 的采样与调用栈采集机制会记录函数名、符号、源码路径，结合源码视图功能甚至可能还原出源代码片段。因此：

• 在把.tracy文件发送给外部人员或上传到公共场合之前，先自行打开检查一遍，确认没有泄露专有代码、密钥相关符号或内部路径；
• 对于仅需对比性能数据的场景，可考虑先移除或模糊化敏感符号信息（取决于采集时启用的选项）再分享；
• 团队内部分享同样建议遵守数据最小化原则。

八、小结：保存 Trace 的正确姿势

掌握了从 Connection 面板入口到压缩参数配置、再到后台原子写盘机制的完整链路，你就能把每次跟踪会话高效地沉淀为可复用、可分享、可对比的性能资产。深入阅读源码可继续查看 TracyView.cpp（保存弹窗与View::Save实现）、TracySafeFileWrite.hpp（临时文件与原子提交）、TracyFileWrite.hpp（四种压缩算法的底层实现）以及 TracyView_ConnectionState.cpp（入口按钮与扩展名补全逻辑）。

【免费下载链接】tracyFrame profiler项目地址: https://gitcode.com/GitHub_Trending/tr/tracy