OBS Studio libobs 性能剖析器（Profiler）API 全解：从 profile_start 到 CSV 快照导出

本文基于 OBS Studio 仓库中的官方 API 参考文档 reference-libobs-util-profiler.rst 展开，系统讲解 libobs 内置性能剖析器（profiler）的完整 API：剖析节点的注册与启停、快照（snapshot）的数据结构与统计语义、名称存储（name store）机制，以及如何把剖析结果导出为 CSV/GZIP 文件。读完本文，你将能够在自己的 OBS 插件或前端代码中正确埋点剖析节点、在程序退出时打印性能报告，并理解 OBS 自身在主程序与 libobs 各线程中实际使用这套 API 的方式。

1. 剖析器的定位与核心数据结构

OBS Studio 的 libobs 是一个跨平台的音视频采集/渲染/编码核心库。由于图形线程（graphics thread）需要以固定间隔逐帧驱动渲染，任何环节的耗时超标都会直接表现为掉帧，因此 libobs 自带一套低开销的层级式剖析器。参考文档开篇即点明其用途：

The profiler is used to get information about program performance and efficiency.

剖析器的数据模型是一棵以根节点为顶层的树：调用 profile_register_root 注册根节点后，用 profile_start / profile_end 成对记录各层子节点的耗时。API 声明全部位于 profiler.h，实现在 profiler.c，头文件用法为：

#include <util/profiler.h>

文档中声明了四个对外类型（见 profiler.h 第 10–12 行与第 38、62 行）：

类型	作用	说明
profiler_snapshot_t	剖析快照	内部持有全部根节点的 DARRAY，是导出 CSV 与遍历结果的入口
profiler_snapshot_entry_t	快照条目	对应剖析树中的一个节点：名称、耗时直方图、min/max、子节点数组
profiler_name_store_t	名称存储	线程安全地缓存格式化后的节点名，避免重复分配字符串
profiler_time_entry_t	时间直方图条目	只有两个字段：uint64_t time_delta（微秒）与 uint64_t count（出现次数）

其中 profiler_time_entry 结构定义在 profiler.h：

struct profiler_time_entry {
    uint64_t time_delta;
    uint64_t count;
};

这正是剖析器"低开销"的关键设计：它不记录每一次调用的原始耗时，而是把 (耗时, 次数) 聚合进一张哈希直方图（profiler.c 的 add_hashmap_entry 采用线性探测、负载因子超过 0.7 时翻倍扩容），因此内存占用与调用次数无关，只与"不同耗时桶的数量"相关。

2. 剖析控制函数：profiler_start / stop / print / free

这组函数控制整个剖析器的生命周期（实现见 profiler.c）：

• profiler_start(void)：把全局 enabled 标志置为 true，此后所有 profile_start 埋点才开始生效。
• profiler_stop(void)：置回 false，埋点静默。
• profiler_print(profiler_snapshot_t *snap)：创建一个剖析快照并保存到 *snap，同时把统计结果以人类可读的缩进树形式打印到日志。从源码看（profiler.c），snap 传 NULL 时会自动创建并在函数结束时释放；每个节点输出形如 min=…, median=…, max=…, 99th percentile=…（单位换算见 G_MS 宏，内部按微秒统计、除以 1000 显示为 ms）。
• profiler_print_time_between_calls(profiler_snapshot_t *snap)：只打印"相邻两次调用之间的间隔"统计。仅对设置了 expected_time_between_calls 的节点有意义，用于检验线程是否按预期节奏运行，例如 60 fps 对应 16.67 ms 的帧间隔，输出会给出落在 ±2% 区间内的百分比（profiler.c 的 profile_print_entry_expected）。
• profiler_free(void)：释放全部根节点、直方图与互斥量，剖析器不可再使用（profiler.c）。

OBS 主程序的实际用法非常典型，见 obs-main.cpp：

static auto ProfilerFree = [](void *) {
    profiler_stop();

    auto snap = GetSnapshot();

    profiler_print(snap.get());
    profiler_print_time_between_calls(snap.get());

    SaveProfilerData(snap);

    profiler_free();
};

static int run_program(fstream &logFile, int argc, char *argv[])
{
    ...
    std::unique_ptr<void, decltype(ProfilerFree)> prof_release(
        static_cast<void *>(&ProfilerFree), ProfilerFree);

    profiler_start();
    profile_register_root(run_program_init, 0);

    ScopeProfiler prof{run_program_init};
    ...
}

要点：用 std::unique_ptr 的自定义删除器保证无论以何种方式退出都执行清理——先 profiler_stop，再取快照、打印两份报告、落盘，最后 profiler_free。此外 SaveProfilerData 会把快照写成 GZIP 压缩的 CSV，路径为配置目录下 obs-studio/profiler_data/<日志名>.csv.gz（obs-main.cpp），这正是排查掉帧问题时可在日志包中找到的剖析数据文件。

3. 剖析埋点函数：注册根节点与 start/end 配对

3.1 profile_register_root：登记根节点与预期节奏

EXPORT void profile_register_root(const char *name, uint64_t expected_time_between_calls);

