性能分析设置指南

了解如何在 EasyAPI 中启用 pprof 与 Pyroscope 性能分析

概述

EasyAPI 提供两类性能分析能力：

pprof（内置）：适合临时诊断与离线分析，启用后可通过 HTTP 端点采集 CPU、内存、协程等 profile 数据。
Pyroscope（可选）：适合线上持续分析与火焰图可视化，将性能数据持续上报至 Pyroscope 服务。

两者可以同时启用，互不冲突。

功能特点

零代码集成 — 仅通过环境变量配置
支持 Docker Compose 与独立部署
支持临时诊断与持续分析并存
可选鉴权与实例区分

pprof（内置）设置

1. 配置环境变量

使用 Docker Compose：

environment:
  - ENABLE_PPROF=true

独立部署：

export ENABLE_PPROF=true

2. 重启应用

重启 EasyAPI 服务以应用更改。

# Docker Compose
docker-compose down && docker-compose up -d

# 独立部署
# 直接重启你的 EasyAPI 应用程序

3. 验证

启用后，通常可在 /debug/pprof/ 访问 pprof 端点（以实际部署为准）。默认监听端口为 8005。

可使用 go tool pprof 采集并分析 profile，例如：

go tool pprof http://localhost:8005/debug/pprof/profile?seconds=30

安全提示：生产环境请限制 pprof 端点的访问范围，避免将诊断接口暴露到公网。

Pyroscope 设置

1. 准备 Pyroscope 服务

确保 Pyroscope 服务可访问，并记录服务地址（例如：http://localhost:4040）。

可使用 Pyroscope 官方 Docker 镜像快速部署，或接入 Grafana Cloud Profiles。

2. 配置环境变量

使用 Docker Compose：

environment:
  - PYROSCOPE_URL=http://localhost:4040
  - PYROSCOPE_APP_NAME=easy-api
  - PYROSCOPE_BASIC_AUTH_USER=your-user
  - PYROSCOPE_BASIC_AUTH_PASSWORD=your-password
  - PYROSCOPE_MUTEX_RATE=5
  - PYROSCOPE_BLOCK_RATE=5
  - HOSTNAME=your-hostname

独立部署：

export PYROSCOPE_URL=http://localhost:4040
export PYROSCOPE_APP_NAME=easy-api
export PYROSCOPE_BASIC_AUTH_USER=your-user
export PYROSCOPE_BASIC_AUTH_PASSWORD=your-password
export PYROSCOPE_MUTEX_RATE=5
export PYROSCOPE_BLOCK_RATE=5
export HOSTNAME=your-hostname

注意：PYROSCOPE_URL 留空时不会启用 Pyroscope 上报。Basic Auth 凭据仅在 Pyroscope 服务启用了鉴权时需要配置。

3. 重启应用

重启 EasyAPI 服务以应用更改。

4. 验证

打开 Pyroscope UI
选择 PYROSCOPE_APP_NAME 对应的应用（默认 easy-api）
如设置了 HOSTNAME，可在实例维度区分不同节点来源

故障排除

性能分析无法工作？

验证环境变量设置正确
更改变量后重启应用
检查网络连通性与鉴权配置
确认 PYROSCOPE_APP_NAME 命名一致

Docker 用户：

docker exec <container-name> env | grep -E "PPROF|PYROSCOPE"

环境变量参考

变量	必需	默认值	说明
`ENABLE_PPROF`	否	`false`	启用 pprof 性能分析（默认监听端口 8005）
`PYROSCOPE_URL`	否	`-`	Pyroscope 服务地址，留空则禁用
`PYROSCOPE_APP_NAME`	否	`easy-api`	Pyroscope 应用标识
`PYROSCOPE_BASIC_AUTH_USER`	否	`-`	Pyroscope Basic Auth 用户名
`PYROSCOPE_BASIC_AUTH_PASSWORD`	否	`-`	Pyroscope Basic Auth 密码
`PYROSCOPE_MUTEX_RATE`	否	`5`	Mutex 采样率
`PYROSCOPE_BLOCK_RATE`	否	`5`	Block 采样率
`HOSTNAME`	否	`easy-api`	实例标识，用于多节点区分来源

概述