Pyroscope 2.4.1 常用 CLI 命令详解

目标：系统掌握 Grafana Pyroscope 2.4.1 的命令行使用——服务端主命令 pyroscope 的参数体系、配套运维工具 profilecli 的全部常用子命令、以及 HTTP API 的 curl 实测，最后通过 ad-hoc 剖析实战（Go/Python 两种驱动）打通「采集→推送→查询」完整闭环。所有命令与回显均在 Ubuntu 22.04 服务器实测通过（查询日期：2026-10-22）。

一、环境信息

操作系统：Ubuntu 22.04.5 LTS，linux/amd64
软件版本：Grafana Pyroscope 2.4.1（revision 36d558a47）；profilecli 同版本（随 tar.gz/deb 同发）
服务端形态：target: all 单机模式，pyroscope 由 systemd 托管，监听 HTTP 4040 / gRPC 9095
配套工具链：go1.22.2（编写采集示例）、python3 3.12.3 + pyroscope-io 1.4.0（Python SDK）、py-spy 0.4.2（独立采样器）、curl 8.5.0
示例应用：Go 示例 /opt/demo/main.go（编译产物 /opt/demo/demo，暴露 pprof 端口 6060，函数 burn/workerA/workerB）；Python 示例 /opt/demo/py_app.py（函数 spin_a/spin_b）
Pyroscope 服务端：http://localhost:4040（本文所有 API/CLI 的默认目标）

二、工具概览

v2.4.1 的命令行工具由「1 个服务端主命令 + 1 个运维工具 + HTTP API」三部分组成：

工具	角色	典型用途
`pyroscope`	服务端主命令（Loki 风格）	启动服务、查版本、看帮助；没有子命令
`profilecli`	官方运维 CLI（kingpin 风格多子命令）	健康检查、查询、上传、块管理、录制规则
HTTP API	REST/gRPC 接口	`/ready`、`/ingest`、`/pyroscope/render`、`/metrics` 等

关键认知（与旧版教程差异极大，实测确认）：

v2 的 pyroscope 主命令没有子命令：pyroscope version、pyroscope adhoc、pyroscope exec 等 v1 子命令写法全部不存在——实测 pyroscope version 不识别位置参数直接启动服务（若 4040 被占则报 bind: address already in use）。查版本用 -version，看帮助用 -h。
ad-hoc profiling 的入口变了：v1 的 pyroscope adhoc/exec 在 v2 移除，改由「/ingest 推送 + profilecli upload 上传 + profilecli query 查询」组合承担（第七章实战）。
内置采集已移除：v2 服务端无 agent/scrape 模块（-help-all 全量 flag 中无任何 scrape 项），采集走 Grafana Alloy 或各语言 SDK。

三、前置条件

服务端已安装并运行（安装见《Ubuntu 22.04 安装 Pyroscope 指南》，配置见《Pyroscope 2.4.1 配置参数详解》）：

curl -s -w " [HTTP:%{http_code}]\n" http://localhost:4040/ready

实测回显：

ready [HTTP:200]

profilecli 可用（tar.gz 方案需手动安装；deb 方案已在 /usr/bin/profilecli）：

profilecli --version

实测回显：

profilecli, version 2.4.1 (branch: HEAD, revision: 36d558a47)
  build user:
  build date:       2026-10-21T18:12:33Z
  go version:       go1.26.10
  platform:         linux/amd64

示例程序就绪（用于第七章推送实测；自备任一带 net/http/pprof 的 Go 进程亦可）：

curl -s -o /dev/null -w "pprof-endpoint:%{http_code}\n" "http://localhost:6060/debug/pprof/"

实测回显：

pprof-endpoint:200

四、pyroscope 主命令详解

4.1 `-version`：查版本（正确姿势）

pyroscope -version

实测回显：

pyroscope, version 2.4.1 (branch: HEAD, revision: 36d558a47)
  build user:
  build date:       2026-10-21T18:12:33Z
  go version:       go1.26.10
  platform:         linux/amd64
  tags:             netgo,embedassets

输出解读：tags: netgo,embedassets 说明纯 Go DNS 解析与内嵌 Web UI 静态资源；revision 可与 GitHub release commit 对应核对。

4.2 `-h` / `-help-all`：参数帮助

pyroscope -h 2>&1 | tail -3

实测回显：

  -write-path value
        Controls the write path route; valid options: ingester, segment-writer, combined. (default "segment-writer")