• name：根节点名称，需以 const char * 长期存活；
• expected_time_between_calls：两次调用该根节点的预期时间间隔，单位为纳秒，无预期则传 0。注意 profiler.c 内部会将其换算为微秒存储（(expected_time_between_calls + 500) / 1000）。

expected_time_between_calls 的作用是让剖析器额外维护一份"调用间隔"直方图，从而在 profiler_print_time_between_calls 中检查线程节奏是否稳定。OBS 中所有周期性线程都登记了这个值：

• 图形线程（obs-video.c）：

const uint64_t interval = obs->video.video_frame_interval_ns;
...
const char *video_thread_name =
    profile_store_name(obs_get_profiler_name_store(),
                       "obs_graphics_thread(%g" NBSP "ms)", interval / 1000000.);
profile_register_root(video_thread_name, interval);

其中 video_frame_interval_ns 由输出帧率决定（如 60 fps 即 16666667 ns），根节点名中直接嵌入了换算后的毫秒数，一眼就能看出该线程目标帧率。

• 热键线程（obs-hotkey.c）：profile_register_root(hotkey_thread_name, (uint64_t)25000000);，即 25 ms 周期；
• GPU 编码线程（obs-video-gpu-encode.c）：profile_register_root(gpu_encode_thread_name, interval);；
• 而一次性初始化流程（如 obs-main.cpp 的 run_program_init）则传 0。

3.2 profile_start / profile_end：成对埋点

EXPORT void profile_start(const char *name);
EXPORT void profile_end(const char *name);

profile_start 把新节点挂为当前线程最近一次 start 节点的子节点（文档原文："This profile node will be a child of the last node that was started"），并通过线程本地存储（THREAD_LOCAL profile_call *thread_context）维护一棵每线程独立的调用栈（profiler.c）。profile_end 弹栈并记录结束时间戳；若与栈顶名称不匹配，会向上回退关闭直至对齐，并向日志输出错误（profiler.c）——所以埋点必须严格配对，名称也要一致。

当关闭的是根节点（call->parent 为空）时，整个线程上下文会被 merge_context 合并进全局剖析树并释放（profiler.c）；有父节点时只记录时间戳，合并延迟到根节点关闭时递归完成。这意味着一次完整"根→…→叶"的埋点结束后数据才真正落账。

3.3 C++ 辅助：ProfileScope 宏与 ScopeProfiler 类

profiler.hpp 为 C++ 代码提供了 RAII 封装：

struct ScopeProfiler {
    const char *name;
    bool enabled = true;

    ScopeProfiler(const char *name) : name(name) { profile_start(name); }
    ~ScopeProfiler() { Stop(); }
    ...
};

配合宏 ProfileScope(x) 可声明式地在作用域开头埋点、结尾自动关闭（__COUNTER__ 保证同作用域多个对象命名不冲突）。例如 obs-hotkey.c 中：

ProfileScope(hotkey_thread_name);

而 obs-main.cpp 则直接写 ScopeProfiler prof{run_program_init};。两者等价，前者更简洁，后者便于中途手动 Stop()。

3.4 profile_reenable_thread：跨线程启用剖析的安全点

文档对它的说明是：由于 profiler_start() 可能在与埋点不同的线程被调用，profile_reenable_thread() 用于指定"剖析可以在当前线程重新启用"的安全点——即循环回到根节点、且根节点当前未激活的位置。实现上它把线程本地的 thread_enabled 与全局 enabled 重新同步（profiler.c）；当全局未启用时，lock_root 会把调用线程的 thread_enabled 置为 false（profiler.c），从而在剖析器关闭期间快速短路所有埋点。

OBS 中每处长循环线程都在循环开头、根节点激活之前调用它：图形线程（obs-video.c）、视频 IO（video-io.c）、音频 IO（audio-io.c）、热键线程（obs-hotkey.c）、GPU 编码线程（obs-video-gpu-encode.c）。从源码结构看，这一约定保证了剖析器运行中开启/停止时，长生命周期线程不会持有过期的"禁用"状态。

4. 名称存储函数：profiler_name_store 与 profile_store_name

动态名称（如带帧率毫秒数的线程名）不能直接传栈上临时字符串给 profile_register_root——根节点名会长期保存在剖析树中。为此文档提供了三个函数（实现见 profiler.c）：

• profiler_name_store_t *profiler_name_store_create(void)：创建名称存储对象，内部是一个带互斥量的 DARRAY(char *)；
• profiler_name_store_free(profiler_name_store_t *store)：释放存储及其中所有字符串；
• const char *profile_store_name(profiler_name_store_t *store, const char *format, ...)：按 printf 风格格式化字符串并存入存储，返回内部持有的副本指针，带 __attribute__((format)) 编译期格式检查（profiler.h）。

OBS 在初始化时统一创建全局存储，见 obs.c：

obs->name_store = store ? store : profiler_name_store_create();

对外通过 obs.h 的 obs_get_profiler_name_store() 获取，插件埋点时也应复用该存储。典型调用如编码器线程命名（obs-encoder.c）：

profile_store_name(obs_get_profiler_name_store(), "encode(%s)", encoder->context.name);

这样即使多个同类型编码器/线程并存，名称也可区分且生命周期有保障。

