C++ Remote Profiler

目录

📋 版本说明

当前版本: v0.1.0

版本检查

#include "version.h"
#if REMOTE_PROFILER_VERSION_AT_LEAST(0, 2, 0)
 // 使用新 API
#else
 // 使用旧 API
#endif

🎯 功能特性

🎯 设计理念

🚀 快速开始

前置要求

1. 安装系统依赖

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install -y \
 cmake \
 build-essential \
 git \
 pkg-config \
 graphviz \
 libgoogle-perftools-dev

# Fedora/RHEL/CentOS
sudo dnf install -y \
 cmake \
 gcc-c++ \
 make \
 git \
 pkg-config \
 graphviz \
 gperftools-devel

2. 初始化 vcpkg

# 克隆项目(如果还没有)
git clone <your-repo-url>
cd cpp-remote-profiler
# 如果 vcpkg 目录不存在,初始化它
if [ ! -d "vcpkg" ]; then
 git clone https://github.com/Microsoft/vcpkg.git
 cd vcpkg
 ./bootstrap-vcpkg.sh
 cd ..
fi

3. 安装 vcpkg 依赖

cd vcpkg
./vcpkg install --triplet=x64-linux-release

4. 编译项目

./build.sh

mkdir build && cd build
cmake .. \
 -DCMAKE_BUILD_TYPE=Release \
 -DCMAKE_TOOLCHAIN_FILE=../vcpkg/scripts/buildsystems/vcpkg.cmake \
 -DVCPKG_TARGET_TRIPLET=x64-linux-release
make -j$(nproc)

⚙️ CMake 构建选项

选项列表

常见构建场景

cmake .. \
 -DCMAKE_BUILD_TYPE=Release \
 -DCMAKE_TOOLCHAIN_FILE=../vcpkg/scripts/buildsystems/vcpkg.cmake \
 -DVCPKG_TARGET_TRIPLET=x64-linux-release

cmake .. \
 -DCMAKE_BUILD_TYPE=Release \
 -DCMAKE_TOOLCHAIN_FILE=../vcpkg/scripts/buildsystems/vcpkg.cmake \
 -DVCPKG_TARGET_TRIPLET=x64-linux-release \
 -DREMOTE_PROFILER_ENABLE_WEB=OFF \
 -DREMOTE_PROFILER_BUILD_EXAMPLES=OFF \
 -DREMOTE_PROFILER_BUILD_TESTS=OFF

cmake .. \
 -DCMAKE_BUILD_TYPE=Release \
 -DCMAKE_TOOLCHAIN_FILE=../vcpkg/scripts/buildsystems/vcpkg.cmake \
 -DVCPKG_TARGET_TRIPLET=x64-linux-release \
 -DREMOTE_PROFILER_ENABLE_WEB=OFF \
 -DREMOTE_PROFILER_BUILD_EXAMPLES=OFF \
 -DREMOTE_PROFILER_BUILD_TESTS=OFF \
 -DBUILD_SHARED_LIBS=OFF

cmake .. \
 -DCMAKE_BUILD_TYPE=Release \
 -DCMAKE_TOOLCHAIN_FILE=../vcpkg/scripts/buildsystems/vcpkg.cmake \
 -DVCPKG_TARGET_TRIPLET=x64-linux-release \
 -DBUILD_DOCS=ON

📦 安装

# 安装到默认路径(通常为 /usr/local)
cmake --install build
# 安装到指定路径
cmake --install build --prefix /opt/cpp-remote-profiler

<prefix>/
├── include/cpp-remote-profiler/ # 头文件
│ ├── profiler_manager.h
│ ├── profiler_version.h
│ ├── version.h
│ └── profiler/
│ ├── http_handlers.h
│ └── log_sink.h
├── lib/
│ ├── libprofiler_core.so # 核心库
│ ├── libprofiler_web.so # Web 库(如果启用)
│ └── cmake/cpp-remote-profiler/ # CMake 配置文件
│ ├── cpp-remote-profiler-config.cmake
│ ├── cpp-remote-profiler-config-version.cmake
│ └── cpp-remote-profiler-targets.cmake
└── share/doc/cpp-remote-profiler/ # 文档(如果启用 BUILD_DOCS)

