简介Tracy Profiler中文用户手册面向需要定位性能瓶颈、优化CPU与GPU程序运行效率的开发者覆盖从客户端集成、代码插桩到实时帧分析与采样分析的全流程。资源为1个docx格式文档约1.26MB内容编排紧凑便于检索查阅。手册基于2025年6月英文版整理除基础集成步骤外详述了FrameMark、ZoneScoped等标记用法、锁与内存分析、OpenGL、Vulkan、Direct3D、Metal等图形API的GPU分析以及Lua、Python、Fortran、C语言接口扩展。还包含区域统计导出CSV、导入外部性能分析数据、配置文件详解等高级主题针对Visual Studio、Linux、Android、Docker等平台给出故障排除、网络端口设置、崩溃处理等实用提示。已有228人学习下载适合刚接触Tracy的开发者系统入门也可供已上手者查阅高级分析与多语言接入方案。1. 程序卡顿只能靠猜Tracy 让性能分析跟着帧走做实时渲染或音视频处理的人都有过这种体验程序平均 60 帧但每十几秒跳一帧加日志只能看到“慢了 15 ms”看不出是哪个函数抢了时间。以前我用 perf 抓采样、用日志打时间点折腾一轮要重跑好几遍而且采样是事后数据现场早丢了。Tracy 是少数把性能分析做成“跟程序同步跑”的工具它把客户端的耗时、内存、栈采样实时传给图形界面卡顿那一帧的调用栈可以直接在回放里展开。下面按“接入工程 → 用 Zone 标记 → 调好参数 → 避坑 → 回放定位”的顺序把 Tracy 从能跑到会用的关键细节一次讲透。适合游戏引擎、仿真、音视频实时处理等需要帧级性能洞察的开发者也适合团队把性能回归当作日常流程来做。2. 从零接入 Tracy 工程最小步骤与第一次数据上屏2.1 先分清角色采集端、服务端、录制文件与回放窗口Tracy 的架构值得在动手前理解清楚它是“采集端与观察端分离”的。采集端是被测量的程序本身链接 TracyClient 静态库后性能数据会写入一块有界环形缓冲再异步推给观察端。观察端是一个叫 Tracy Profiler 的图形界面它可以是实时连接的“服务端”也可以在程序跑完后回放一份录制文件。这个分离带来的好处是业务线程只负责写内存队列推送不阻塞观察端如果没打开程序依然正常运行数据照常记录稍后连接时还能补传。我一般把使用方式分成三种。第一种是实时连接先启动 Tracy Profiler再运行被测程序界面自动发现进程并连接适合改代码调优的迭代循环。第二种是录制文件让 Tracy Profiler 带参数跑一段时间把数据写到磁盘适合做回归对比。第三种是回放已有文件程序早就退出了再用回放窗口看录制文件适合拿到同事机器上复现问题。后两种是 Tracy 区别于很多采样器的地方它能做到“事后复盘”而不是只能现场盯着。2.2 用 CMake 接入 TracyClient 的最小工程拿到源码后常见做法是把整个 Tracy 目录放进工程通过add_subdirectory引入这比手写一串 .cpp 文件列表更稳。最小 CMake 如下cmake_minimum_required(VERSION 3.14) project(tracy_demo CXX) set(CMAKE_CXX_STANDARD 17) # 把附带的 tracy 源码放到 third_party/tracy add_subdirectory(third_party/tracy) add_executable(demo main.cpp) target_link_libraries(demo PRIVATE Tracy) # 总开关不定义时所有 Zone 宏都是空操作 target_compile_definitions(demo PRIVATE TRACY_ENABLE) find_package(Threads REQUIRED) target_link_libraries(demo PRIVATE Threads::Threads)上面这段里target_link_libraries链接的是 Tracy 项目自带的 CMake target名字就是TracyTRACY_ENABLE是宏总开关它必须在调用 Tracy 宏的源文件里可见所以放在target_compile_definitions里会随编译命令自动加上。如果你的工程不用 CMake等价做法是把 Tracy 目录里所有 .cpp 编进目标再在你的全局预处理器里加入TRACY_ENABLE。注意 Tracy 依赖 pthreadWindows 上默认线程库已就绪Linux 上不要漏了 Threads。还要多说一句TRACY_ENABLE不是写在 Tracy 的公开头文件里的而是由使用方定义这正是“零开销开关”的来源。只要不定义它ZoneScoped这类宏会展开成空语句不会有任何变量或分支定义它宏才会变成真实的计时对象。因此代码可以始终保留 Tracy 标记由构建配置决定是否采集。2.3 在 main 函数里点亮第一帧数据先把最简的插桩代码写进工程#include tracy/Tracy.hpp void DrawFrame() { ZoneScoped; // 离开 DrawFrame 作用域时自动提交耗时 // 画面绘制、逻辑更新等业务代码 } int main(int argc, char** argv) { tracy::StartupProfiler(); // 可选不写也会在首个 Zone 时自启动 while (true) { DrawFrame(); FrameMark; // 标记完整一帧的结束位置 } return 0; }代码逻辑并不复杂关键在于理解两个宏的行为。ZoneScoped展开后会在当前函数里创建局部对象构造函数记录进入时刻析构函数提交 zone 事件名字默认取函数名DrawFrame嵌套函数时会自动形成父子树。FrameMark则负责“画帧结束线”服务端通过连续两个FrameMark之间的时间算出帧耗时与帧率。若某个循环里本身没有“帧”的概念可以不写FrameMark只看 zone 树但对于游戏与渲染类应用帧曲线是最直观的第一屏指标。若不想用函数名也可以写成ZoneScopedN(顶点提交)名字会显示在资源树里想在界面里直接看到业务字符串配合后面章节的ZoneText使用。2.4 第一次连线看见帧时间曲线按下面顺序操作能最快排除网络与版本干扰先运行 Tracy Profiler 图形界面保持默认端口监听。运行刚才编出来的 demo观察界面是否出现“新进程被发现”的提示。如果没有自动发现在连接面板手动填localhost:8086连接。连线成功后左侧面板会出现每秒更新一次的帧时间曲线下方按线程列出 zone 树把帧时间缩放到毫秒级能看到DrawFrame的耗时曲线。提示Tracy 客户端默认连接本机 8086 端口多机器联调时先确认防火墙放行 TCP 8086。首次跑通后不要着急优化先把“能录、能看、能回放”这条链路跑稳后面所有定位工作都建立在这条链路上。3. 用 Zone 把性能分析落进代码作用域、嵌套与采样热度3.1 Zone 是对象不是日志自动收尾才有嵌套树很多刚接触 Tracy 的人把 Zone 理解成“打点”进入时记录、离开时记录。这个直觉对了一半但漏掉了 Tracy 最有用的父子关系。ZoneScoped生成的局部对象会把自己挂在当前线程的 zone 栈顶离开作用域时弹出所以它天然形成一棵嵌套树函数 A 调用 BB 的 Zone 就显示为 A 的子节点。服务端左侧展示 zone 树右侧展示耗时分布自顶向下能定位到具体函数自底向上能看到某个热点被谁调用。读懂 zone 耗时需要区分总时间与自用时间。服务端每一个 zone 都显示两个值总耗时是进入 zone 到离开 zone 的全部时间自用时间是总耗时减去所有子 zone 的耗时。比如一个DrawFrame总耗时 16 ms调用影子 pass 花掉 8 ms粒子更新花掉 5 ms那么DrawFrame自用时间只有 3 ms。遇到慢帧先看自用时间大的那个 zone它才是“自己慢”而不是“下面某个子函数慢”。另一个关键性质是“作用域自动收尾不依赖 return 路径”。代码里函数可能有多处提前return如果用手工打点很难保证每个出口都补齐结束时间ZoneScoped借助栈对象析构不管从哪个return离开时间都会被记录也不会出现“结束时间早于开始时间”的脏数据。在一个成熟工程里往关键路径的函数第一行都塞一个ZoneScoped是安全的。我见过上千个 zone 的项目性能分析本身的开销仍落在可接受区间。但也要明确Zone 是给“函数或代码块”用的不是给循环用的。想看清循环内部每次迭代的波动必须把 Zone 写在循环体内。把for (int i...) Update(i)改成每次迭代一个ZoneScopedN(粒子更新)才能看出某一帧里到底是哪一次调用超时。3.2 三种 Zone 写法分别适合什么场景Tracy 提供了几档粒度不同的写法void UpdateAI() { ZoneScoped; // 用函数名 UpdateAI DoAStar(); DoBehavior(); } void RenderShadow() { ZoneScopedN(阴影Pass); // 自定义可读名字 DrawShadowMap(); } void FlushCommands(bool enabled) { tracy::ScopedZone zone(命令刷写, enabled); // 可用变量控制是否采集 SubmitCommandBuffer(); }ZoneScoped主要用于函数级追踪缺点是被编译器内联后名字可能带不上目标信息ZoneScopedN适合区分同名重载或给逻辑阶段起业务名比如“阴影Pass”“粒子排序”。ScopedZone是手动构造的栈对象构造函数的第二个active参数能在运行时按条件裁剪数据量这在发布版本排查低频问题时很好用默认关只有现场临时打开收集。同帧内RenderShadow被调用 5 次时服务端会按出现顺序带序号显示 5 个同名校验节点总时间可展开成 5 个独立条目。回放时间轴上能看到 5 个色块判断波动时比看平均值更有价值。还有一点容易被忽略把 Tracy 头文件放进预编译头后ZoneScoped对编译期性能几乎无感但在一处非常热的小函数里频繁进出 zone服务端收到的 zone 数目会非常大。此时可以用activefalse的分支或干脆少包几层而不是追求完美包裹。3.3 给 zone 挂文本与数值从“查得到函数”升级到“看得见参数”性能分析到函数级还不够很多热点函数在不同参数下行为差异巨大。Tracy 允许在 zone 存活期间附加额外信息void LoadTexture(const char* path, int bytes) { ZoneScopedN(加载纹理); ZoneName(path, strlen(path)); // 在 zone 树中显示资源路径 ZoneValue(bytes); // 该 zone 附加可排序的数值 TracyPlot(加载耗时, LoadMs()); // 单独的时间序列曲线 TracyMessage(换图完成, 5); // 一条带时间戳的普通消息 }ZoneName的第一个参数是字符指针第二个是长度数据会被复制进客户端缓冲界面里悬浮显示资源路径ZoneValue给当前 zone 一个数字在 zone 列表中按最大值排序时可以快速找出“最重的纹理”或“最慢的实体”。TracyPlot则是独立于 zone 的连续量适合记录帧率、内存占用、队列深度这类过程量。参数虽然简单但组合起来能让一次录制的信息密度高很多回放时不用靠脑补。这里要补充一个生命周期细节ZoneName传入的字符串只需要在 zone 离开前有效它是复制语义不是引用语义所以传std::string的c_str()完全没有问题。想给时间轴加视觉分组用ZoneScopedC(0x00AAFF)这种带颜色的变体0xRRGGBB格式渲染阶段用暖色、I/O 用冷色回放时一眼能扫出阶段边界。3.4 数据量爆炸时的收敛策略这里其实是最容易翻车的点如果整个游戏逻辑每个函数都ZoneScoped录制十几分钟后区域树会巨大服务端下拉列表卡顿。我的经验是分两层一层在关键流程函数每帧一次放ZoneScopedN控制 zone 数量级一层在高频热路径里用active开关控制默认关闭只在排查时临时启用。这样既保住整体可读性又不彻底失去热路径视角。想更精细一点可以在录制阶段临时把ZoneText和TracyMessage的调用频率降下来字符串是缓冲区的大户一次ZoneText的占用远比普通 zone 高。4. Tracy 参数怎么调四个开关决定你录到的是现场还是废料4.1 编译期宏影响数据量、连接行为与兼容性Tracy 的参数分两层编译期宏与服务端启动参数。先看编译期宏下面表格是我在工程里常用到的几个宏默认作用TRACY_ENABLE未定义总开关定义了才让 Zone/TracyMessage 生效TRACY_NO_EXIT未定义服务端已连接时进程退出前等待缓冲区刷完TRACY_ONLY_IPV4未定义禁止 IPv6 尝试只走 IPv4降低连接失败概率TRACY_NO_SAMPLING未定义关闭 CPU 采样只有 zone/消息数据TRACY_BUFFER_SIZE4MB客户端有界缓冲大小需为 2 的幂TRACY_ENABLE不必解释TRACY_NO_EXIT值得多说程序退出时缓冲区里可能还积压最后几十毫秒的数据如果让进程直接退出这些数据会丢。定义它之后Tracy 在退出前会多等一会儿把缓冲推完再返回。对命令行工具、跑完就退出的 CI 任务我建议定义它避免每次回放都缺最后一段对长驻服务进程影响不大。TRACY_ONLY_IPV4主要解决双栈环境下的连接超时局域网联调时几乎必开。TRACY_BUFFER_SIZE默认 4MB 对大多数游戏帧够用但如果往里塞大量ZoneName或ZoneText字符串缓冲会更快填满填满后 Tracy 会丢弃新事件并在界面上报丢包计数。调大它不等于万能更大缓冲意味着程序内存占用上涨更推荐从源头减少文本信息。采样数据是 Tracy 里最容易被低估的体积来源。开了采样后每个线程会定时被抓取当前 PC 与调用栈每一帧可能生成几十条采样记录这些记录会挤占缓冲。回放时你看到采样密集但代价是丢包率上升。我的经验是新工程默认不开采样先看 zone 数和帧时间等 zone 层面已经圈定可疑函数再重编一版开采样验证调用路径。4.2 服务端启动参数实时观察与离线录制跟编译宏互补的是 Tracy Profiler 的启动参数。常见做法是常驻一个图形界面用于临时观察真正做回归对比时用录制参数# 实时观察默认监听 8086 ./tracy-profiler # 录制 30 秒到文件适合自动化回归 ./tracy-profiler -f 30 -o regression.tracy # 回放已录制文件程序不在场也能分析 ./tracy-profiler -l regression.tracy-f后跟的是录制时长单位秒服务端会在这段时间内持续接收并写盘-o指定输出文件-l则进入纯回放模式不监听端口。把三者组合起来就能把“现场发现卡顿”变成“先录音再细看”卡顿一出现立刻用-f 10录一小段事后加载文件逐帧翻不耽误现场继续跑程序。端口冲突时可以用-p参数指定其他端口同时让客户端代码里对应设置同端口。如果录制时间很短但文件很大说明客户端缓冲里包含了大量采样栈或字符串结合 4.1 缩小采样与文本是最直接的减量办法。录制文件默认不压缩所以“录得久”不等于“省心”剪出事故现场附近 30 秒往往比录 10 分钟更有价值。4.3 采样深度与线程命名别忽略的两个隐性参数Tracy 的采样器默认会开启但要让采样结果有栈可看往往需要编译器不要省略帧指针或在客户端开启栈回溯。构建时加-g与-fno-omit-frame-pointer是最保险的组合发布配置也建议保留-g只是忽略调试符号而不是完全不生成这样采样界面能还原函数名。如果采样栈不够深可以在客户端源码里调整TRACY_CALLSTACK宏定义的深度值这个值不是越大越好深度越大采样开销越高默认场景下 20 到 50 帧通常够用。多线程场景下线程名直接决定回放可读性在代码里调用tracy::SetThreadName(Render)或系统线程 API 设置服务端会按名字分组否则一堆0x1234的线程 ID 很难映射到业务逻辑。对服务端显示窗口我还会把不直接看的面板关掉比如内存面板、消息面板只保留帧时间与 zone 树回放拖动会更顺尤其是录制文件很大的时候。5. 用着用着就翻车Tracy 五个常见坑与排查顺序性能分析工具的问题通常分三类事件缺失、连接异常、数据解释困难。按“先编译宏、再连接、后数据质量”的顺序排查最快。下面五条是按我实际工程中出现频率排的。5.1 Release 下 Zone 全部消失现象Debug 下一切正常Release 连上服务端后只有线程、没有 zone 树也没有任何耗时上屏。原因最常见是TRACY_ENABLE没有在 Release 的编译定义里生效。它可能只在某个源文件用手动#define加上其他翻译单元不知道或者 clean build 没有执行旧对象残留导致宏状态不一致。解决在 CMake 里统一写成target_compile_definitions(demo PUBLIC TRACY_ENABLE)而不是PRIVATE或散在代码里改完删掉 build 目录重新配置。Linux 上可以用nm -C ./demo | grep -i tracy看有没有 Tracy 符号Windows 上则用dumpbin /symbols过滤 Tracy 符号。如果符号列表里什么都没有说明编译宏确实没生效而不是连接问题。5.2 进程能被发现但连接一直转圈现象服务端列表里能看到被测进程名点连接后界面一直 pending没有任何数据。原因Tracy 用 UDP 广播做“发现”随后建立的是 TCP 连接。本机防火墙放行了 UDP 但没放行 TCP 8086或者 IPv6 优先导致客户端尝试了不通的地址。解决客户端定义TRACY_ONLY_IPV4服务端用-p 8086显式固定端口并在防火墙规则里放行 TCP 8086。本机调试时直接用localhost手动连接能绕开大部分局域网问题。Windows 下可以先netstat -ano | findstr 8086确认监听端口存在再排查防火墙。5.3 帧时间曲线全是毛刺看不出卡点现象FPS 曲线跳得跟心电图中风一样但 zone 树里每个函数都正常找不到具体是哪一帧慢了。原因FrameMark的位置不对。如果在一次业务循环里放了多个FrameMark帧周期被切碎如果主线程没有FrameMark服务端按默认间隔硬切曲线就会锯齿化。解决在一帧逻辑的固定结尾只放一次FrameMark且该调用必须落在主线程横跨多帧的工作用 Zone 表示不要用FrameMark。定位卡点时把时间轴放大到怀疑区间再打开线程活动视图看那一帧里 CPU 是空转还是确实在做某段计算。5.4 录 10 分钟文件占了 20G回放机器直接卡死现象录制时间不长输出文件巨大加载回放时内存飙升界面无响应。原因采样栈、ZoneText字符串、TracyMessage日志全都进了缓冲大量重复字符串没有合并Tracy 录制文件默认不压缩信息密度越高文件越大。解决录制前在编译宏里打开TRACY_NO_SAMPLING或在代码里减少ZoneText/TracyMessage的调用频率补救办法是回放时用时间范围截取关键区间把 10 分钟裁成 30 秒再导出只保留事故现场附近的数据。回放大文件前把机器上不必要的后台程序关掉也能减少渲染线程自身争抢 CPU 造成的顿挫。5.5 显示耗时与自行计时对不上现象用std::chrono在函数外计时是 4 msTracy 里同一个函数显示 8 ms差了一倍。原因微观基准最容易踩计时器一致性坑。多核调度下 TSC 或 QPC 在部分 CPU/虚拟机环境存在跳变Tracy 如果有调试模式zone 对象本身也有构造析构开销Release 下编译器内联会把两个相邻区域的边界弄得模糊。解决用 Tracy 看相对变化与热点定位看绝对时间用外部计时器校验遇到跳变可以在编译参数里尝试把TRACY_FAST_TIMER设为 0强制走通用计时路径。对“差异大”这类问题先确认是不是 Release 与 Debug 的优化差异再动手改代码。6. 用 Tracy 回放一次真实慢帧验证优化效果的完整链路最后一层落地动作是把前面所有能力串成一条可重复的验证流程。遇到“慢帧”报告我的标准流程是先现场录制再用回放定位最后用第二份录像确认修复。第一步程序能固定复现问题时在 Tracy Profiler 窗口里启动 10 秒录制-f 10 -o slow.tracy期间让故障场景完整走一遍。第二步加载slow.tracy把时间轴拖到帧耗时峰值处先看是哪条线程占满 CPU再在 zone 树里按最大值排序找到真正消耗的那层函数如果 zone 树里看不出切到 Sampling 面板看采样热点。第三步修改代码后重新运行录第二份fix.tracy把两张曲线叠在一起看峰值是否回落。这个流程里最容易出问题的细节是“对比录制的条件”。我会固定从启动到故障出现的时间点固定录制约 10 秒固定用同一帧业务场景否则前后两版曲线因负载不同而失去可比性。若网络中断或缓冲丢包录制文件里会出现空洞判断依据是服务端窗口右上角的丢包计数计数不为 0 时这份数据只能定性不能定量。进阶技巧上我常用时间范围裁剪导出回放模式里选中 2 秒关键段裁剪后另存为单独文件后续分析和归档都基于这个小文件既避免回放大文件卡顿也方便把复现材料发给同事时只带最小数据量。另一个值得养成的习惯是每次版本发布前录一份 30 秒基准存档放在 CI 产物里当某个版本回归卡顿时直接对比存档与当前版本曲线能省下大量复现时间。我自己早期只在排查问题时才打开 Tracy后来固定成“功能完整版必录一份”的做法后性能回归的可追溯性明显好了很多也顺手救回过一次压测现场的数据。这个习惯比任何单一参数都管用希望帮到你。本文还有配套的精品资源点击获取