Tracy 是一款专为游戏和性能敏感型应用设计的实时、纳秒级分辨率、远程遥测混合帧分析器

Tracy 是一款专为游戏和性能敏感型应用设计的实时、纳秒级分辨率、远程遥测混合帧分析器。它支持CPU、GPU、内存分配、锁、上下文切换等多维度性能分析，并允许在应用运行时远程连接，实时查看性能数据，被誉为“RAD Telemetry 与 Intel VTune 的结合体，且功能更强大”。

本教程将指导你完成Tracy的完整部署，包括服务端获取、客户端集成与使用。

一、Tracy 的核心架构

在开始前，理解其架构有助于后续操作：

客户端 (Client)：即被你进行性能分析的应用。你需要在其代码中集成Tracy的客户端库，并在编译时启用。
服务端 (Server)：即 tracy-profiler 图形界面程序，用于连接客户端，实时接收、显示和分析性能数据。

两者通过网络（默认TCP端口8086）进行通信。

二、部署步骤

步骤 1：获取 Tracy 服务端 (tracy-profiler)

首先，你需要获得用于查看性能数据的图形界面程序。

方式一：使用包管理器安装（推荐）
这是最简单的方式，适用于多数操作系统。

操作系统	包管理器	命令
macOS	Homebrew	`brew install tracy`
Linux	Nix	`nix profile install nixpkgs#tracy`
Windows	Scoop	`scoop install extras/tracy`
Windows	Winget	`winget install --id wolfpld.tracy -e`

方式二：下载预编译二进制文件 (Windows)
访问 Tracy GitHub Releases 页面，下载最新版本的 Tracy-<version>.7z 压缩包，解压后即可得到 tracy-profiler.exe 等工具。

方式三：从源代码编译 (Linux / macOS)
如果需要自定义或包管理器不可用，可从源码编译：

bash

# 1. 克隆指定版本的源码（例如 v0.13.0）
git clone -b v0.13.0 --single-branch https://github.com/wolfpld/tracy.git
cd tracy

# 2. 使用 CMake 编译服务端
# 注意：在 Linux 下如果使用 X11，需要添加 -DLEGACY=1
cmake -B profiler/build -S profiler -DCMAKE_BUILD_TYPE=Release
cmake --build profiler/build --config Release --parallel

# 3. 编译完成后，可执行文件位于：
# ./profiler/build/tracy-profiler  (Linux/macOS)
# ./profiler/build/tracy-profiler.exe (Windows)

步骤 2：在你的项目中集成 Tracy 客户端

要让Tracy能够分析你的程序，需要将Tracy的客户端代码集成到项目中。

1. 添加客户端文件
将 tracy/public 目录下的所有文件（主要是 tracy/Tracy.hpp 和相关头文件）复制到你的项目源码目录中。

2. 包含头文件
在你需要加入性能分析功能的源文件中包含主头文件：

cpp

1	#include "tracy/Tracy.hpp"

3. 定义框架标记 (Frame Mark)
Tracy以“帧”（Frame）为基本分析单元。在你的主循环（如游戏循环或事件循环）的每一帧末尾，调用 FrameMark 宏：

cpp

while (true) {
    // ... 你的帧逻辑 ...
    FrameMark; // 标记当前帧结束
}

4. 标记分析区 (Zone)
在你的关键函数内部，可以使用 ZoneScoped 宏来标记一段需要详细分析的代码块（Zone）。当进入该作用域时开始计时，退出时结束：

cpp

void yourCriticalFunction() {
    ZoneScoped; // 对此函数进行性能分析
    // ... 你的函数逻辑 ...
}

你还可以用 ZoneText、ZoneColor 等宏为Zone添加元数据，便于分析。

5. 链接客户端库
根据你的构建系统，链接Tracy客户端库。

CMake项目：可以通过 add_subdirectory(tracy) 和 target_link_libraries(your_target TracyClient) 集成。
直接编译：在编译时，需要包含 public 目录，并定义 TRACY_ENABLE 宏。

步骤 3：构建与分析

1. 构建启用Tracy的应用
Tracy客户端默认是禁用的，以避免性能开销。在编译时需要显式启用：

bash

1 2	# 在编译命令中定义 TRACY_ENABLE 宏 g++ -DTRACY_ENABLE -Ipath/to/tracy/public your_source.cpp -o your_app

重要提示：请对Release优化版本（如 -O2/-O3）进行性能分析，因为Debug版本的性能特征与实际发布版本差异巨大，分析结果可能无效。

2. 启动应用与连接

首先，运行步骤1中获取的 tracy-profiler 程序。
然后，启动你已集成Tracy并构建好的应用。
在Tracy服务端界面，你应该能看到一个名为你应用进程的可连接项目，点击 “Connect” 按钮进行连接。

3. 开始分析
连接成功后，你将看到实时的性能数据流，包括：

时间线视图：直观展示各线程、各Zone的执行时间和调用关系。
帧时间直方图：显示帧耗时分布，帮助快速定位卡顿帧。
CPU数据视图：展示线程在CPU核心上的调度情况、上下文切换等。
统计窗口：提供各函数的调用总耗时、调用次数等聚合统计数据，帮助定位热点函数。

收集到足够数据后，点击 “Stop” 按钮可以保存当前追踪文件（.tracy）以便后续分析。

三、常用附加工具

Tracy安装包中附带了一些实用命令行工具：

tracy-capture：无需打开GUI，直接在命令行捕获程序性能数据并保存为 .tracy 文件。
tracy-csvexport：将 .tracy 追踪文件导出为CSV格式，便于在其他工具中进一步分析。
tracy-update：用于更新追踪文件格式。

四、关键配置选项

为了在生产环境或按需分发的应用中控制分析器行为，可以使用以下预处理器定义：

编译定义	作用
`TRACY_ENABLE`	必需。全局启用Tracy客户端。
`TRACY_ON_DEMAND`	按需模式。客户端代码仍然编译进程序，但只有当Tracy服务端主动连接时，才开始收集和发送数据，平时几乎无额外开销。这是发布版本的首选方案。
`TRACY_NO_FRAME_IMAGE`	禁用帧截图功能，可略微减少开销。
`TRACY_NO_CALLSTACK`	禁用调用栈采样，可显著减少追踪文件大小和性能开销。

五、常见问题排查

Tracy服务端列表中找不到应用进程：
- 确认应用已成功启动并运行。
- 检查应用编译时是否定义了 TRACY_ENABLE。
- 检查防火墙设置，确保端口8086未被阻止。
- 确保Tracy服务端与你的应用在同一台机器或同一局域网内。
应用运行速度变慢：
- 这是正常现象，启用性能分析本身会带来一定的性能开销。
- 仅在需要进行性能分析时编译 TRACY_ENABLE 版本，平时使用不带此宏的版本。
性能数据不完整或缺少Zone：
- 确认在需要分析的函数中正确使用了 ZoneScoped 等宏。
- 确认编译时未使用 TRACY_NO_CALLSTACK 等会限制功能的宏。