微信扫一扫README
🚀 uniprof
uniprof 简化了人类和 AI 代理的 CPU 性能分析过程。无需更改代码或添加依赖项，即可对任何应用程序进行性能分析。
# 一步完成对任何应用的性能分析和结果分析
npx uniprof python script.py
🚀 快速开始
一步完成性能分析和结果分析
# 对大多数语言进行性能分析并立即获得分析结果
uniprof python app.py
uniprof node server.js
uniprof ruby script.rb
uniprof java -jar myapp.jar
uniprof dotnet MyApp.dll
uniprof ./my-native-app
# 进行性能分析并在浏览器中可视化火焰图
uniprof --visualize python app.py
保存分析结果以便后续分析和可视化
# 1. 检查环境（可选）
uniprof bootstrap
# 2. 记录性能分析结果
uniprof record -o profile.json -- python app.py
uniprof record -o profile.json -- node server.js
uniprof record -o profile.json -- ruby script.rb
uniprof record -o profile.json -- php script.php
uniprof record -o profile.json -- java -jar myapp.jar
uniprof record -o profile.json -- ./gradlew run
uniprof record -o profile.json -- ./mvnw spring-boot:run
uniprof record -o profile.json -- dotnet MyApp.dll
uniprof record -o profile.json -- elixir script.exs
uniprof record -o profile.json -- mix run
uniprof record -o profile.json -- ./my-native-app
uniprof record -o profile.json -- /Applications/MyApp.app
# 3. 分析性能分析数据以找出热点
uniprof analyze profile.json
# 4. 在浏览器中可视化火焰图
uniprof visualize profile.json
详细的命令行选项文档请参考 docs/cli.md。
主机模式与容器模式
使用 --mode 选项来控制性能分析的运行方式：
auto（默认）：当 Docker 可用时，优先使用容器模式；否则使用主机模式。- 语言运行时（Python/Node.js/Ruby/PHP/BEAM/JVM/.NET）默认使用容器模式，无需进行额外设置。
- 在 macOS 上，使用 Mach - O 二进制文件的原生应用使用主机模式（Instruments）。macOS 上的 ELF 二进制文件支持容器模式。
- 在 Linux 上，原生应用默认使用容器模式；如果您更喜欢使用本地的 perf 设置，也可以使用主机模式。
host：强制使用主机安装的性能分析工具。container：强制使用 Docker 容器（macOS Instruments/Mach - O 二进制文件不支持）。
# 自动模式（默认）
uniprof record -o profile.json -- python script.py
# 强制使用主机性能分析工具
uniprof record --mode host -o profile.json -- python script.py
# 强制使用容器模式
uniprof record --mode container -o profile.json -- ./my-linux-app
✨ 主要特性
uniprof 在多个针对不同平台和运行时的性能分析工具之上实现了一个通用接口。它会根据执行的命令自动检测要使用的性能分析工具，运行该工具，将不同的输出格式转换为单一格式，并对数据进行统计分析以找出热点。
| 平台 | 性能分析工具 | 容器 | 主机 | 最低版本 | |------|--------------|------|------|----------| | Python | [py - spy](https://github.com/benfred/py - spy) | ✅ | ✅ | Python 3.7+ | | Node.js | 0x | ✅ | ✅ | Node 14+ | | Ruby | rbspy | ✅ | ✅ | Ruby 2.5+ | | PHP | [Excimer](https://github.com/wikimedia/mediawiki - php - excimer) | ✅ | ✅ | PHP 7.2+ | | JVM | [async - profiler](https://github.com/async - profiler/async - profiler) | ✅ | ✅ | Java 8+ | | .NET | dotnet - trace | ✅ | ✅ | .NET 5+ | | BEAM | perf | ✅ | ✅* | OTP 24+ | | 原生（macOS） | Instruments | ❌ | ✅ | Xcode 14.3+ | | 原生（Linux） | perf | ✅ | ✅ | Linux 2.6.31+ |
* 主机模式仅适用于 Linux
📦 安装指南
安装 uniprof
npm install -g uniprof
MCP 服务器
# 自动安装 uniprof MCP 服务器
uniprof mcp install claudecode
uniprof mcp install cursor
uniprof mcp install vscode
支持自动安装的客户端：amp、claudecode、codex、cursor、gemini、vscode、zed
如果您的客户端不支持自动安装，可以使用命令 npx -y uniprof mcp run 通过 stdio 传输添加 MCP 服务器。
详细的 MCP 文档请参考 docs/mcp.md。
🔧 技术细节
编译时包含调试信息
原生性能分析需要调试信息才能获得有意义的结果。调试符号使性能分析工具能够将内存地址映射到函数名，从而提供可读的输出，而不仅仅是十六进制地址。此外，帧指针可以提高调用栈的准确性，特别是对于经过优化的代码。
| 编译器 | DWARF 调试信息 | 帧指针 | 注意事项 |
|----------|------------------|----------------|-------|
| gcc | gcc -g -o myapp main.c | gcc -fno-omit-frame-pointer -o myapp main.c | 使用 -g3 以获得最大的调试信息，使用 -ggdb 以获得 GDB 特定的扩展 |
| clang | clang -g -o myapp main.cpp | clang -fno-omit-frame-pointer -o myapp main.cpp | 在 macOS 上使用 -gfull 以获得完整的调试信息 |
| swift | swiftc -g main.swift | swiftc -Xcc -fno-omit-frame-pointer main.swift | 使用 swift build 进行调试构建时，默认包含符号 |
| cargo | cargo build（调试模式）cargo build --release + [profile.release]debug = true | RUSTFLAGS="-C force-frame-pointers=yes" cargo build | 调试构建默认包含 DWARF；对于发布版本，在 Cargo.toml 中添加 debug = true |
| go | go build -gcflags=all="-N -l" | 内置，始终启用 | Go 默认包含调试信息；-gcflags 禁用优化以进行更好的调试 |
| zig | zig build-exe -O Debug main.zig | zig build-exe -fno-omit-frame-pointer main.zig | 对于带有符号的优化构建，使用 -O ReleaseSafe 并包含调试信息 |
| ghc | ghc -g -rtsopts main.hs | ghc -fno-omit-frame-pointer main.hs | 使用 -prof 进行性能分析构建；-rtsopts 启用运行时性能分析选项 |
📚 详细文档
👏 鸣谢
- [py - spy](https://github.com/benfred/py - spy)（MIT）用于 Python 性能分析。包含在 [uniprof - python](https://github.com/indragiek/uniprof/pkgs/container/uniprof - python) 镜像中。
- 0x（MIT）用于 Node.js 性能分析。包含在 [uniprof - nodejs](https://github.com/indragiek/uniprof/pkgs/container/uniprof - nodejs) 镜像中。
- rbspy（MIT）用于 Ruby 性能分析。包含在 [uniprof - ruby](https://github.com/indragiek/uniprof/pkgs/container/uniprof - ruby) 镜像中。
- Excimer（Apache 2.0）用于 PHP 性能分析。包含在 [uniprof - php](https://github.com/indragiek/uniprof/pkgs/container/uniprof - php) 镜像中。
- [async - profiler](https://github.com/async - profiler/async - profiler)（Apache 2.0）用于 JVM 性能分析。包含在 [uniprof - jvm](https://github.com/indragiek/uniprof/pkgs/container/uniprof - jvm) 镜像中。
- dotnet - trace（MIT）用于 .NET 性能分析。包含在 [uniprof - dotnet](https://github.com/indragiek/uniprof/pkgs/container/uniprof - dotnet) 镜像中。
- perf（GPL）用于 Linux 上的原生性能分析。包含在 [uniprof - native](https://github.com/indragiek/uniprof/pkgs/container/uniprof - native) 和 [uniprof - beam](https://github.com/indragiek/uniprof/pkgs/container/uniprof - beam) 镜像中。
- speedscope（MIT）与 uniprof 捆绑在一起，用于火焰图可视化。
📄 许可证
本仓库中的所有 uniprof 源代码均遵循 MIT 许可证。请参阅 LICENSE。
uniprof 会下载并运行 Docker 镜像，这些镜像捆绑了第三方软件。用于构建这些镜像的 Dockerfile 可以在 containers/ 中找到。这些镜像及其内容不受 MIT 许可证的覆盖，而是受其各自的许可证约束。uniprof 不授予这些组件的使用权限，也不会对它们进行重新许可。