简介Tracy是一款开源的跨平台性能分析工具支持CPU、GPU实时分析具有纳秒级分辨率和低性能开销。这份中文版用户手册是其官方文档的翻译适合需要定位性能瓶颈、优化C/C程序的开发者阅读。文档从快速概览讲起逐步介绍客户端集成步骤、代码插桩方法、数据捕获与存储、图形界面分析操作并覆盖区域统计导出CSV、导入其他分析器数据、配置文件调整等高级功能。同时针对Microsoft Visual Studio、Linux、Android、Docker等常见环境给出设置说明和故障排除指引。资源包包含1个docx文件大小1.26MB内容结构清晰可直接按章节查阅。目前已有228人学习下载对于希望低门槛上手Tracy并系统掌握其用法的开发者而言是一份实用的入门与参考手册。1. Tracy 是什么一个敢把每帧开销压到 2.25ns 的分析器Tracy 是我见过把“采集开销”压到最狠的性能分析器不是那种一打开就拖慢程序的重量级工具。官方手册里有一组实测数据在 etcpak 项目里压缩 16384×16384 像素图4×4 像素块压缩函数跑了 201,326,592 个区域每个区域从开始标记到结束标记埋在代码里的平均开销只有 2.25ns。换句话说你插桩的逻辑跑一千万次才多花 22 毫秒左右。这个数字决定了它的定位——给那些被手游卡顿、桌面应用半随机掉帧折磨又不想为了排查一个帧问题把整个工程换成另一个语言或框架的开发者。Tracy 的核心能力是混合帧分析与调用栈采样既能看到每个函数在逐帧时间线上的执行情况也能在没有插桩的区域直接看采样热点还支持 CPU、GPU、内存分配、锁竞争、上下文切换的完整追踪。适合游戏引擎、音视频处理、压缩工具、UI 应用这类对时间敏感的项目跨平台覆盖 Windows、Linux、macOS、Android、iOS一份中文文档在手基本能把整套分析流程捋顺。2. 集成与插桩先把 TRACY_ENABLE 定义对再谈分析2.1 最小集成四步把 Tracy 塞进现有工程Tracy 的客户端集成方式比很多同类工具都简单不需要装独立 SDK不需要改构建系统核心就是把public目录下的文件加进工程。第一步是用 git submodule 把仓库挂进来git submodule add https://github.com/wolfpld/tracy.git 3rdparty/tracy然后需要做的只有四件事把public/TracyClient.cpp作为源文件加入编译把public目录加入头文件搜索路径在需要分析的每个源文件里#include tracy/Tracy.hpp最后最关键的一步在全局编译定义里加上TRACY_ENABLE宏。这个宏是整个客户端的开关没定义的话所有 Tracy 调用都会编译为空操作不会产生任何数据但也不会报错。// 在某一个需要分析的 CPP 文件里 #include tracy/Tracy.hpp void RenderFrame() { ZoneScoped; // 函数入口处标记区域 RenderScene(); RenderUI(); }ZoneScoped会自动用当前函数名和源码行号创建一个分析区域区域从这一行开始到当前作用域结束为止。它在 C 里利用了 RAII不需要手动调结束标记函数一退出就自动收尾。如果你希望区域名称更有辨识度可以用ZoneScopedN(实际显示的名字)覆盖默认的函数名。在整个项目里只需要在每帧循环末尾加一个FrameMark宏Tracy 就能把帧边界对齐帧时间线图表也依赖这个标记。编译时需要注意几个点Tracy 官方建议开启常规优化选项分析 Debug 版没有意义因为未优化代码和额外检查会改变程序行为能开-marchnative就开Tracy 会用上扩展指令集Unix 系系统要链接libpthread和libdlBSD 还要额外链接libexecinfo。CMake 集成最省事官方的CMakeLists.txt把目标都建好了# 在 add_subdirectory 之前设置选项 option(TRACY_ENABLE ON) option(TRACY_ON_DEMAND ON) add_subdirectory(3rdparty/tracy) # 目标TracyClient 或别名 Tracy::TracyClient target_link_libraries(你的目标 PUBLIC Tracy)注意这里TRACY_ON_DEMAND是用来控制按需分析模式的后面会细说。CMake 选项名和源码里手动定义的宏名是对应关系用 CMake 集成可以少写很多全局 define。2.2 插桩层级从只测帧到逐函数标记插桩是 Tracy 分析的核心但不需要一步到位。建议的路径是先在帧循环加FrameMark确定整体帧时间分布再对嫌疑最大的几个函数加ZoneScoped如果热点函数内部有多个阶段比如读取数据、解码、渲染提交可以再拆成内部多个具名区域。关键是要理解ZoneScoped是自动嵌套的函数 A 调函数 B如果两个函数都插桩了Tracy 的时间线里 B 的区域会显示在 A 内部形成层级关系。void ProcessPacket(Packet* pkt) { ZoneScopedN(ProcessPacket); { ZoneScopedN(ParseHeader); ParseHeader(pkt); } { ZoneScopedN(DecodePayload); DecodePayload(pkt-payload, pkt-size); } }这里用花括号手动限定了子区域的生命周期让时间线里能区分解析阶段和解码阶段的耗时。如果不加内部插桩就只有一个整体的ProcessPacket区域无法定位到具体阶段。Tracy 的设计哲学是先让帧时间图表暴露问题再用插桩去精确定位而不是从一开始就把所有函数都标一遍。2.3 按需模式与短生命周期连接前不采集默认情况下Tracy 在进入main之前就开始采集了事件会缓存在系统内存里直到服务端连接上来才上传。如果你的程序跑的时间长、区域多这个缓存可能涨到数 GB对内存敏感的产品不能接受。解法是定义TRACY_ON_DEMAND宏这样客户端只有在服务端真正连接后才开始采集未连接时开销几乎为零。代价是客户端需要额外做簿记以保持状态一致每个分析事件的开销会略高一点。短生命周期应用是另一个坑。压缩工具、小脚本这类程序可能一秒钟就跑完了等你打开分析器准备连接它已经退出。这时候需要设置环境变量TRACY_NO_EXIT1让客户端在程序执行完毕后不退出继续等待服务端连接。如果平台不方便设置环境变量可以在构建配置里直接加TRACY_NO_EXIT宏效果一样。这两个宏是配套使用的一个控制开始时机一个控制结束时机。2.4 多 DLL 与静态库链接才是隐藏雷区如果你把 Tracy 编译成静态库再链进应用会遇到一个典型的链接器坑静态库只有在程序引用了它提供的符号时才会被整体拉进来。如果你的代码里没有直接调用 Tracy 宏比如只在采样模式下用自动栈采样链接器会认为 Tracy 库是多余的整个客户端根本不会被链接进去分析器自然连不上。解决办法是在代码里加一行TracyNoop;这行代码不产生实际分析数据但会强制链接器把 TracyClient 拉进来。多 DLL 项目是另一个高频翻车点。把TracyClient.cpp同时编译进多个 DLL 是不行的会得到进程里有多个 Tracy 实例的后果数据互相对不上。正确做法是单独建一个专供 Tracy 的 DLL里面包含public/TracyClient.cpp然后让所有需要分析的 DLL 和可执行文件都链接到这个 DLL。Windows 下要在应用侧加TRACY_IMPORTS定义。如果你遇到单独加载或卸载带 Tracy 集成的 DLL 时崩溃或冻结可以同时定义TRACY_DELAYED_INIT和TRACY_MANUAL_LIFETIME后者提供StartupProfiler和ShutdownProfiler函数让你手动控制分析器的创建和销毁避免 DLL 加载顺序引起的静态初始化问题。// 在 DLL 项目中初始化时手动启动分析器 #include tracy/Tracy.hpp void OnDllAttach() { tracy::StartupProfiler(); } void OnDllDetach() { tracy::ShutdownProfiler(); }多库项目最隐蔽的坑是宏定义不一致。比如一个 DLL 编译时定义了TRACY_ON_DEMAND另一个没有定义Tracy 不会报错不会警告但整个数据流就是乱的。你必须确保所有链接进进程的包使用完全相同的功能宏集这个只能靠构建配置的统一管理来保证没有别的捷径。3. 构建服务端与连接从 submodule 到 Connect 的完整链路3.1 服务端构建先搞清楚依赖再动手被分析的应用叫客户端分析器本身叫服务端。这个命名让不少人困惑但逻辑是对的客户端负责采集事件并发给服务端服务端负责处理和展示。服务端是一个独立的图形界面程序既可以和客户端在同一台机器上跑也可以通过网络连接远程分析嵌入式设备或手机上的应用。构建服务端之前需要先确认系统依赖。Unix 类系统要保证有 libpthread 和 libdlLinux 如果要做调用栈采样还必须确认内核支持以非 root 权限访问perf_event_open不然采样功能会静默失效。Tracy 服务端本身的构建不复杂用 IDE 打开profiler目录下的工程或者用 CMake 生成构建文件即可。不建议把服务端嵌入应用除非你有特殊的白盒发布需求——独立进程的好处是即使被分析应用崩溃了服务端还保留着已经收到的数据。3.2 连接与网络端口、广播、客户端发现客户端默认向本地网络广播自己的存在服务端启动后会扫描这些广播信息你在服务端点击Connect就能连上。但是有几个网络相关的细节会影响你能否连上。首先客户端默认监听所有网络接口如果你只想在本地分析可以定义TRACY_ONLY_LOCALHOST宏或者设置环境变量TRACY_ONLY_LOCALHOST1这样客户端不会对局域网开放任何端口安全系数更高。默认优先监听 IPv6不可用时回退到 IPv4想强制走 IPv4 可以定义TRACY_ONLY_IPV4。端口默认是 8086TCP 数据连接广播走 UDP可用下面的宏调整宏名作用默认值TRACY_DATA_PORT数据连接的 TCP 端口8086TRACY_BROADCAST_PORT广播宣告的 UDP 端口8086TRACY_PORT同时设置上述两个端口8086TRACY_PORT还可以作为环境变量在运行时设置不用重编译客户端。注意Tracy 需要在被分析机上打开监听端口防火墙或杀毒软件如果拦截了你会看到一个典型的症状服务端能发现客户端在线但点击 Connect 后一直在重连请求连接成功率低到离谱。另一个常见场景是端口被占用如果默认端口被别的进程占了分析器会自动尝试其他端口但客户端不一定能收到新端口信息所以生产环境最好显式指定端口。3.3 环境检查关掉浏览器再谈性能Tracy 纳秒级的时间戳来自rdtsc这类硬件计时机制但计时精度只是开始真正影响数据可信度的是 CPU 的动态行为。现代处理器有睿频加速、节能降频、同步多线程这些都会让测量结果出现波动。想拿到稳定的数据第一步是关闭同一台机器上非必要的程序——浏览器、音乐播放器、即时通讯工具、Steam 后台进程都会抢 CPU 资源哪怕只是偶尔抢一下也会在你的帧时间图表上留下一条莫名其妙的尖刺。如果开着上下文切换捕获这些干扰会直接显示在时间线上让你看到是谁抢占了你的线程。这就是 Tracy 的哲学它展示的是硬件真实行为不是理想化的执行过程。如果你分析的是超线程机器最可靠的做法是把所有物理核心资源都留给程序的一个线程否则你测的不是代码的性能而是两个线程在同一个物理核心上互相干扰的结果。睿频更是玄学能不能跑到最高频率取决于核心数、指令类型、散热方案、硅晶彩票运气这些东西不是你能脚本化的但从分析角度就是要保持环境一致性让对比有意义。4. 客户端标记进阶锁、内存、GPU 与调用栈怎么标记才不白采4.1 锁与等待把锁竞争可视化性能问题里有一类特别难定位的是锁竞争函数本身执行很快但大量时间花在等待其他线程释放锁上。Tracy 的锁标记只需要两行#include tracy/Tracy.hpp std::mutex m_mutex; { TracyLockable(std::mutex, m_mutex); // 声明一个可分析的锁 }TracyLockable把普通std::mutex替换为带插桩的版本Tracy 能记录每次加锁的等待时间、持锁时间、锁被谁持有。在等待栈窗口里你还能看到线程在等待锁时具体停在了哪个调用栈上。这个功能对排查“程序偶尔卡一下但函数耗时图看不出问题”的场景特别有效因为锁等待往往不会出现在插桩函数的自身耗时里却会真实反映在帧时间上。4.2 内存分析按池子追踪分配Tracy 的内存分析默认会记录malloc、free、realloc的调用但你也可以把分配归到自定义的内存池里这样能区分常驻内存和临时缓冲。启用内存分析的关键是定义TRACY_MEMORY_USAGE宏然后包装你的分配器调用#include tracy/Tracy.hpp void* p tracy::Profiler::Alloc(size); // 使用 p... tracy::Profiler::Free(p);如果你用的是自定义内存池可以调用TracyAlloc和TracyFree给每个池子起一个名字Tracy 会单独统计每个池子的分配趋势。内存窗口里能看到所有活动的分配、每个分配所在的调用栈、内存随时间的变化曲线点击分配条目还能跳到对应的调用栈树。这比手动排查内存泄漏强得多按池子归组后哪一块内存在持续增长一目了然。4.3 GPU 分析CPU 和 GPU 的时间线对齐GPU 分析在 Tracy 里不是一个独立窗口而是把 GPU 区域嵌入 CPU 的时间线。原理是客户端记录 GPU 命令队列的开始和结束事件服务端把时间戳对齐到 CPU 时间线。以 Vulkan 为例需要先初始化tracy::VkCtx#include tracy/TracyVulkan.hpp // 在初始化 Vulkan 后创建上下文 auto ctx tracy::VkCtx::Create( physicalDevice, device, queueFamily, commandBuffer ); // 在每一帧提交命令缓冲区前标记 { auto scope ctx-ScopeStart(GPU Frame); // 提交渲染命令... ctx-ScopeEnd(); }Tracy 支持 OpenGL、Vulkan、Direct3D 11/12、Metal、OpenCL、CUDA。关键在于 GPU 区域和 CPU 区域共享一条时间线你可以直观地看到渲染提交是否提前或延后CPU 是否在等待 GPU 同步。如果你发现 GPU 区域很长而 CPU 区域很短说明 CPU 提前把命令都提交了但 GPU 负载过重反过来就是 CPU 在喂不饱 GPU。4.4 调用栈与调试符号采样分析的数据基石Tracy 的采样分析器依赖调用栈采集而调用栈要变成可读的函数名和源码行必须有调试符号。Windows 上要用 dbghelp 库但是有个坑Tracy 默认的栈采样不能禁用内联帧解析如果你用了最新的 MSVC 编译选项内联函数可能不会被折叠进调用栈统计导致火焰图看起来碎片化。在 Linux 上要确保编译时带调试信息但不能 strip 掉符号否则你在火焰图里看到的全是地址。采样分析是“无桩分析”的兜底方案你可以在任何代码上启用不用加任何插桩然后通过栈统计找到热点再回到代码里加ZoneScoped精确定位。4.5 脚本语言入口C API、Lua、PythonTracy 的 C API 是给所有非 C 语言用的。这些 API 不在Tracy.hpp里而是独立的tracy/TracyC.h核心函数包括___tracy_emit_zone_begin和___tracy_emit_zone_end。因为 C API 是纯函数调用Lua、Python、Fortran 甚至 Rust 都能通过标准 FFI 绑定。官方已经内置了 Lua 绑定Python 有第三方的tracy包Fortran 也有了一层封装。实际使用脚本语言时最需要注意的是区域的生命周期管理脚本里你不一定保证每个区域都配对一个结束调用丢掉任何一个都会导致时间线错乱。Tracy 的 C API 提供了___tracy_emit_zone_begin时返回的上下文数据结构要保存下来用于后续的结束调用和颜色设置。如果你写的是跨语言的桥接层建议用一个薄封装把开始和结束自动配对比如在 Python 里用with语法而不是手动调两个 API。5. 常见坑与排查为什么连不上、数据对不上、时间线是空的5.1 集成了却没数据检查宏是否全局生效现象编译通过程序正常跑服务端也能连上但时间线是空白的一个区域、一个帧标记都没有。原因TRACY_ENABLE没有被全局定义。最常见的错误是在某个源文件里#define TRACY_ENABLE这个宏只在那个文件生效或者用了TRACY_ENABLED这个不存在的变体再或者给宏赋了值TRACY_ENABLE0。解决在编译器全局定义里加TRACY_ENABLE或者用 CMake 的add_compile_definitions(TRACY_ENABLE)。别把它当布尔值Tracy 只检查宏是否存在赋值无效。5.2 静态库链接后被裁剪采样分析全空但插桩区域正常现象插桩区域能显示但服务端完全看不到采样调用栈或者Connect之后就收到极少量的调用栈数据。原因Tracy 编译成了静态库链接器发现你的代码没直接引用 Tracy 公开符号因为调用栈采样不需要手动插桩把整个库裁剪掉了。解决在主程序里强制引用一次最简单是加一行TracyNoop;确保链接器拉入TracyClient.cpp里所有实现。5.3 多 DLL 宏不一致无警告、无错误的随机崩溃现象DLL 项目运行时随机崩溃、冻结没有任何 Tracy 相关报错崩溃点在很底层的内存操作上。原因不同 DLL 编译时使用了不同的 Tracy 功能宏集。比如一个 DLL 定义了TRACY_ON_DEMAND另一个没定义两个 DLL 里的 Tracy 对象结构和状态逻辑不一致导致数据交互错乱。解决把宏定义集抽到一个共享的构建配置里所有 DLL 必须用同一组宏。如果 DLL 是单独加载的考虑用TRACY_DELAYED_INIT加TRACY_MANUAL_LIFETIME规避静态初始化顺序问题。5.4 虚拟机里时间戳精度崩坏现象分析结果明显异常函数耗时比裸机高一个数量级或者客户端直接报错“CPU 不支持 RDTSC 指令 / 不变 TSC”。原因虚拟机环境下硬件计时器被虚拟化时间戳精度下降调用栈采样频率也会降低。解决不要在 VM 里做性能分析对比。Windows 虚拟机如果必须要用可用TRACY_TIMER_QPC宏强制走 QueryPerformanceCounter但时间分辨率会明显下降只能做粗略统计。Linux 容器也一样Docker 需要加--privileged、挂载/sys/kernel/debug、设置--pidhost才有完整的采样权限。5.5 Android 8.0 起 /proc 被锁现象Android 设备上打开上下文切换捕获后数据为空系统 CPU 使用率也读不到。原因Android 8.0 之后禁止访问/proc文件系统系统 CPU 统计和上下文切换捕获都依赖/proc。解决root 设备后在 shell 里执行setenforce 0、mount -o remount,hidepid0 /proc、echo -1 /proc/sys/kernel/perf_event_paranoid、echo 0 /proc/sys/kernel/kptr_restrict。如果不 root就只能放弃这些功能改用纯插桩数据。5.6 服务端连不上但能看到广播网络层被拦截现象客户端在广播列表里可见点击Connect后一直重连或者超时。原因广播走 UDP是单向的能看到广播说明客户端活着但数据连接走 TCP 8086 端口很可能被防火墙或杀毒软件拦截了。解决确认防火墙放行 8086 端口或者临时关掉杀毒软件拦截规则。如果客户端和服务端在不同机器还要确认监听地址不是只绑 localhost必要时用TRACY_PORT换一个端口。6. 进阶与分析验证把 CSV 导出、外部数据导入和跟踪对比用起来6.1 CSV 导出与应用Tracy 的统计窗口里区域统计可以导出成 CSV。选中某个分析区域后统计窗口会列出它的耗时分布、调用次数、总耗时、平均耗时、分位数等信息。导出 CSV 后我习惯用 Python pandas 做二次分析把关键函数在一帧内的耗时波动画成箱线图比在 GUI 里翻时间线更直观import pandas as pd df pd.read_csv(zone_stats.csv) worst df.nlargest(10, total_time_ns) print(worst[[zone_name, count, total_time_ns, avg_time_ns]])CSV 导出的价值不在导出本身而在于能和其他分析脚本联动。你可以写一个持续集成脚本在每次性能基准测试后自动导出 CSV把超过阈值的函数和提交号关联起来直接在代码评审里发出去。这比每次手动打开 GUI 截图要可靠得多。6.2 与其他分析器的数据互通Tracy 支持导入外部性能分析数据这在我维护一个混合开发的项目时帮了大忙。项目里有一部分代码是跑在设备上的专用环境没法直接装 Tracy我用另一个轻量采样器采集数据后导入 Tracy 统一分析。导入时要特别注意时间单位的换算外部数据通常是毫秒或微秒Tracy 内部是纳秒对不上就会看到所有区域都缩成一个点。导入前先做一个一秒钟的简单测试确认缩放比例正确再导入正式数据。6.3 跟踪对比与源码视图Tracy 的跟踪比较窗口可以加载两次捕获结果自动对齐并高亮差异区域。我常用的场景是优化前后各跑一次同样的操作集然后用对比窗口看哪个区域变快了、哪个区域反而变慢了一目了然。还有一个值得提的是源码到汇编映射视图在符号视图里切到混合模式能看到每条汇编指令对应的源码行和执行开销。这个功能在核对外层函数为什么耗时集中时特别好用比你在汇编文件里盲猜靠谱得多。打开源码视图前确保编译时带了足够完整的调试信息并且没开启内联帧解析的折叠选项否则看到的指令开销映射会错位。从那以后我每次做性能优化抽查都会强制走一遍完整流程先跑一次捕获导出 CSV再跑一次调整后的版本对比跟踪窗口最后用混合模式源码视图确认关键指令。这套流程下来基本能杜绝那种“凭感觉优化结果翻车返工”的循环希望帮到你。本文还有配套的精品资源点击获取