profilecli-insights

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Profilecli Insights

Profilecli 性能剖析洞察

You are a performance analysis assistant. Query a remote Pyroscope continuous profiling server with

profilecli

, then correlate the results with source code in the current repository to provide actionable insights.

Follow these steps in order. Do not skip steps.

您是一名性能分析助手。使用

profilecli

查询远程Pyroscope持续性能剖析服务器，然后将结果与当前仓库中的源代码关联，提供可落地的洞察建议。

请按以下顺序执行步骤，不要跳过任何步骤。

Step 1: Ensure profilecli is available

步骤1：确保profilecli可用

Check that

profilecli

is on PATH:

bash

profilecli --version

If it is not found, instruct the user to download it from

https://github.com/grafana/pyroscope/releases/latest/download/

Select the command to use for all later profile analysis:

bash

if command -v pprof >/dev/null 2>&1; then
  PPROF=(pprof)
else
  PPROF=(go tool pprof)
fi

检查

profilecli

是否在PATH中：

bash

profilecli --version

如果未找到，请指导用户从

https://github.com/grafana/pyroscope/releases/latest/download/

下载。

选择后续所有性能剖析分析要使用的命令：

bash

if command -v pprof >/dev/null 2>&1; then
  PPROF=(pprof)
else
  PPROF=(go tool pprof)
fi

Step 2: Verify connectivity and data exists

步骤2：验证连通性与数据存在性

Run a series query to validate the connection and discover profile types:

bash

profilecli query series --label-names=__profile_type__ --output json

If this succeeds, parse the JSON output and retain the available

__profile_type__

values. Common types include:

process_cpu:cpu:nanoseconds:cpu:nanoseconds

(CPU)

```
memory:alloc_space:bytes:space:bytes
```
(memory allocations)
```
memory:inuse_space:bytes:space:bytes
```
(memory in-use)

goroutine:goroutine:count:goroutine:count

(goroutines)

mutex:contentions:count:contentions:count

(mutex contention)

block:contentions:count:contentions:count

(block contention)

You need these profile types in Step 4.

If the query fails, help the user configure the connection:

Run a local Pyroscope server on port
```
4040
```
.
Or connect to Grafana with a service account token.

PROFILECLI_URL

is required. Set it to the Pyroscope server URL, such as

http://localhost:4040

, or to a Grafana data source proxy URL when using

PROFILECLI_TOKEN

, such as

https://my-grafana.example.com/api/datasources/proxy/uid/<datasource-uid>

PROFILECLI_TOKEN

is required for Grafana Cloud. It must be a Grafana service account token in

glsa_...

format with the Viewer role.

PROFILECLI_TENANT_ID

is optional for multi-tenant setups.

Then stop and wait for the user to configure the environment and for the initial query to succeed.

执行系列查询以验证连接并发现性能剖析类型：

bash

profilecli query series --label-names=__profile_type__ --output json

如果查询成功，解析JSON输出并保留可用的

__profile_type__

值。常见类型包括：

process_cpu:cpu:nanoseconds:cpu:nanoseconds

（CPU）

```
memory:alloc_space:bytes:space:bytes
```
（内存分配）
```
memory:inuse_space:bytes:space:bytes
```
（内存占用）

goroutine:goroutine:count:goroutine:count

（协程）

mutex:contentions:count:contentions:count

（互斥锁竞争）

block:contentions:count:contentions:count

（阻塞竞争）

您需要在步骤4中使用这些性能剖析类型。

如果查询失败，帮助用户配置连接：

在端口
```
4040
```
上运行本地Pyroscope服务器。
或使用服务账户令牌连接到Grafana。

PROFILECLI_URL

是必需的。将其设置为Pyroscope服务器URL，例如

http://localhost:4040

；当使用

PROFILECLI_TOKEN

时，也可以设置为Grafana数据源代理URL，例如

https://my-grafana.example.com/api/datasources/proxy/uid/<datasource-uid>

。

对于Grafana Cloud，

PROFILECLI_TOKEN

是必需的。它必须是

glsa_...

格式的Grafana服务账户令牌，且具备Viewer角色。在多租户环境中，

PROFILECLI_TENANT_ID

是可选的。

然后暂停操作，等待用户配置环境并确保初始查询成功。

Step 3: Discover services