5. 运行服务

./start.sh

cd build
./profiler_example

📖 使用方法

方法 1: 使用 Go pprof 工具(推荐)

# CPU 采样 10 秒
go tool pprof http://localhost:8080/pprof/profile?seconds=10
# 或者先下载 profile 文件
curl http://localhost:8080/pprof/profile?seconds=10 > cpu.prof
go tool pprof -http=:8081 cpu.prof
# Heap profile(需要先设置环境变量)
curl http://localhost:8080/pprof/heap > heap.prof
go tool pprof -http=:8081 heap.prof

方法 2: 通过 Web 界面(快速查看)

方法 3: 通过 API 获取 SVG

# CPU 火焰图
curl http://localhost:8080/api/cpu/analyze?duration=10
# Heap 火焰图
curl http://localhost:8080/api/heap/analyze?duration=10

📊 如何查看火焰图

方法 1: 使用内置 Web 界面(最简单)

方法 2: 使用 Go pprof 工具(功能强大)

# 安装 Go
wget https://go.dev/dl/go1.21.5.linux-amd64.tar.gz
sudo tar -C /usr/local -xzf go1.21.5.linux-amd64.tar.gz
export PATH=$PATH:/usr/local/go/bin
# 安装 pprof
go install github.com/google/pprof@latest

# 直接从 URL 分析
go tool pprof -http=:8081 http://localhost:8080/pprof/profile?seconds=10
# 或者先下载
curl http://localhost:8080/pprof/profile?seconds=10 > cpu.prof
go tool pprof -http=:8081 cpu.prof

方法 3: 使用 Speedscope

🔧 API 端点

使用示例

# CPU profile(返回原始文件,用于 pprof 工具)
curl http://localhost:8080/pprof/profile?seconds=10 > cpu.prof
# Heap profile(返回原始文件,用于 pprof 工具)
# 注意:需要设置 TCMALLOC_SAMPLE_PARAMETER 环境变量
curl http://localhost:8080/pprof/heap > heap.prof
# Heap growth stacks(返回调用堆栈)
curl http://localhost:8080/pprof/growth
# CPU 火焰图(返回 SVG,浏览器可直接显示)
curl http://localhost:8080/api/cpu/analyze?duration=10
# Heap 火焰图(返回 SVG,浏览器可直接显示)
curl http://localhost:8080/api/heap/analyze?duration=10
# 获取所有线程的调用堆栈
curl http://localhost:8080/api/thread/stacks

📁 项目结构

cpp-remote-profiler/
├── CMakeLists.txt # 构建配置
├── README.md # 项目文档
├── build.sh # 构建脚本
├── start.sh # 启动脚本
├── include/
│ ├── profiler_manager.h # Profiler 管理器(非单例)
│ ├── profiler_version.h.in # 版本信息模板(CMake 生成)
│ ├── version.h # 版本宏(向后兼容)
│ └── profiler/
│ ├── http_handlers.h # 框架无关的 HTTP 处理器
│ ├── drogon_adapter.h # Drogon 适配层(可选)
│ └── log_sink.h # 日志 Sink 接口
├── src/
│ ├── profiler_manager.cpp # Profiler 管理器实现
│ ├── symbolize.cpp # 符号化引擎
│ ├── http_handlers.cpp # HTTP 处理器实现(框架无关)
│ ├── drogon_adapter.cpp # Drogon 适配层实现(可选)
│ ├── web_resources.cpp # 嵌入的 Web 资源
│ └── internal/ # 内部实现(不对外暴露)
│ ├── log_manager.h/cpp # 日志管理器
│ ├── default_log_sink.h/cpp # 默认日志实现(std::cout/cerr)
│ ├── log_macros.h # 内部日志宏
│ └── ... # 其他内部头文件
├── example/
│ ├── main.cpp # 示例程序主入口
│ ├── workload.cpp # 工作负载示例
│ ├── workload.h
│ └── custom_signal.cpp # 自定义信号示例
├── tests/
│ ├── test_cpu_profile.cpp # CPU profiling 测试
│ ├── test_full_flow.cpp # 完整流程测试
│ └── test_logger.cpp # 日志系统测试
├── docs/ # 用户文档
│ ├── README.md # 文档索引
│ └── user_guide/ # 用户指南
│ ├── 01_quick_start.md
│ ├── 02_api_reference.md
│ ├── 03_integration_examples.md
│ ├── 04_troubleshooting.md
│ ├── 05_installation.md
│ └── 06_using_find_package.md
├── scripts/
│ └── check-format.sh # 代码格式检查脚本
└── vcpkg/ # vcpkg 包管理器

