查看和分析 Profile 数据

Profile CLI

开源此页面包含适用于开源版本的内容。

Profile CLI

Pyroscope 提供了一个命令行界面 (CLI)，即 profilecli。此工具支持多种提高效率的工作流程，例如：

与运行中的 Pyroscope 服务器交互，上传 Profile、查询数据等
检查 Parquet 文件

提示
使用 help 命令（profilecli help）获取完整的功能列表和帮助信息。

安装 Profile CLI

您可以通过软件包或编译源代码的方式安装 Profile CLI。

使用软件包安装

在 macOS 上，您可以使用 HomeBrew 安装 Profile CLI

brew install pyroscope-io/brew/profilecli

对于其他平台，您可以手动下载适用于您操作系统和架构的 profilecli 发布资产，并使其可执行。

例如，对于 AMD64 架构的 Linux

下载并解压软件包（存档）。

curl -fL https://github.com/grafana/pyroscope/releases/download/v1.1.5/profilecli_1.1.5_linux_amd64.tar.gz | tar xvz

使 profilecli 可执行
bash
```
chmod +x profilecli
```
可选：使 profilecli 可在任何位置访问
bash
```
sudo mv profilecli /usr/local/bin
```

从源代码构建

从源代码构建，您必须具备：

已安装 Go（版本 > 1.19）。
已配置 $GOPATH 或 $GOBIN，并已将其添加到您的 PATH 环境变量中。

构建源代码

克隆仓库。

git clone git@github.com:grafana/pyroscope.git

运行 Go install 命令来构建并安装软件包。
bash
```
cd pyroscope
go install ./cmd/profilecli
```
该命令会将 profilecli 可执行文件放置在 $GOPATH/bin/（或 $GOBIN/）下，并使其可用。

常用 Flag 和环境变量

与 Pyroscope 服务器交互的 profilecli 命令需要服务器 URL 和可选的认证详情。这些可以通过命令行 flag 或环境变量提供。

服务器 URL
默认：https://:4040
--url flag 指定命令将运行的服务器。如果使用 Grafana Cloud，URL 示例可以是 https://profiles-prod-001.grafana.net。对于本地实例，URL 可以是 https://:4040。
认证详情。
默认：<空>
如果使用 Grafana Cloud 或您的 Pyroscope 服务器启用了认证，您需要分别使用 --username 和 --password flag 提供用户名和密码。对于 Grafana Cloud，用户名将是 Stack ID，密码是生成的 API token。

环境变量命名

您可以使用环境变量来避免每次使用命令时都传递 flag，或者保护敏感信息。环境变量带有 PROFILECLI_ 前缀。以下是为 profilecli 工具提供服务器 URL 和凭据的示例

export PROFILECLI_URL=<pyroscope_server_url>
export PROFILECLI_USERNAME=<username>
export PROFILECLI_PASSWORD=<password>
# now we can run a profilecli command without specifying the url or credentials:
profilecli <command>

注意
如果您正在查询 Cloud Profiles 中的数据，请确保在 PROFILECLI_URL 中使用您的 Cloud Profiles 服务器 URL（例如 https://profiles-prod-001.grafana.net），而不是您的 Grafana Cloud 租户 URL（例如 <您的租户>.grafana.net）。

使用 profilecli 将 Profile 上传到 Pyroscope 服务器

使用 profilecli 可以简化将 Profile 上传到 Pyroscope 的过程，使其成为手动 HTTP 请求的便捷替代方案。

开始之前

按照上面的安装步骤，确保您的系统上已安装 profilecli。
准备好要上传的 Profile 文件。请注意，目前您只能上传 pprof 文件。

上传步骤

确定 pprof 文件。
- 您的 pprof 文件路径：path/to/your/pprof-file.pprof
可选：指定任何额外 Label。
- 您可以使用 --extra-labels flag 为您上传的 Profile 添加额外 Label。
- 您可以通过 service_name Label 提供捕获 Profile 的应用名称（默认为 profilecli-upload）。这在使用 profilecli 或 UI 查询数据时非常有用。
- 您可以多次使用此 flag 添加多个 Label。