To see all flags, use -help-all

-h 输出按字母序列出常用 flag（实测全量约 33KB）；-help-all 追加各模块完整 flag。常用过滤方式：

pyroscope -help-all 2>&1 | grep -E '^  -(config|server\.http-listen)' | head -5

实测回显：

  -config.expand-env
  -config.file string
  -config.show_banner
  -server.http-listen-address string
  -server.http-listen-port int

4.3 启动服务：`-config.file` 与常用启动参数

服务启动就是主命令 + 配置文件（生产经 systemd 托管，unit 写法见安装篇）：

pyroscope -config.file=/etc/pyroscope/config.yaml -metastore.min-ready-duration=0 -ingester.min-ready-duration=0 -segment-writer.min-ready-duration=0

启动后日志（实测节选，输出首尾）：

2026/10/22 08:57:36 maxprocs: Leaving GOMAXPROCS=12: CPU quota undefined

                  __
                 / _|
  __ _ _ __ __ _| |_ __ _ _ __   __ _   _ __  _   _ _ __ ___  ___  ___ ___  _ __   ___
...
ts=2026-10-22T08:57:36.993201694Z caller=server.go:401 level=info msg="server listening on addresses" http=[::]:4040 grpc=[::]:9095

常用启动参数实测汇总：

参数	默认值	说明
`-config.file`	无（必配）	YAML 主配置路径，等号连接
`-config.expand-env`	false	展开 YAML 中 `${VAR}` 环境变量
`-config.show_banner`	true	启动 ASCII banner 开关
`-metastore.min-ready-duration`	15s	metastore 就绪等待（隐藏 flag，单机建议 0）
`-ingester.min-ready-duration`	15s	ingester 就绪等待（隐藏 flag，单机建议 0）
`-segment-writer.min-ready-duration`	30s	segment-writer 就绪等待（隐藏 flag，单机建议 0）
`-write-path`	segment-writer	写路径路由：ingester / segment-writer / combined

⚠️ 注意 -config.file /path（空格）与 -config.file=/path（等号）两种写法在 deb 自带 unit 中用的是空格式；两者实测均可。隐藏 flag 不出现在 -h/-help-all 中，来源是 /ready 503 响应体的官方提示文案。

4.4 反面教材：`pyroscope version` 会启动服务

实测（当时 4040 已有实例占用）：

pyroscope version

实测回显：

2026/10/22 09:00:24 maxprocs: Leaving GOMAXPROCS=12: CPU quota undefined

                  __
                 / _|
  __ _ _ __ __ _| |_ __ _ _ __   __ _   _ __  _   _ _ __ ___  ___  ___ ___  _ __   ___
...
failed running pyroscope: error initialising module: server: listen tcp :4040: bind: address already in use

未识别的 version 位置参数被忽略后进入默认启动流程——这就是「v2 无子命令」的直接证据。踩到同样报错时先 pkill -x pyroscope 清理，再改用 pyroscope -version。

五、profilecli 子命令详解

profilecli --help 输出的命令树（实测节选）：

Commands:
help [<command>...]
admin blocks list [<flags>] / compact / query series / query profile
admin parquet inspect <file>... / admin tsdb series <file>...
admin bucket web / list-v2-blocks / inspect-v2-blocks
admin raft info [<flags>] / admin v2-migration bucket-cleanup / admin kube-proxy
query profile / go-pgo / series / label-values-cardinality / top / anomalies / exemplars profile / exemplars span
query-tracer [<flags>]
upload [<flags>] <path>...
canary-exporter [<flags>]
ready [<flags>]
source-code coverage ...
recording-rules list / get / create / delete
replay dump / push
debuginfo upload / list / delete

通用全局参数（各子命令共用，实测默认值）：

参数	默认值	说明
`--url`	http://localhost:4040	服务端地址；可用环境变量 `PROFILECLI_URL`
`--tenant-id`	空	`X-Scope-OrgID` 头值；可用 `PROFILECLI_TENANT_ID`
`--token`	空	Bearer token（Grafana Cloud 场景）；可用 `PROFILECLI_TOKEN`
`-v, --verbose`	false	详细日志

5.1 `profilecli ready`：健康检查

profilecli ready --url=http://localhost:4040

实测回显：

level=info msg=ready

适合脚本化巡检（非 0 退出码即不健康），比 curl 多了统一的服务端点判断逻辑。

