使用 Grafana Alloy 以 Pull 模式抓取 Node.js pprof 性能数据：Pyroscope 实战指南

使用 Grafana Alloy 以 Pull 模式抓取 Node.js pprof 性能数据：Pyroscope 实战指南

【免费下载链接】pyroscopeContinuous Profiling Platform. Debug performance issues down to a single line of code项目地址: https://gitcode.com/GitHub_Trending/py/pyroscope

本篇指南基于 Pyroscope 官方示例讲解Pull 模式下的连续性能分析：应用程序无需主动推送数据，而是由 Grafana Alloy 周期性抓取每个 Node.js 实例通过@pyroscope/nodejsExpress 中间件暴露的 pprof 端点，再统一转发到 Pyroscope 服务器。读完本文，你将掌握从零搭建「Pyroscope + Alloy + 多区域 Node.js 应用」全链路采集方案的能力，并理解 scrape 目标、profiling 配置、标签注入与可视化查询的完整工作流。

一、Pull 模式与 Push 模式：先理解数据流向

Pyroscope 支持两种接入方式：

• Push 模式：应用进程内嵌入 SDK，由 SDK 将 profile 数据推送到 Pyroscope 服务器（仓库中 express 示例即此模式，其 index.js 中通过Pyroscope.init({ appName, serverAddress, tags })后调用Pyroscope.start()主动上报）；
• Pull 模式（本文主题）：应用自身不做任何上报，只负责暴露标准的 pprof HTTP 端点；由抓取器（这里是 Grafana Alloy）按周期访问这些端点、拉取 profile 数据并转发到 Pyroscope 服务器。

本示例所在的 express-pull 目录完整演示了 Pull 模式。其 README 开宗明义："Instead of the application pushing profiles to Pyroscope, Alloy periodically scrapes the pprof endpoints exposed by each nodejs instance and forwards the profiles to the Pyroscope server."—— 即应用端不推送，Alloy 周期性抓取各 Node.js 实例暴露的 pprof 端点，再转发给 Pyroscope 服务端。

Pull 模式的典型价值在于：应用的接入成本更低、与抓取基础设施解耦，特别适合无法或不便在进程内常驻上报协程的场景（如 Serverless、多语言混合集群），也是 Prometheus 生态用户最熟悉的采集心智模型。

二、整体架构：一次docker-compose up拉起五个组件

完整拓扑定义在 docker-compose.yml，共包含五个服务：

其中us-east、eu-north、ap-south三个实例共享同一份构建上下文，仅通过环境变量REGION区分彼此：

us-east: environment: - REGION=us-east build: context: .

这与 Push 模式示例的玩法一致：同一份代码、三个 region 标签，用来演示「跨区域分布式应用」的连续性能剖析。

三、应用端：用 Express 中间件暴露 pprof 端点

演示应用是一份「微调过的 rideshare 应用」，核心代码在 index.js。与 Push 模式的关键差异在于：这里没有Pyroscope.start()，也没有serverAddress上报配置，只做两件事。

1. 初始化 SDK 并挂载中间件

const Pyroscope = require('@pyroscope/nodejs'); const { expressMiddleware } = Pyroscope.default; Pyroscope.init({ tags: { region } }); // 只打标签，不上报 app.use(expressMiddleware()); // 暴露 pprof 端点

Pyroscope.init({ tags: { region } })将REGION环境变量以静态标签形式注入所有 profile 数据；app.use(expressMiddleware())则在 Express 应用上挂载 pprof 端点（默认路径为/debug/pprof/...），供 Alloy 抓取。应用本身依然监听5000端口提供业务接口。

2. 用动态标签区分业务维度

三个业务路由分别模拟三种车辆搜索，搜索耗时由genericSearchHandler(p)的参数p控制（单位秒），并用wrapWithLabels打上vehicle动态标签：

