TiKV HTTP API 指南基于 Status Server 的 CPU / Heap Profiling 与符号解析实战【免费下载链接】tikvDistributed transactional key-value database, originally created to complement TiDB项目地址: https://gitcode.com/GitHub_Trending/ti/tikv导读本文基于 TiKV 仓库中的官方文档 doc/http.md系统讲解 TiKV 通过 HTTP 接口对外提供的性能剖析能力如何在任意 TiKV 实例上收集 CPU Profile、导出 Heap Profile并通过本地或远程方式将堆内存地址符号化为函数调用图。文中所有参数说明、命令示例与底层原理均与当前仓库源码状态服务位于 src/server/status_server/mod.rs、剖析实现位于 src/server/status_server/profile.rs一一对应读完你即可在真实集群上完成一次完整的性能剖析与火焰图生成。前置约定TiKV 状态服务地址本文所有 HTTP 请求都指向 TiKV 的状态服务Status Server其监听地址统一记为TIKV_ADDRESS$TIKV_IP:$TIKV_STATUS_PORT默认情况下TIKV_IP为127.0.0.1TIKV_STATUS_PORT为20180该端口由配置项status-addr控制在 etc/config-template.toml 中可以看到其默认注释值为# status-addr 127.0.0.1:20180配置模板同时给出了明确的安全提示该端口直接对外暴露存在泄漏状态信息的风险置空字符串表示完全禁用状态服务。在源码层面该配置解析于 src/server/config.rs结构体字段status_addr以及用于注册的advertise_status_addr共同决定状态服务的实际监听地址。配置校验逻辑还要求若status-addr为空而advertise-status-addr非空则报错当status-addr使用0.0.0.0等通配地址且未显式指定advertise-status-addr时会记录告警并回退使用status-addr见 src/server/config.rs。因此建议在排查时先确认status-addr已正确配置再执行下面的 curl 命令。CPU Profiling按时间窗口采集 CPU 剖析数据CPU 剖析用于在指定时间范围内持续采集并导出 CPU 使用数据请求发出后服务端立即开始采样直到超时时间到达后返回结果。curl -H Content-Type:type -X GET http://$TIKV_ADDRESS/debug/pprof/profile?secondssecondsfrequencyfrequency请求参数参数是否必填说明默认值示例seconds可选CPU 剖析数据的采集时长秒10?seconds20frequency可选CPU 剖析数据的采样频率Hz99?frequency100type请求头Content-Type可选响应体格式application/protobuf返回原始 profile 数据其他任意类型返回火焰图无N/A-H Content-Type:application/protobuf响应格式服务端返回 CPU 剖析数据其格式由请求头Content-Type决定原始 profile 数据protobuf 格式请求头指定Content-Type: application/protobuf时返回可交由pprof工具解析火焰图SVG 格式请求头为其他任何类型时返回可直接用浏览器打开的 SVG 火焰图。原始 profile 数据可用pprof工具处理例如在交互式浏览器中打开go tool pprof --http0.0.0.0:1234 xxx.proto源码级实现解读服务端对/debug/pprof/profile的路由注册见 src/server/status_server/mod.rs其参数解析逻辑与文档描述完全一致src/server/status_server/mod.rsseconds缺省为10frequency缺省为99源码注释说明 99Hz 是为了避开特殊周期如 100Hz 电网频率带来的采样干扰请求头Content-Type精确匹配application/protobuf时开启原始数据输出响应会附加Content-Disposition: attachment; filenamecpu_profile头方便浏览器直接保存文件。真正的采样工作由 src/server/status_server/profile.rs 中的start_one_cpu_profile完成它使用pprof库的ProfilerGuardBuilder以指定频率启动采样并通过blocklist([libc, libgcc, pthread, vdso])过滤底层运行时符号以减小噪声采样结束后protobuf 模式通过report.pprof()生成标准 pprof 数据火焰图模式则通过report.flamegraph()直接输出 SVG。采样期间还会对线程名做归一化处理见 profile.rs 附近的extract_thread_name保证火焰图线程标签的可读性。Heap Profiling导出堆内存快照堆剖析用于导出 TiKV 进程当前的堆内存使用快照。需要特别注意的是堆剖析不同于 CPU 剖析——它不是在请求后的指定时间窗口内持续采集而是 TiKV 在堆内存使用被激活后持续累积统计请求发生时直接导出这一时刻的快照。curl -X GET http://$TIKV_ADDRESS/debug/pprof/heap?jeprofjeprof请求参数参数是否必填说明默认值示例jeprof可选是否使用 Jeprof 处理堆剖析数据以生成调用图。需要环境中安装perlfalse?jeproftrue响应格式服务端返回堆剖析数据响应格式由jeprof参数决定jeproftrue返回由jeprof生成的SVG 调用图前提是 TiKV 运行环境中安装了perljeproffalse默认返回jemalloc 专用格式的原始剖析数据。源码级实现解读堆快照的采集在 src/server/status_server/profile.rs 的dump_one_heap_profile中完成它创建临时文件并调用dump_prof落盘。jeproftrue时服务端调用 profile.rs 的jeprof_heap_profile以perl执行脚本将仓库内置的jeprof脚本src/server/status_server/jeprof.in经标准输入喂给解释器同时传入当前 TiKV 可执行文件路径与堆剖析临时文件追加--show_bytes、--svg参数生成调用图 SVG 并返回给客户端。在 src/server/status_server/mod.rs 中可以看到一组与堆剖析相关的历史接口/debug/pprof/heap_list、/debug/pprof/heap_activate、/debug/pprof/heap_deactivate均已标记为Deprecated返回提示称堆剖析默认始终开启需要时直接使用/debug/pprof/heap获取即可这也解释了为什么堆快照在请求时立即可得——统计一直在后台累积。Heap Profile Symbolization堆剖析数据的符号化通过heap接口获取的堆剖析数据默认是jemalloc 专用格式的原始数据需要用jeprof处理后才能可视化。从原始数据生成 SVG 调用图有两种方式方式一本地符号化提供剖析文件路径并使用 TiKV 二进制文件本地解析符号jeprof --svg binary profile其中binary为 TiKV 可执行文件路径profile为上一步导出的堆剖析原始数据文件。方式二远程符号化直接让jeprof通过 HTTP 拉取 TiKV 最新的堆剖析数据并由 TiKV 提供的符号化服务解析符号jeprof --svg http://$TIKV_ADDRESS/debug/pprof/heap为支持远程方式TiKV 提供了符号化服务将内存地址映射为对应的函数名。jeprof会隐式调用.../debug/pprof/symbol完成调用栈地址到函数名的转换绝大多数场景下无需手动调用。如果你有其它用途需要显式使用该接口可参考curl -X POST -d address_list http://$TIKV_ADDRESS/debug/pprof/symbol请求参数参数是否必填说明address_list必填待解析的内存地址列表以十六进制格式给出是否带0x前缀均可多个地址之间用字符分隔响应格式返回纯文本格式的已解析符号列表每一行表示一个十六进制地址及其对应的函数名若某个内存地址无法解析则标记为??。源码级实现解读符号化服务的路由在 src/server/status_server/mod.rsGET /debug/pprof/symbol返回符号数量计数实现为固定的num_symbols: 1见 mod.rs该接口遵循 pprof 远程服务器协议仅用于告知客户端存在可用的符号信息POST /debug/pprof/symbol真正的地址解析源码注释mod.rs明确说明其请求/响应格式遵循 pprof 远程服务器规范并使用addr2line解析地址每行输出一个符号若函数被内联则可能输出多个符号。仓库自带的集成测试完整覆盖了这三类剖析服务src/server/status_server/mod.rstest_pprof_heap_service请求/debug/pprof/heap?seconds1断言返回内容非空test_pprof_profile_service请求/debug/pprof/profile?seconds1frequency99验证默认频率下的 CPU 剖析请求可正常返回test_pprof_symbol_service先POST地址列表到/debug/pprof/symbol再断言解析结果中包含当前测试函数名test_pprof_symbol_service——这条断言恰好验证了地址到函数名的完整解析链路。典型排查流程小结确认status-addr已配置默认127.0.0.1:20180否则先通过配置模板 etc/config-template.toml 调整并重启 TiKV排查 CPU 热点执行curl http://$TIKV_ADDRESS/debug/pprof/profile?seconds30 cpu.proto或直接指定Content-Type: application/protobuf再用go tool pprof --http0.0.0.0:1234 cpu.proto在浏览器中交互分析排查内存占用执行curl http://$TIKV_ADDRESS/debug/pprof/heap heap.prof获取原始快照随后在本机执行jeprof --svg tikv-binary heap.prof生成调用图若 TiKV 环境已安装perl也可直接请求?jeproftrue一步到位需要自动化脚本将地址映射为函数时直接POST /debug/pprof/symbol调用符号化服务即可。【免费下载链接】tikvDistributed transactional key-value database, originally created to complement TiDB项目地址: https://gitcode.com/GitHub_Trending/ti/tikv创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考