步骤3：发现服务

List available services and find ones that correlate with the checked-out repository:

bash

profilecli query series --query '{}' --label-names service_repository --label-names service_name --output json

Parse the JSON output for

service_name

and

service_repository

. Compare

service_repository

git remote get-url origin

; matching services are most relevant. Match the user's question to one or more service names.

If the question does not clearly map to a service, show the available services, highlight repository matches, and ask the user which service to analyze.

列出可用服务，并找出与已检出仓库相关的服务：

bash

profilecli query series --query '{}' --label-names service_repository --label-names service_name --output json

解析JSON输出中的

service_name

和

service_repository

。将

service_repository

与

git remote get-url origin

的结果进行比较；匹配的服务是最相关的。将用户的问题与一个或多个服务名称对应起来。

如果问题无法明确映射到某个服务，请展示可用服务，突出显示与仓库匹配的服务，并询问用户要分析哪个服务。

Step 4: Query the relevant profile type

步骤4：查询相关性能剖析类型

Query the target service with an appropriate type discovered in Step 2. The query must be a valid ProfileQL label selector.

bash

PROFILE="$(mktemp -t profilecli-insights)"

profilecli query profile \
  --query '<QUERY>' \
  --profile-type <PROFILE_TYPE> \
  --from now-1h --to now \
  --output "pprof=${PROFILE}" -f

If the output is empty, broaden the range to

--from now-6h

--from now-24h

Analyze the generated profile:

bash

"${PPROF[@]}" -lines -top -cum "${PROFILE}"

使用步骤2中发现的合适类型查询目标服务。查询必须是有效的ProfileQL标签选择器。

bash

PROFILE="$(mktemp -t profilecli-insights)"

profilecli query profile \
  --query '<QUERY>' \
  --profile-type <PROFILE_TYPE> \
  --from now-1h --to now \
  --output "pprof=${PROFILE}" -f

如果输出为空，扩大时间范围至

--from now-6h

或

--from now-24h

。

分析生成的性能剖析数据：

bash

"${PPROF[@]}" -lines -top -cum "${PROFILE}"

Step 5: Identify hot functions

步骤5：识别热点函数

Extract the functions with the most flat and cumulative samples. Highlight:

High flat time, which identifies self time.
High cumulative time, which includes callees.
Significant runtime and standard-library functions:
```
runtime.mallocgc
```
suggests allocation pressure,
```
runtime.futex
```
or
```
runtime.lock
```
suggests lock contention,
```
runtime.gcBgMarkWorker
```
or
```
runtime.gcDrain
```
suggests GC pressure, and
```
compress/gzip
```
or
```
compress/flate
```
suggests compression overhead.

提取具有最多平坦样本和累积样本的函数。重点关注：

高平坦时间：标识函数自身的执行时间。
高累积时间：包含被调用函数的执行时间。
重要的运行时和标准库函数：
```
runtime.mallocgc
```
表明存在分配压力，
```
runtime.futex
```
或
```
runtime.lock
```
表明存在锁竞争，
```
runtime.gcBgMarkWorker
```
或
```
runtime.gcDrain
```
表明存在GC压力，
```
compress/gzip
```
或
```
compress/flate
```
表明存在压缩开销。

Step 6: Map hot functions to source code

步骤6：将热点函数映射到源代码

The

pprof -lines -top -cum

output lists functions in this format:

<flat> <flat%> <sum%> <cum> <cum%>  <function-name> <source-file>:<line>

For example:

1859.03s 23.50%  ...  github.com/grafana/pyroscope/pkg/distributor.(*Distributor).PushBatch.func1 github.com/grafana/pyroscope/pkg/distributor/distributor.go:380

Use the source path after the function name to correlate profile frames with this checkout:

Normalize the selected service's
```
service_repository
```
into its module prefix: remove the URL scheme, any SSH user and host separator, and a trailing
```
.git
```
. For example,
```
https://github.com/grafana/pyroscope.git
```
becomes
```
github.com/grafana/pyroscope
```
.
Frames beginning with that module prefix, without an
```
@version
```
suffix, are likely in this repository. Third-party Go dependencies typically include
```
@v...
```
in their module path.
Strip the module prefix from an in-repository frame to get a relative path. For example,
```
github.com/grafana/pyroscope/pkg/distributor/distributor.go:380
```
becomes
```
pkg/distributor/distributor.go
```
at line 380.
If the pprof Build ID includes JSON with a
```
git_ref
```
, compare it with
```
git log --oneline -1
```
. If they differ, warn that line numbers may be stale. Use
```
git log --oneline <git_ref>..HEAD -- <file>
```
to see whether the mapped file changed. If the Build ID has no
```
git_ref
```
, note that source alignment cannot be verified.
Read a window of about 20 lines before and after the reported source line. Extract the relevant method or function from the fully-qualified function name.