app.get('/bike', function bikeSearchHandler(req, res) { Pyroscope.wrapWithLabels({ vehicle: 'bike' }, () => genericSearchHandler(0.5)(req, res) // 忙等约 0.5 秒 ); }); app.get('/car', function carSearchHandler(req, res) { Pyroscope.wrapWithLabels({ vehicle: 'car' }, () => genericSearchHandler(1)(req, res) // 忙等约 1 秒 ); }); app.get('/scooter', function scooterSearchHandler(req, res) { Pyroscope.wrapWithLabels({ vehicle: 'scooter' }, () => genericSearchHandler(0.25)(req, res) // 忙等约 0.25 秒 ); });

genericSearchHandler内部用while忙等循环制造真实 CPU 消耗，vehicle标签让后续在火焰图上可以按车辆类型拆分、对比三者 CPU 占比与耗时的比例关系。

3. 镜像构建与关键环境变量

Dockerfile 基于node:25，安装依赖后直接启动node index.js，并设置两个值得注意的环境变量：

ENV DEBUG=pyroscope ENV PYROSCOPE_WALL_COLLECT_CPU_TIME=true

• DEBUG=pyroscope：开启 SDK 的调试日志，便于排查抓取链路问题；
• PYROSCOPE_WALL_COLLECT_CPU_TIME=true：让 SDK 额外采集 wall-clock（墙上时钟）时间，从而在nodejs.wallprofile 类型下看到每个函数的真实耗时占比。

依赖方面，package.json 锁定了@pyroscope/nodejsv0.6.3、express^4.21.2 与morgan（请求日志中间件），并通过resolutions将qs、path-to-regexp固定到安全版本。

4. 内置负载生成器

压测脚本位于上层目录 load-generator.py，启动后每 0.2~0.4 秒随机挑选一个区域（us-east/eu-north/ap-south）和一个车辆端点（bike/car/scooter）发起请求：

host = HOSTS[random.randint(0, len(HOSTS) - 1)] vehicle = VEHICLES[random.randint(0, len(VEHICLES) - 1)] resp = requests.get(f'http://{host}:5000/{vehicle}')

这样三个区域的实例都能持续获得访问量，火焰图才有内容可看——这正是 README 所说「Profiling is more fun when the application does some work」（性能剖析在有真实负载时才更有意义）。

四、Alloy 侧：scrape 配置逐行拆解

整个 Pull 模式的核心在 alloy.config.alloy。该文件包含两个组件：pyroscope.write与pyroscope.scrape。

1. 写入组件：数据发往哪里

pyroscope.write "example" { endpoint { url = "http://pyroscope:4040" // 若要接入 Grafana Cloud，需配置 basic_auth： // basic_auth { // username = "myuser" // password = "mypassword" // } } external_labels = { "env" = "example", } }

• endpoint.url指向 Pyroscope 服务器（Docker 网络内主机名pyroscope，端口4040）；
• 注释中的basic_auth示例说明：改用 Grafana Cloud 时只需补充用户名/密码即可复用同一份配置；
• external_labels会作为全局附加标签打到所有转发的 profile 上，这里统一标记env="example"，方便在查询时按环境过滤。

2. 抓取组件：抓谁、抓什么

pyroscope.scrape "default" { targets = [ {"__address__" = "us-east:5000", "service_name"="nodejs"}, {"__address__" = "eu-north:5000", "service_name"="nodejs"}, {"__address__" = "ap-south:5000", "service_name"="nodejs"}, ] forward_to = [pyroscope.write.example.receiver] profiling_config { profile.memory { // disable memory, use godeltaprof_memory instead path = "/debug/pprof/heap" } } }

• targets：三个抓取目标，__address__为「主机名:端口」，service_name作为标签标明服务身份；
• forward_to：把抓取到的数据管道化转发到pyroscope.write.example组件的receiver；
• profiling_config.profile.memory：自定义内存 profile 的抓取路径为/debug/pprof/heap，并在注释中说明默认关闭 memory、改用 godeltaprof_memory——这是 Go/Node 生态中更高效的内存剖析采集方式，示例特意展示如何覆盖默认 profiling 配置。

3. 全局日志设置

logging { level = "debug" format = "logfmt" }

将 Alloy 自身日志调至 debug 级别，配合应用侧DEBUG=pyroscope，可以从抓取器与 SDK 两端双向排查抓取链路问题。

五、一键运行与数据观察

1. 启动

在 express-pull 目录下执行：

docker-compose up -d

该命令会拉取grafana/pyroscope:latest、grafana/alloy:latest、grafana/grafana:latest三个镜像，构建三个区域的应用镜像与负载生成器，然后后台启动全部服务。

2. 三个观测入口

启动完成后，按 README 指引可通过以下地址观察数据：

Grafana 的预配置数据源定义在 grafana-provisioning/datasources/pyroscope.yml：通过 provisioning 机制声明了grafana-pyroscope-datasource类型的数据源，url指向http://pyroscope:4040，并保留了pyroscope_git_sessioncookie 以便 Grafana 与 Pyroscope 之间共享会话；文件同样给出了接入 Grafana Cloud 时启用 basicAuth 的注释模板。

3. 观察要点

负载生成器会持续向三个区域打流量，20~30 秒后火焰图便会随抓取周期更新。由于三个车辆端点的忙等时间成比例（car 1s > bike 0.5s > scooter 0.25s），在火焰图底部可以看到bikeSearchHandler、carSearchHandler、scooterSearchHandler三个函数按各自的p参数成比例占据 CPU 资源——这正是验证「标签驱动 + 抓取驱动」连续剖析链路是否打通的最直观方式。

六、与 Push 模式示例的对照与选型建议

本仓库在 nodejs 目录下同时提供了多个接入变体：express（Push 模式）、express-ts、express-ts-inline、tinyhttp与本文的express-pull。对比两者的应用代码可以清晰看到接入差异：

七、关键结论

• Pull 模式接入成本极低：应用侧只需Pyroscope.init({ tags })+app.use(expressMiddleware())，无上报地址、无鉴权配置，全部采集策略收敛到 Alloy 的 alloy.config.alloy 一个文件；
• 标签体系贯穿全链路：静态标签（region）来自环境变量、动态标签（vehicle）来自wrapWithLabels、外部标签（env）来自 Alloyexternal_labels，三者叠加形成多维过滤能力；
• 配置可平滑迁移：同一份 Alloy 配置只需取消注释basic_auth即可从本地 Pyroscope 切换到 Grafana Cloud，本地与云端的采集逻辑完全一致；
• 排查抓手充分：Alloy 侧logging.level="debug"、应用侧DEBUG=pyroscope、以及 Alloy UI（:12345）的组件状态页，构成了抓取链路的三重可观测性。

按上述步骤启动后，你便拥有了一套完整的「多区域 Node.js 应用 + Pull 模式连续剖析」参考实现，可直接在其基础上扩展真实业务的抓取目标与标签策略。

【免费下载链接】pyroscopeContinuous Profiling Platform. Debug performance issues down to a single line of code项目地址: https://gitcode.com/GitHub_Trending/py/pyroscope