构造并执行 Upload 命令。

以下是一个基本的命令模板

export PROFILECLI_URL=<pyroscope_server_url>
export PROFILECLI_USERNAME=<username>
export PROFILECLI_PASSWORD=<password>

profilecli upload --extra-labels=<label_name>=<label_value> <pprof_file_path>

命令示例

export PROFILECLI_URL=https://profiles-prod-001.grafana.net
export PROFILECLI_USERNAME=my_username
export PROFILECLI_PASSWORD=my_password

profilecli upload path/to/your/pprof-file.pprof

带有额外 Label 的命令示例

export PROFILECLI_URL=https://profiles-prod-001.grafana.net
export PROFILECLI_USERNAME=my_username
export PROFILECLI_PASSWORD=my_password

profilecli upload \
    --extra-labels=service_name=my_application_name \
    --extra-labels=cluster=us-east \
    path/to/your/pprof-file.pprof

检查是否成功上传。
- 运行命令后，您应该看到一条确认消息，表明上传成功。如果出现任何问题，profilecli 会提供错误消息以帮助您进行故障排除。

使用 profilecli 查询 Pyroscope 服务器

您可以使用 profilecli query 命令在 Pyroscope 服务器上查找可用的 Profile 并读取实际的 Profile 数据。这对于调试或在 CI 流水线中集成性能分析（例如，为了方便 Profile 引导优化）非常有用。

在 Pyroscope 服务器上查找可用的 Profile

您可以使用 profilecli query series 命令在 Pyroscope 服务器上查找可用的 Profile。默认情况下，它会查询最近一小时的数据，尽管可以通过 --from 和 --to flag 进行控制。您可以使用 --query flag 缩小结果范围。有关更多信息，请参阅 profilecli help query series。

查询 Series 步骤

可选：指定查询和时间范围。
- 您可以使用 --query flag 提供 Label 选择器，例如：--query='{service_name="my_application_name"}'。
- 您可以使用 --from 和 --to flag 提供自定义时间范围，例如：--from="now-3h" --to="now"。

构造并执行 Query Series 命令。

以下是一个基本的命令模板

export PROFILECLI_URL=<pyroscope_server_url>
export PROFILECLI_USERNAME=<username>
export PROFILECLI_PASSWORD=<password>

profilecli query series --query='{<label_name>="<label_value>"}'

命令示例

export PROFILECLI_URL=https://profiles-prod-001.grafana.net
export PROFILECLI_USERNAME=my_username
export PROFILECLI_PASSWORD=my_password

profilecli query series --query='{service_name="my_application_name"}'

输出示例

{
    "__name__":"memory",
    "__period_type__":"space",
    "__period_unit__":"bytes",
    "__profile_type__":"memory:inuse_objects:count:space:bytes",
    "__service_name__":"my_application_name",
    "__type__":"inuse_objects",
    "__unit__":"count",
    "cluster":"eu-west-1",
    "service_name":"my_application_name"
 }

从 Pyroscope 服务器读取原始 Profile

您可以使用 profilecli query profile 命令从 Pyroscope 服务器检索合并（聚合）的 Profile。该命令会合并 Profile 存储中针对指定查询和时间范围找到的所有采样。默认情况下，它会查找最近一小时内的采样，尽管可以通过 --from 和 --to flag 进行控制。可以使用 --query flag 缩小源数据范围，方式与 series 命令相同。

查询 Profile 步骤

指定可选 Flag。
- 您可以使用 --query flag 提供 Label 选择器，例如：--query='{service_name="my_application_name"}'。
- 您可以使用 --from 和 --to flag 提供自定义时间范围，例如：--from="now-3h" --to="now"。
- 您可以通过 --profile-type flag 指定 Profile 类型。可用的 Profile 类型列在 profilecli query series 命令的输出中。

构造并执行 query profile 命令。

以下是一个基本的命令模板

export PROFILECLI_URL=<pyroscope_server_url>
export PROFILECLI_USERNAME=<username>
export PROFILECLI_PASSWORD=<password>