🧪 运行测试

cd build
ctest --output-on-failure
# 或单独运行:
./test_cpu_profile
./test_full_flow
./test_logger

# 确保服务正在运行
./start.sh
# 在浏览器访问
http://localhost:8080

🎨 代码格式检查

检查代码格式

./scripts/check-format.sh

自动格式化代码

./scripts/check-format.sh --fix

格式检查范围

CI 集成

💡 集成到你的项目

选项 1: 仅使用核心 profiling 功能(无 Web 依赖)

find_package(cpp-remote-profiler REQUIRED)
target_link_libraries(my_app cpp-remote-profiler::profiler_core)

#include "profiler_manager.h"
int main() {
 profiler::ProfilerManager profiler;
 // 启动 CPU profiling
 profiler.startCPUProfiler("cpu.prof");
 // ... 运行你的代码 ...
 profiler.stopCPUProfiler();
 return 0;
}

选项 2: 使用 Drogon Web 界面(推荐)

find_package(cpp-remote-profiler REQUIRED)
find_package(Drogon CONFIG REQUIRED)
target_link_libraries(my_app
 cpp-remote-profiler::profiler_web
 Drogon::Drogon
)

#include "profiler_manager.h"
#include "profiler/drogon_adapter.h"
#include <drogon/drogon.h>
int main() {
 profiler::ProfilerManager profiler;
 profiler::registerDrogonHandlers(profiler);
 drogon::app().addListener("0.0.0.0", 8080).run();
}

选项 3: 与任意 Web 框架集成

#include "profiler_manager.h"
#include "profiler/http_handlers.h"
profiler::ProfilerManager profiler;
profiler::ProfilerHttpHandlers handlers(profiler);
// 调用 handler,获得框架无关的响应
auto resp = handlers.handleCpuAnalyze(10, "flamegraph");
// resp.status, resp.content_type, resp.body → 用你的框架包装

配置信号(可选)

#include "profiler_manager.h"
int main() {
 // 在创建 ProfilerManager 之前设置信号
 profiler::ProfilerManager::setStackCaptureSignal(SIGRTMIN + 5);
 profiler::ProfilerManager profiler;
 // ... 正常使用 profiler ...
}

配置日志(可选)

#include "profiler_manager.h"
#include "profiler/log_sink.h"
class MyAppLogSink : public profiler::LogSink {
public:
 void log(profiler::LogLevel level, const char* file, int line,
 const char* function, const char* message) override {
 // 转发到你的日志系统
 MY_APP_LOG("[Profiler] {}:{} - {}", file, line, message);
 }
};
int main() {
 profiler::ProfilerManager profiler;
 profiler.setLogSink(std::make_shared<MyAppLogSink>());
 profiler.setLogLevel(profiler::LogLevel::Debug);
 // ... 正常使用 profiler ...
}

⚙️ 配置说明

环境变量

vcpkg 依赖版本

cd vcpkg
./vcpkg upgrade --triplet=x64-linux-release

⚠️ 注意事项

🎨 与其他工具的对比

📝 许可证

🤝 贡献

📞 联系方式