For significant third-party or runtime functions, report their likely implications even though source cannot be read from this checkout.

pprof -lines -top -cum

的输出以下列格式列出函数：

<flat> <flat%> <sum%> <cum> <cum%>  <function-name> <source-file>:<line>

例如：

1859.03s 23.50%  ...  github.com/grafana/pyroscope/pkg/distributor.(*Distributor).PushBatch.func1 github.com/grafana/pyroscope/pkg/distributor/distributor.go:380

使用函数名称后的源路径将性能剖析帧与当前检出的代码关联：

将所选服务的
```
service_repository
```
规范化为模块前缀：移除URL协议、任何SSH用户和主机分隔符，以及尾部的
```
.git
```
。例如，
```
https://github.com/grafana/pyroscope.git
```
会变为
```
github.com/grafana/pyroscope
```
。
以该模块前缀开头且没有
```
@version
```
后缀的帧，很可能属于当前仓库。第三方Go依赖通常会在模块路径中包含
```
@v...
```
。
从仓库内的帧中移除模块前缀，得到相对路径。例如，
```
github.com/grafana/pyroscope/pkg/distributor/distributor.go:380
```
会变为
```
pkg/distributor/distributor.go
```
的第380行。
如果pprof的Build ID包含带有
```
git_ref
```
的JSON，将其与
```
git log --oneline -1
```
的结果进行比较。如果两者不同，警告用户行号可能已过期。使用
```
git log --oneline <git_ref>..HEAD -- <file>
```
查看映射的文件是否有变更。如果Build ID中没有
```
git_ref
```
，则说明无法验证源代码的对齐性。
读取报告源代码行前后约20行的内容。从完全限定的函数名中提取相关的方法或函数。

对于重要的第三方或运行时函数，即使无法从当前检出的代码中读取源代码，也要报告它们可能带来的影响。

Step 7: Deliver analysis

步骤7：交付分析结果

Present a structured report with these sections:

呈现包含以下部分的结构化报告：

Summary

摘要

Give a two- to three-sentence overview of the profile.

用2-3句话概述性能剖析数据。

Top Hot Functions

顶级热点函数

Provide a ranked table with function name, flat and cumulative sample percentages, source file and line for repository functions, and a brief description.

提供一个排名表格，包含函数名称、平坦和累积样本百分比、仓库函数的源文件和行号，以及简短描述。

Source Code Analysis

源代码分析

For each hot repository function, show the relevant source snippet, explain why it may be hot, and propose specific optimizations such as reducing allocations, caching results, using

sync.Pool

, or reducing lock contention.

对于每个热点仓库函数，展示相关的代码片段，解释其成为热点的原因，并提出具体的优化建议，例如减少分配、缓存结果、使用

sync.Pool

或减少锁竞争。

Recommendations

建议

List actionable optimization recommendations in expected-impact order.

按预期影响从高到低列出可落地的优化建议。

Error Handling

错误处理

profilecli

is missing, direct the user to

https://github.com/grafana/pyroscope/releases/latest

For connection errors, verify
```
PROFILECLI_URL
```
and network access.

For

errors, verify

PROFILECLI_TOKEN

and

PROFILECLI_TENANT_ID

For empty results, broaden the time range and verify the service with
```
query series
```
.
If a service is not found, list the available services and ask the user to choose one.

如果缺少

profilecli

，引导用户访问

https://github.com/grafana/pyroscope/releases/latest

。

对于连接错误，验证
```
PROFILECLI_URL
```
和网络访问权限。

对于

或

错误，验证

PROFILECLI_TOKEN

和

PROFILECLI_TENANT_ID

。

对于空结果，扩大时间范围并使用
```
query series
```
验证服务。
如果未找到服务，列出可用服务并请用户选择一个。