profilecli query profile \
    --profile-type=<profile_type> \
    --query='{<label_name>="<label_value>"' \
    --from="<from>" --to="<to>"

命令示例

export PROFILECLI_URL=https://profiles-prod-001.grafana.net
export PROFILECLI_USERNAME=my_username
export PROFILECLI_PASSWORD=my_password

profilecli query profile \
    --profile-type=memory:inuse_space:bytes:space:bytes \
    --query='{service_name="my_application_name"}' \
    --from="now-1h" --to="now"

输出示例

level=info msg="query aggregated profile from profile store" url=https://:4040 from=2023-12-11T13:38:33.115683-04:00 to=2023-12-11T14:38:33.115684-04:00 query={} type=memory:inuse_space:bytes:space:bytes
PeriodType: space bytes
Period: 524288
Time: 2023-12-11 13:59:59.999 -0400 AST
Duration: 59m5
Samples:
inuse_space/bytes[dflt]
  115366240: 107 13 14 15 16 17 1 2 3
...

导出 Go PGO 的 Profile

您可以使用 profilecli query go-pgo 命令从 Pyroscope 服务器检索聚合的 Profile，用于 Go PGO。使用 profilecli query profile 检索的 Profile 包含 Profile 存储中找到的所有采样，导致 Profile 文件很大。Profile 文件大小可能会导致网络传输问题并减慢 PGO 进程。相比之下，使用 profilecli query go-pgo 检索的 Profile 仅包含 Go PGO 使用的信息，使其显著更小，处理效率更高。默认情况下，它会查找最近一小时内的采样，尽管可以通过 --from 和 --to flag 进行控制。可以使用 --query flag 缩小源数据范围，方式与 query 命令相同。

指定可选 Flag。
- 您可以使用 --query flag 提供 Label 选择器，例如：--query='{service_name="my_application_name"}'。
- 您可以使用 --from 和 --to flag 提供自定义时间范围，例如：--from="now-3h" --to="now"。
- 您可以通过 --profile-type flag 指定 Profile 类型。可用的 Profile 类型列在 profilecli query series 命令的输出中。
- 您可以通过 --keep-locations flag 指定保留的叶节点数量。默认值为 5。Go 编译器不使用完整的堆栈追踪。减少此数量有助于最大程度地减小 Profile 大小。
- 您可以使用 --aggregate-callees flag 控制是否使用被调用者聚合。默认情况下，此选项已启用，这意味着采样会根据叶节点位置进行聚合，忽略被调用者行号，因为 Go 编译器不使用此信息。要禁用聚合，请使用 --no-aggregate-callees flag。

构造并执行命令。

命令示例

export PROFILECLI_URL=https://profiles-prod-001.grafana.net
export PROFILECLI_USERNAME=my_username
export PROFILECLI_PASSWORD=my_password

profilecli query go-pgo \
    --query='{service_name="my_service"}' \
    --from="now-1h" --to="now"

输出示例

level=info msg="querying pprof profile for Go PGO" url=https://:4040 query="{service_name=\"my_service\"}" from=2024-06-20T12:32:20+08:00 to=2024-06-20T15:24:40+08:00 type=process_cpu:cpu:nanoseconds:cpu:nanoseconds output="pprof=default.pgo" keep-locations=5 aggregate-callees=true
# By default, the profile is saved to the current directory as `default.pgo`

此页面有帮助吗？

在 GitHub 中提出编辑建议

创建 GitHub Issue

发送邮件至 docs@grafana.com

帮助和支持

社区

Profile CLI

安装 Profile CLI

使用软件包安装

从源代码构建

常用 Flag 和环境变量

环境变量命名

使用 profilecli 将 Profile 上传到 Pyroscope 服务器

开始之前

上传步骤

使用 profilecli 查询 Pyroscope 服务器

在 Pyroscope 服务器上查找可用的 Profile

查询 Series 步骤

从 Pyroscope 服务器读取原始 Profile

查询 Profile 步骤

导出 Go PGO 的 Profile

此页面有帮助吗？

Grafana Labs 的相关资源