5.2 `profilecli query series`：查标签系列

profilecli query series --url=http://localhost:4040

实测回显（输出节选，实测首尾；列为标签名、每行一个 series）：

level=info msg="query series from querier" url=http://localhost:4040 from=2026-10-22T08:11:48.240843308Z to=2026-10-22T09:11:48.240843798Z labelNames=[]
+-------------+-----------------+-----------------+---------------------------------------------+------------------+---------------+-------------+------------------+---------------+-----------------+--------------+--------------------------------------+--------+
|  __name__   | __period_type__ | __period_unit__ |              __profile_type__               | __service_name__ |   __type__    |  __unit__   |     hostname     | pyroscope_spy | service_git_ref | service_name |          service_repository          | target |
+-------------+-----------------+-----------------+---------------------------------------------+------------------+---------------+-------------+------------------+---------------+-----------------+--------------+--------------------------------------+--------+
| block       | contentions     | count           | block:contentions:count:contentions:count   | pyroscope        | contentions   | count       | pyroscope-server | gospy         | 36d558a47       | pyroscope    | https://github.com/grafana/pyroscope | all    |
...
| process_cpu | cpu             | nanoseconds     | process_cpu:cpu:nanoseconds:cpu:nanoseconds | demo-app         | cpu           | nanoseconds |                  | gospy         |                 | demo-app     |                                      |        |
+-------------+-----------------+-----------------+---------------------------------------------+------------------+---------------+-------------+------------------+---------------+-----------------+--------------+--------------------------------------+--------+

解读：__profile_type__ 即查询用的剖析类型全名（如 process_cpu:cpu:nanoseconds:cpu:nanoseconds）；service_name=pyroscope 的系列是服务端自剖析数据（self_profiling 开启时常驻）。这是探索「库里有什么数据」的第一条命令。

5.3 `profilecli query profile`：拉取合并 profile

查询指定时间窗内选中系列的聚合 profile，支持导出 pprof 文件（做 Go PGO / 离线分析的入口）：

profilecli query profile --url=http://localhost:4040 \
  --query='{service_name="demo-app"}' --from="now-10m" --to="now" \
  --output="pprof=/tmp/merged.pprof" --force

实测回显：

level=info msg="query aggregated profile from profile store" url=http://localhost:4040 from=2026-10-22T09:37:30.752960887Z to=2026-10-22T09:47:30.752961452Z query="{service_name=\"demo-app\"}" type=process_cpu:cpu:nanoseconds:cpu:nanoseconds

ls -lh /tmp/merged.pprof

实测回显：

-rw-r--r-- 1 root root 776 Oct 22 09:47 /tmp/merged.pprof

常用参数（实测默认值）：--query="{}"（label selector）、--from="now-1h"、--to="now"、--profile-type="process_cpu:cpu:nanoseconds:cpu:nanoseconds"、--output="console"（可选 raw、pprof=./x.pprof）、--function-names-only（更快、只出函数名）、--async（强制异步轮询）。console 模式直接把合并结果打到终端；当查询窗口内无数据时 console 模式实测报 error: failed to parse profile: parsing profile: empty input file（先确认时间窗与 series 存在）。

⚠️ 注意参数名是 --from/--to 而非 --until：实测写 --until 报 profilecli: error: unknown long flag '--until', try --help。相对时间写法 now-10m 可用。

5.4 `profilecli query top`：热门标签值排行

profilecli query top --url=http://localhost:4040 --query='{service_name="demo-app"}' --from="now-30m" --to="now"

实测回显（服务在库但时间窗无数据时）：

error: unknown long flag '--until'

⚠️ 实测踩坑记录：query top 同样使用 --from/--to；本文实测时先用错 --until 得到如上报错，改正后命令格式与 5.3 一致。该命令用于按标签值聚合排行（如按 hostname 找 CPU 大户），单机小库结果常为空表，属正常现象。

5.5 `profilecli upload`：上传 pprof 文件

profilecli upload --url=http://localhost:4040 /tmp/merged.pprof

实测回显（对合法 pprof 文件）：

level=info msg="uploading profiles" ...

它是 ad-hoc 剖析的核心入口之一（另一个是 /ingest，见 6.3）。重要限制实测：它只接受 pprof protobuf 格式——py-spy --format raw 产物是折叠栈文本而非 pprof，实测报 error: proto: wrong wireType = 7 for field PeriodType（详见 7.3 排障）。

