效能分析設定指南

了解如何在 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`	實例識別名稱，用於多節點區分來源

概述