Lib.rs

› 开发工具 › 性能分析 › Pyroscope
#profiler #pyroscope #cli-command #cli #shell-completion #run-command

app pyroscope-cli

Pyroscope性能分析器CLI

由 Abid Omar 和 16位贡献者 开发

3个不稳定版本

0.2.0 2022年5月4日
0.1.1 2022年3月30日
0.1.0 2022年3月30日

#328 in 性能分析

Apache-2.0

235KB
5K SLoC

Rust 4K SLoC // 0.1% comments Python 324 SLoC // 0.0% comments Ruby 209 SLoC // 0.0% comments Jsonnet 72 SLoC Forge Config 72 SLoC Shell 57 SLoC // 0.2% comments Bazel 2 SLoC

Pyroscope CLI (pyroscope-cli)

pyroscope-cli 是一个通用性能分析器。它目前支持Ruby和Python应用程序的性能分析。性能分析的数据聚合后发送到 Pyroscope服务器。在底层，它使用了 Pyroscope Rust库 和其 后端。

这是一个正在进行中的实现。一些功能（如adhoc/pull模式）尚不可用，性能分析代理仅限于Ruby/Python。对于原始实现，您应检查 Pyroscope Go代理。

变更日志

请参阅 变更日志 了解发布历史。

目录

安装

目前，本地安装 pyrsocope-cli 的最佳方法是使用 rustc 编译器和 Cargo。

$ cargo install pyrsocope-cli

二进制文件也可在发布页面中找到。目标平台是 x86_64/ARM 和 linux/macos。

如何使用

1. 基本用法

无论使用哪种性能分析器，分析程序的两种方法：要么通过连接到进程 PID，要么通过传递命令，代理将处理其执行和分析。

$ pyroscope-cli connect --pid=$pid --spy-name=rbspy

$ pyroscope-cli exec --spy-name=rbspy ruby ./program.rb

2. 连接到进程

要连接到进程并附加性能分析器，您需要进程ID和所需的系统权限。最后一个取决于您的操作系统及其配置。

要获取程序的PID，可以使用ps和grep

$ ps -aux | grep ruby

您还需要指定性能分析器，可能的值有rbspy（用于Ruby）和pyspy（用于Python）。pid和spy-name是性能分析进程所需的两个参数。

$ pyroscope-cli connect --pid=1222 --spy-name=rbspy

3. 执行命令

pyroscope-cli可以执行命令并分析由此产生的进程。命令作为代理进程的子进程启动。一旦代理进程退出，所执行的命令及其子进程也将退出。

$ pyroscope-cli exec --spy-name=rbspy ruby ./program.rb

您还可以通过附加--将参数传递给要执行的命令

$ pyroscope-cli exec --spy-name=rbspy ruby ./program.rb -- --ruby-arg=value

4. 选项

pyroscope-cli代理及其后端性能分析器都可以接受配置。一些选项被所有性能分析器接受，而其他只能应用于特定的性能分析器或多个性能分析器。CLI的--help菜单应提供程序可以接受的所有选项的详细列表。

4.1 所有性能分析器和命令接受的选项
  • application-name：上传性能数据时使用的应用程序名称。默认为随机生成的名称。
  • log-level：应用程序的日志级别。默认为info。有关更多信息，请参阅日志记录。
  • sample-rate：性能分析器的采样率，单位为Hz。100表示每秒读取100次。默认为100
  • server-address：Pyroscope服务器地址。默认为https://127.0.0.1:4040。
  • tag：键=值形式的标签。可以指定多次。默认为空。
4.2 exec命令接受的选项
  • user-name：在指定的用户名下启动进程。
  • group-name：在指定的组名下启动进程。

5. 配置

有3种方法可以配置Pyroscope代理。配置优先级按以下顺序评估：环境变量 > 配置文件 > 命令行参数。

1. 配置文件

配置文件存储在TOML格式中。您可以使用-config <path>指定配置文件位置。这适用于exec和connect命令。

pyroscope-cli -c -config /tmp/custom-config.toml <COMMAND>
2. 环境变量

环境变量必须具有PYROSCOPE_前缀，并且采用UPPER_SNAKE_CASE格式，例如

PYROSCOPE_APPLICATION_NAME=:my-ruby-app pyroscope-cli connect --pid=100 --spy-name=rbspy

6. 日志记录

日志输出到终端。有6个日志级别。日志级别不单独显示，而是具有优先级。例如，如果您指定了info日志级别，您将获得info、warn、error和critical日志的输出。

  • trace：非常低的优先级，通常非常详细的信息。
  • debug：较低的优先级信息。
  • info：有用的信息。
  • warn：危险情况。
  • error：非常严重的错误。
  • critical：导致程序崩溃的错误。

支持的性能分析器

1. rbspy

rbspy性能分析器可用于分析Ruby应用程序。它使用rbspy后端，它本身是rbspy性能分析器的包装器。

rbspy接受的选项
  • detect-subprocesses：跟踪并分析主进程的子进程。
  • blocking：启用阻塞模式

2. pyspy

《pyspy》性能分析器可以用来分析Ruby应用程序。它使用pyspy后端，而pyspy后端本身是对py-spy性能分析器的包装。

pyspy接受的选项
  • detect-subprocesses：跟踪并分析主进程的子进程。
  • blocking：启用阻塞模式。
  • pyspy-idle：包含空闲线程。
  • pyspy-gil：启用GIL模式。
  • pyspy-native：启用本地扩展分析。

常见问题解答

有关常见问题，请参阅FAQ页面。

Shell补全

pyroscope-cli支持为bash、zsh、fish和powershell提供shell自动完成。您可以使用completion命令生成自动完成文件。

例如，为fish生成自动完成

$ pyroscope-cli completion fish > pyroscope-cli.fish

从源代码构建

如果您已安装Rust工具链，可以从中构建pyroscope-cli。您将需要Rust 1.59或更高版本。

  1. 使用rustup安装Rust工具链
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

对于其他系统，请查阅https://rustup.rs/上的说明。

  1. 将~/.cargo/bin添加到您的PATH
. "$HOME/.cargo/env"
  1. 构建pyroscope-cli
git clone https://github.com/pyroscope-io/pyroscope-rs
cd pyroscope-rs/pyroscope_cli
cargo build --release
./target/release/pyroscope-cli --help

许可证

Pyroscope采用Apache License（版本2.0）分发。

有关详细信息，请参阅LICENSE。

依赖项

~38–54MB
~1M SLoC