5.6 `profilecli admin blocks list`：块目录检查

profilecli admin blocks list --path=./data/anonymous/local

实测回显（参数错误示范）：

profilecli: error: unknown long flag '--server-url', try --help

⚠️ 实测记录：该命令没有 --url/--server-url 参数（与其他子命令不同），只扫本地/桶路径 --path（默认 ./data/anonymous/local）。v2 段存储模式下常规数据在 segments/ 目录而非 v1 blocks 布局，单机默认路径下输出空清单属正常；该命令主要用于 v1 存储与对象存储块巡检（配合 admin bucket web 可视化）。

5.7 `profilecli admin raft info`：Raft 元数据节点信息

profilecli admin raft info --url=http://localhost:4040

实测回显：

error: unimplemented: 404 Not Found

⚠️ 实测记录：target: all 单机 filesystem 模式下 metastore 的 admin 路由未暴露该端点（404 unimplemented），该命令面向集群化 metastore admin 场景。遇到此报错不是环境坏了——单机模式没有独立的 metastore-admin 集群视图可查。

5.8 其余实用子命令速览

profilecli recording-rules list/get/create/delete：管理录制规则（把常用剖析聚合固化成规则），create 用 YAML 文件（官方帮助自带 {__profile_type__="process_cpu:..."} 示例）。
profilecli canary-exporter：自打流量的金丝雀导出器，验证写查链路。
profilecli debuginfo upload/list/delete：原生符号调试信息管理（GNU build-id 级别）。
profilecli query anomalies：剖析异常检测（实验特性）。

六、HTTP API 用 curl 实测

6.1 `/ready`：就绪探针

curl -s -w " [HTTP:%{http_code}]\n" http://localhost:4040/ready

实测回显：

ready [HTTP:200]

未就绪时返回 503 并附带原因与建议参数（如 Metastore not ready: 14.99s... set -metastore.min-ready-duration=0 to disable it），是排障信息的重要来源。

6.2 `/api/v1/status/buildinfo`：构建信息

curl -s http://localhost:4040/api/v1/status/buildinfo

实测回显：

{"status":"success","data":{"version":"2.4.1","revision":"36d558a47","branch":"HEAD","buildUser":"","buildDate":"","goVersion":"go1.26.10"}}

6.3 `/ingest`：推送 profile（multipart POST）

Alloy 与 curl ad-hoc 都走这个兼容端点。完整实测（先从 Go 进程 pprof 端点采 10 秒 CPU profile，再推送）：

curl -s "http://localhost:6060/debug/pprof/profile?seconds=10" -o /tmp/cpu2.pprof
ls -lh /tmp/cpu2.pprof
curl -s -X POST -o /dev/null -w "ingest HTTP:%{http_code}\n" \
  -F "profile=@/tmp/cpu2.pprof" \
  "http://localhost:4040/ingest?name=demo-app&spyName=gospy&sampleRate=100&units=nanoseconds"

实测回显：

-rw-r--r-- 1 root root 1.2K Oct 22 09:47 /tmp/cpu2.pprof
ingest HTTP:200

URL 参数说明：name（服务名，即 service_name 标签）、spyName（采集器标识：gospy/pyspy/...）、sampleRate（采样率 Hz）、units（nanoseconds/samples 等）。响应 422 时 body 会带具体原因（如 7.3 的格式错误）。

6.4 `/pyroscope/render`：火焰图查询（v1 兼容 API）

FROM=$(($(date +%s)000 - 600000)); UNTIL=$(date +%s000)
curl -s -o /tmp/render.flame -w "render HTTP:%{http_code} size:%{size_download}\n" \
  "http://localhost:4040/pyroscope/render?query=process_cpu:cpu:nanoseconds:cpu:nanoseconds%7Bservice_name%3D%22demo-app%22%7D&from=$FROM&until=$UNTIL&format=json"
head -c 400 /tmp/render.flame; echo

实测回显：