5. 快照数据访问函数：创建、遍历与统计

5.1 创建与释放快照

• profile_snapshot_create(void)：创建快照，把当前所有根节点树的直方图拷贝为排序数组并计算 min/max（profiler.c）。快照与活动剖析树解耦，创建后可在剖析器已停止甚至已释放前安全遍历；
• profile_snapshot_free(profiler_snapshot_t *snap)：递归释放快照。

5.2 导出 CSV：profiler_snapshot_dump_csv / _gz

• bool profiler_snapshot_dump_csv(const profiler_snapshot_t *snap, const char *filename)：写出 CSV 文件，成功返回 true；
• bool profiler_snapshot_dump_csv_gz(...)：同样内容经 zlib gzwrite 压缩写出，Windows 下通过 gzopen_w 支持宽字符路径（profiler.c）。

CSV 表头由 profiler_snapshot_dump 固定生成（profiler.c）：

id,parent_id,name_id,parent_name_id,name,time_between_calls,time_delta_µs,count

即每行是一条 (节点, 父节点, 名称, 耗时分布) 记录：普通耗时行的 time_between_calls 列为 0，调用间隔行的 time_delta_µs 列记录间隔、首列记录预期间隔。用电子表格或脚本按 name 聚合即可复现日志中的 min/median/99th percentile 统计（对应 gather_stats 的分位数算法，profiler.c）。主程序退出时的 SaveProfilerData 使用的就是 GZIP 版本（obs-main.cpp）。

5.3 枚举与过滤

• profiler_snapshot_num_roots(profiler_snapshot_t *snap)：快照中根节点数量；
• profiler_snapshot_enumerate_roots(snap, func, context)：回调遍历根节点，回调返回 false 即停止枚举；
• profiler_snapshot_filter_roots(snap, func, data)：按名称过滤根节点。回调签名 bool (*profiler_name_filter_func)(void *data, const char *name, bool *remove) 通过输出参数 *remove 决定该根是否被摘除（被移除的条目会一并释放，profiler.c）——适合"只关心某几个线程"的场景；
• profiler_snapshot_num_children(entry) / profiler_snapshot_enumerate_children(entry, func, context)：对单个条目做同构的子节点遍历。

两个回调类型（profiler_entry_enum_func、profiler_name_filter_func）均声明于 profiler.h。

5.4 单条目统计访问器

以下函数均直接读快照条目字段，entry 为空时安全返回 0/NULL（profiler.c）：

函数	返回	语义
profiler_snapshot_entry_name	const char *	节点名称
profiler_snapshot_entry_times	profiler_time_entries_t *	耗时分桶数组（已按 time_delta 升序排序，见 sort_snapshot_entry）
profiler_snapshot_entry_min_time / _max_time	uint64_t（微秒）	最小/最大单次耗时
profiler_snapshot_entry_overall_count	uint64_t	该节点累计调用次数
profiler_snapshot_entry_times_between_calls	profiler_time_entries_t *	调用间隔分桶数组
profiler_snapshot_entry_expected_time_between_calls	uint64_t	预期调用间隔，未设置则为 0
profiler_snapshot_entry_min_time_between_calls / _max_	uint64_t	观测到的最小/最大调用间隔
profiler_snapshot_entry_overall_between_calls_count	uint64_t	累计记录的调用间隔次数

6. 实践路径：从埋点到阅读报告

综合文档 API 与仓库中的实际用法，在 OBS 插件中接入剖析器可遵循以下流程：

1. 全局生命周期：程序入口 profiler_start()，退出路径 profiler_stop() → profile_snapshot_create() → profiler_print / profiler_print_time_between_calls → （可选）profiler_snapshot_dump_csv_gz → profile_snapshot_free → profiler_free()，参考 obs-main.cpp 的 ProfilerFree 模式；
2. 线程埋点：线程启动时先 profile_reenable_thread()，再通过 profile_store_name（复用 obs_get_profiler_name_store()）生成带参数的唯一名称，profile_register_root(name, expected_interval_ns) 登记根节点（周期线程传纳秒级预期间隔，一次性流程传 0）；
3. 循环埋点：热路径用 ProfileScope("...") 或成对 profile_start/profile_end，保证配对且名称一致，嵌套即成父子关系；
4. 读结果：运行期直接看日志打印树；离线分析用 obs-studio/profiler_data/ 下的 CSV.gz，按 name 聚合 time_delta_µs/count 列即可得到任意分位数；检查掉帧节奏则看 time_between_calls != 0 的行。

需要说明的适用前提：剖析耗时统计的内部存储单位为微秒、expected_time_between_calls 的入参单位为纳秒，两者在 profiler.c 的 diff_ns_to_usec 与 profile_register_root 的换算中可见；此外剖析器依赖 zlib（CSV.gz 导出与 #include <zlib.h>），构建时需有该依赖。除文档列出的 API 外，libobs 另有一套面向单个 source 渲染耗时的 profiler_result_t 接口（source-profiler.h），用于逐 source 的 CPU/GPU 渲染统计，与本文的通用剖析器属于两套互补设施，可另行查阅其头文件。