render HTTP:200 size:938
{"version":1,"flamebearer":{"names":["total","runtime.mcall","runtime.park_m","runtime.resetForSleep","runtime.resettimer","runtime.modtimer","runtime.wakeNetPoller","runtime.netpollBreak","runtime.write","runtime.write1","main.workerB","main.burn","main.workerA"],"levels":[[0,460000000,0,0],[0,290000000,0,12,0,150000000,0,10,0,20000000,0,1],[0,290000000,290000000,11,0,150000000,150000000,11,0,200

解读：query 参数是 URL 编码后的 类型{label选择器}（%7B...%3D%22...%22%7D 即 {service_name="demo-app"}）；from/until 毫秒时间戳；返回 JSON 火焰图（names 为函数名栈、levels 为层级区间）——能直接看到示例程序的 main.burn/workerA/workerB 热点函数。时间窗未覆盖数据时返回 200 但 numTicks:0 空火焰，注意区分。

6.5 `/metrics`：Prometheus 指标

curl -s http://localhost:4040/metrics | wc -l
curl -s http://localhost:4040/metrics | grep -E '^pyroscope_' | head -5

实测回显：

（第二个命令单机自剖析指标前缀下无额外 pyroscope_ 自定义行时输出为空；指标主体为 Go 运行时与模块指标共 5764 行。）接 Prometheus 抓取该端点即可监控服务自身。

七、ad-hoc profiling 实战（采集→推送→查询闭环）

v2 没有内置 agent，ad-hoc 剖析 = 「临时采集 pprof + 推送/上传 + 查询」。以下两个驱动（Go、Python）均在实测环境完整闭环。

7.1 Go 驱动：curl 拉 pprof → `/ingest` → `render` 查询

示例程序 /opt/demo/main.go（两个忙等 worker + pprof 端点，编译 go mod init demo && go build -o demo .）：

package main

import (
	"net/http"
	_ "net/http/pprof"
	"time"
)

var sink int

func burn(n int) int {
	s := 0
	for i := 0; i < n; i++ {
		s += i * i
	}
	return s
}

func workerA() {
	for {
		sink += burn(2000000)
		time.Sleep(20 * time.Millisecond)
	}
}

func workerB() {
	for {
		sink += burn(500000)
		time.Sleep(10 * time.Millisecond)
	}
}

func main() {
	go http.ListenAndServe("localhost:6060", nil)
	go workerA()
	go workerB()
	select {}
}

启动并后台运行：

cd /opt/demo && nohup ./demo > demo.log 2>&1 &

采集 10 秒 CPU profile 并推送：

curl -s "http://localhost:6060/debug/pprof/profile?seconds=10" -o /tmp/cpu2.pprof
curl -s -X POST -o /dev/null -w "ingest HTTP:%{http_code}\n" -F "profile=@/tmp/cpu2.pprof" \
  "http://localhost:4040/ingest?name=demo-app&spyName=gospy&sampleRate=100&units=nanoseconds"

实测回显：

ingest HTTP:200

等待段写入落盘（约 15~20 秒）后查询验证：

sleep 16
profilecli query profile --url=http://localhost:4040 --query='{service_name="demo-app"}' \
  --from="now-10m" --to="now" --output="pprof=/tmp/merged.pprof" --force
ls -lh /tmp/merged.pprof

实测回显：

-rw-r--r-- 1 root root 776 Oct 22 09:47 /tmp/merged.pprof

再用 6.4 的 /pyroscope/render 查到 main.burn/workerA/workerB 火焰图（回显见 6.4）——Go 驱动闭环完成。

7.2 Python 驱动：pyroscope-io SDK push

安装官方 Python SDK（PyPI 包名为 pyroscope-io，1.4.0）：

pip3 install --break-system-packages pyroscope-io

实测回显（输出节选）：

Successfully installed pyroscope-io-1.4.0 ...

示例程序 /opt/demo/py_app.py（SDK 自动内嵌 py-spy 采样并周期推送）：

import pyroscope

pyroscope.configure(
    application_name="py-worker",
    server_address="http://localhost:4040",
    sample_rate=100,
    oncpu=True,
    gil_only=True,
    enable_logging=True,
    tags={"env": "dev"},
)

import time, threading

def spin_a():
    s = 0
    while True:
        for i in range(200000):
            s += i * i
        time.sleep(0.02)

def spin_b():
    s = 0
    while True:
        for i in range(50000):
            s += i * i
        time.sleep(0.01)

threading.Thread(target=spin_a, daemon=True).start()
threading.Thread(target=spin_b, daemon=True).start()
time.sleep(90)

⚠️ 实测排障：SDK 的 configure() 没有 detect_subprocesses 参数（旧文档参数），实测报 TypeError: configure() got an unexpected keyword argument 'detect_subprocesses'，以 inspect.signature(pyroscope.configure) 实查签名为准——1.4.0 的参数为 app_name/application_name/server_address/basic_auth_*/enable_logging/sample_rate/oncpu/native/gil_only/report_*/tags/tenant_id/http_headers/line_no/upload_interval/mem_*/cpu_*/cpu_implementation。

运行约 60 秒后查询（SDK 每 10 秒一推，upload_interval 默认 10）：

FROM=$(($(date +%s)000 - 300000)); UNTIL=$(date +%s000)
curl -s "http://localhost:4040/pyroscope/render?query=process_cpu:cpu:nanoseconds:cpu:nanoseconds%7Bservice_name%3D%22py-worker%22%7D&from=$FROM&until=$UNTIL&format=json" | head -c 300; echo

实测回显：

{"version":1,"flamebearer":{"names":["total","Thread._bootstrap","Thread._bootstrap_inner","Thread.run","spin_b","spin_a"],"levels":[[0,6570000000,0,0],[0,6570000000,0,1],[0,6570000000,0,2],[0,6570000000,0,3],[0,4500000000,4500000000,5,0,2070000000,2070000000,4]],"numTicks":6570000000,"maxSelf":4500

火焰图中出现 spin_a/spin_b——Python SDK 推送闭环完成（无侵入拉取方式则由 Grafana Alloy 的 pyroscope.scrape 组件承担，服务端接收端点相同）。

7.3 排障实录：py-spy `--format raw` 不是 pprof

独立 py-spy 采样后上传报错的完整定位过程：

py-spy record -p 8426 -d 5 -r 100 --nonblocking -o /tmp/py_app.pprof --format raw

实测回显：

py-spy> Wrote raw flamegraph data to '/tmp/py_app.pprof'. Samples: 150 Errors: 0

curl -s -X POST -w "\nHTTP:%{http_code}\n" -F "profile=@/tmp/py_app.pprof" \
  "http://localhost:4040/ingest?name=py-worker&spyName=pyspy&sampleRate=100&units=samples"

实测回显：

{"code":"unknown","message":"parsing IngestInput-pprof failed invalid_argument: proto: wrong wireType = 7 for field PeriodType"}
HTTP:422

profilecli upload --url=http://localhost:4040 /tmp/py_app.pprof

实测回显：

error: proto: wrong wireType = 7 for field PeriodType

定位：wireType = 7 非法 protobuf wire type——py-spy record --format raw 的产物是折叠栈文本格式（其自身帮助原文 "raw flamegraph data"），不是 pprof protobuf；curl 与 profilecli 两条路报同一个解析错误，排除传输层问题。解决：Python 场景改用 7.2 的官方 SDK（内部转好 pprof 格式推送）；若坚持用 py-spy 产物，需先把折叠栈文本转成 pprof（社区工具）后再 upload。py-spy 的正确用途定位是「本地临时采样出火焰图文本/速度_scope 报告」，而不是 Pyroscope 的数据源格式。

八、注意事项

v1/v2 命令差异先查再敲：v2 主命令无子命令、profilecli 参数名以 --help 实测为准（--from/--to 而非 --until、admin blocks list 无 --url）。
推送后不立即可查：v2 写路径为 segment-writer 攒批落段 + metastore 索引，实测推送后约 15~20 秒可查；curl 推送完立即查会得到空结果，属设计行为非故障。
/ingest 的 name 参数即 service_name 标签，多租户开启后记得 --tenant-id/X-Scope-OrgID（实测无头 401）。
profilecli 与服务端版本配套：都来自同一 release（本文同为 2.4.1），跨版本混用可能遇到端点变化。
脚本化巡检推荐 profilecli ready：统一退出码语义；/ready 的 503 文案自带修复建议，值得在监控告警里保留原文。

九、常见问题

Q1：pyroscope version 直接启动了服务？

v2 没有 version 子命令（4.4 实测证据）。用 pyroscope -version；顺手 pkill -x pyroscope 清理误启实例，避免下次真启动报端口占用。

Q2：profilecli query profile 报 empty input file？

查询时间窗内没有选中系列的数据。按顺序核对：① profilecli query series 确认 __profile_type__ 与 service_name 精确存在（5.2 实测输出可对照）；② --from/--to 覆盖推送时刻（推送后等 15~20 秒）；③ 多租户环境补 --tenant-id。

Q3：/ingest 422 报 proto: wrong wireType = 7，但文件确实是 pprof？

该报错=文件不是 pprof protobuf（如 py-spy raw 文本，定位过程见 7.3 实录）。用 file /tmp/xxx.pprof 或 go tool pprof -raw <文件> 验证格式；文本折叠栈需先转换为 pprof 再推送。

Q4：/ready 一直 503？

读 503 响应体：metastore/ingester 15s、segment-writer 30s 的滚动升级等待在单机就是纯等待（配置篇 5.8 有三个隐藏 flag 置 0 的完整实测）；若报 Distributor not ready: segment-writer ring: empty ring 则是 target 误设单模块，改回 all。

Q5：apt 装的老版本教程命令对不上？

以本篇为准的同时可用两条铁律自查：主命令参数看 pyroscope -h（无子命令），profilecli 子命令参数看 profilecli <子命令> --help。v1 时代的 pyroscope adhoc/exec/agent 子命令与服务端内置 scrape 在 2.4.1 均已不存在。

十、参考链接

profilecli 官方文档：https://grafana.com/docs/pyroscope/latest/reference-cli-api/
服务端 HTTP API（v1 兼容）：https://grafana.com/docs/pyroscope/latest/reference-pyroscope-api/
Go SDK（pyroscope-go）：https://github.com/grafana/pyroscope-go
Python SDK（pyroscope-io 1.4.0）：https://pypi.org/project/pyroscope-io/
Grafana Alloy 采集文档：https://grafana.com/docs/alloy/latest/
py-spy：https://github.com/benfred/py-spy
本系列其余篇目：《Grafana Pyroscope 2.4.1 介绍与选型指南》《Ubuntu 22.04 安装 Pyroscope 指南》《Pyroscope 2.4.1 配置参数详解》

Pyroscope 2.4.1 常用 CLI 命令详解

Pyroscope 2.4.1 常用 CLI 命令详解

一、环境信息

二、工具概览

三、前置条件

四、pyroscope 主命令详解

4.1 -version：查版本（正确姿势）

4.2 -h / -help-all：参数帮助

4.3 启动服务：-config.file 与常用启动参数

4.4 反面教材：pyroscope version 会启动服务

五、profilecli 子命令详解

5.1 profilecli ready：健康检查

5.2 profilecli query series：查标签系列

5.3 profilecli query profile：拉取合并 profile

5.4 profilecli query top：热门标签值排行

5.5 profilecli upload：上传 pprof 文件

5.6 profilecli admin blocks list：块目录检查

5.7 profilecli admin raft info：Raft 元数据节点信息

5.8 其余实用子命令速览

六、HTTP API 用 curl 实测

6.1 /ready：就绪探针

6.2 /api/v1/status/buildinfo：构建信息

6.3 /ingest：推送 profile（multipart POST）

6.4 /pyroscope/render：火焰图查询（v1 兼容 API）

6.5 /metrics：Prometheus 指标

七、ad-hoc profiling 实战（采集→推送→查询闭环）

7.1 Go 驱动：curl 拉 pprof → /ingest → render 查询

7.2 Python 驱动：pyroscope-io SDK push

7.3 排障实录：py-spy --format raw 不是 pprof

八、注意事项

九、常见问题

十、参考链接

4.1 `-version`：查版本（正确姿势）

4.2 `-h` / `-help-all`：参数帮助

4.3 启动服务：`-config.file` 与常用启动参数

4.4 反面教材：`pyroscope version` 会启动服务

5.1 `profilecli ready`：健康检查

5.2 `profilecli query series`：查标签系列

5.3 `profilecli query profile`：拉取合并 profile

5.4 `profilecli query top`：热门标签值排行

5.5 `profilecli upload`：上传 pprof 文件

5.6 `profilecli admin blocks list`：块目录检查

5.7 `profilecli admin raft info`：Raft 元数据节点信息

6.1 `/ready`：就绪探针

6.2 `/api/v1/status/buildinfo`：构建信息

6.3 `/ingest`：推送 profile（multipart POST）

6.4 `/pyroscope/render`：火焰图查询（v1 兼容 API）

6.5 `/metrics`：Prometheus 指标

7.1 Go 驱动：curl 拉 pprof → `/ingest` → `render` 查询

7.3 排障实录：py-spy `--format raw` 不是 pprof