logo
svn/pprof
Public
0
0
WeChat Login
CodeIssuesPull requestsEventsPackagesInsights
master
pprof/README.md
山里人
feat: 原生 pprof 端点集成到 Handler 中
751d8a45

GoProbe

Go 应用全方位监控探针，提供 pprof 性能分析、系统监控、进程监控、告警和健康检查功能。

特性

  • 🔥 可视化火焰图 - 直观展示 CPU、内存等性能数据
  • 📊 表格视图 - 调用栈详细信息
  • 📈 Go 运行时监控 - SSE 推送 Goroutine/内存/GC 等指标
  • 🖥️ 系统监控 - CPU、内存、磁盘 IO、网络流量实时监控
  • 📦 进程监控 - 进程 CPU、内存、线程、文件描述符、连接数
  • 🔔 告警系统 - 阈值告警 + Webhook 通知（支持企业微信/钉钉）
  • 📸 快照功能 - 保存完整状态，支持快照对比
  • ❤️ 健康检查 - /health 端点，支持 K8s 探针
  • 📁 历史记录 - 自动保存采样结果，支持回溯查看
  • 🔄 Profile 对比 - 对比两次采样差异，快速定位性能回归
  • 📥 导入/导出 - 支持标准 pprof 文件格式
  • 🔌 一行代码集成 - 类似 net/http/pprof 的简单 API
  • ✅ 完全兼容 - 同时提供原生 pprof 端点
  • 📦 零外部依赖 - 前端资源内嵌，无需额外部署
  • 🌍 跨平台 - 支持 Linux/macOS/Windows/BSD

安装

go get cnb.cool/svn/pprof

快速开始

方式一：使用 Handler（推荐）

适用于所有 Web 框架（Gin、Chi、Echo、Fiber 等）：

package main

import (
    "net/http"
    goprobe "cnb.cool/svn/pprof"
)

func main() {
    mux := http.NewServeMux()

    // 挂载 GoProbe（包含 UI + 原生 pprof 端点）
    mux.Handle("/debug/probe/", http.StripPrefix("/debug/probe", goprobe.Handler()))

    // 你的其他路由...
    mux.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
        w.Write([]byte("Hello World"))
    })

    http.ListenAndServe(":6060", mux)
}

方式二：Gin 框架集成

import (
    "github.com/gin-gonic/gin"
    goprobe "cnb.cool/svn/pprof"
)

func main() {
    r := gin.Default()

    // 挂载 GoProbe
    r.Any("/debug/probe/*any", gin.WrapH(goprobe.HandlerWithPrefix("/debug/probe")))

    // 你的其他路由...
    r.GET("/", func(c *gin.Context) {
        c.String(200, "Hello World")
    })

    r.Run(":6060")
}

启动后访问：

高级配置

// 自定义配置
opts := goprobe.Options{
    HistorySize:       50,              // 历史记录保留数量
    StatsHistorySize:  600,             // Go 运行时统计历史 (10分钟)
    SysMonHistorySize: 600,             // 系统监控历史 (10分钟)
    StatsInterval:     time.Second,     // 采集间隔
    SnapshotSize:      20,              // 快照保留数量
    Version:           "1.0.0",         // 服务版本
    ServiceName:       "my-service",    // 服务名称
}

handler := goprobe.HandlerWithOptions(opts)
mux.Handle("/debug/probe/", http.StripPrefix("/debug/probe", handler))

API

Handler()

返回 http.Handler，包含完整的 UI 和原生 pprof 端点：

// 标准 http.ServeMux
mux.Handle("/debug/probe/", http.StripPrefix("/debug/probe", goprobe.Handler()))

// Gin
r.Any("/debug/probe/*any", gin.WrapH(goprobe.HandlerWithPrefix("/debug/probe")))

// Chi
r.Mount("/debug/probe", goprobe.Handler())

// Echo
e.Any("/debug/probe/*", echo.WrapHandler(goprobe.HandlerWithPrefix("/debug/probe")))

HandlerWithPrefix(prefix string)

自动处理路径前缀，适用于需要自定义挂载路径的场景：

// Gin 示例
r.Any("/custom/path/*any", gin.WrapH(goprobe.HandlerWithPrefix("/custom/path")))

HandlerWithOptions(opts Options)

使用自定义配置：

handler := goprobe.HandlerWithOptions(goprobe.Options{
    HistorySize: 100,
    ServiceName: "my-service",
})
mux.Handle("/debug/probe/", http.StripPrefix("/debug/probe", handler))

端点说明

GoProbe 提供以下端点：

UI 界面

  • / - Web UI 首页
  • /api/types - 可用的 profile 类型
  • /api/profile - 获取 profile 数据
  • /api/flamegraph - 火焰图数据
  • /api/stats - Go 运行时统计
  • /api/stats/stream - SSE 实时统计流
  • /api/sysmon - 系统监控数据
  • /api/sysmon/stream - SSE 系统监控流
  • /api/alerts/* - 告警配置和历史
  • /api/snapshots/* - 快照管理
  • /health - 健康检查

原生 pprof 端点（兼容 go tool pprof）

  • /pprof/ - pprof 索引页
  • /pprof/profile - CPU profile
  • /pprof/heap - 堆内存 profile
  • /pprof/goroutine - Goroutine profile
  • /pprof/allocs - 内存分配 profile
  • /pprof/block - 阻塞 profile
  • /pprof/mutex - 互斥锁 profile
  • /pprof/threadcreate - 线程创建 profile
  • /pprof/cmdline - 命令行参数
  • /pprof/symbol - 符号解析
  • /pprof/trace - 执行追踪

使用 go tool pprof

# CPU profiling (30秒)
go tool pprof http://localhost:6060/debug/probe/pprof/profile?seconds=30

# 堆内存分析
go tool pprof http://localhost:6060/debug/probe/pprof/heap

# Goroutine 分析
go tool pprof http://localhost:6060/debug/probe/pprof/goroutine

框架集成

GoProbe 返回标准的 http.Handler，可以轻松集成到任何 Go Web 框架。

Gin

import (
    "github.com/gin-gonic/gin"
    goprobe "cnb.cool/svn/pprof"
)

func main() {
    r := gin.Default()

    // 使用 gin.WrapH
    r.Any("/debug/probe/*any", gin.WrapH(goprobe.HandlerWithPrefix("/debug/probe")))

    r.Run(":8080")
}

Chi

import (
    "github.com/go-chi/chi/v5"
    goprobe "cnb.cool/svn/pprof"
)

func main() {
    r := chi.NewRouter()

    // 直接挂载
    r.Mount("/debug/probe", goprobe.Handler())

    http.ListenAndServe(":8080", r)
}

Echo

import (
    "github.com/labstack/echo/v4"
    goprobe "cnb.cool/svn/pprof"
)

func main() {
    e := echo.New()

    // 使用 echo.WrapHandler
    e.Any("/debug/probe/*", echo.WrapHandler(goprobe.HandlerWithPrefix("/debug/probe")))

    e.Start(":8080")
}

Fiber

import (
    "github.com/gofiber/fiber/v2"
    "github.com/gofiber/fiber/v2/middleware/adaptor"
    goprobe "cnb.cool/svn/pprof"
)

func main() {
    app := fiber.New()

    // 使用 adaptor 转换
    app.All("/debug/probe/*", adaptor.HTTPHandler(goprobe.HandlerWithPrefix("/debug/probe")))

    app.Listen(":8080")
}

标准库 http.ServeMux

import (
    "net/http"
    goprobe "cnb.cool/svn/pprof"
)

func main() {
    mux := http.NewServeMux()

    // 方式 1: 使用 Register (推荐，同时注册 pprof 端点)
    goprobe.Register(mux)

    // 方式 2: 手动挂载 Handler
    mux.Handle("/debug/probe/", http.StripPrefix("/debug/probe", goprobe.Handler()))

    http.ListenAndServe(":8080", mux)
}

支持的 Profile 类型

类型描述即时
cpuCPU 使用分析❌
heap堆内存分配✅
goroutineGoroutine 堆栈✅
allocs内存分配采样✅
block阻塞分析✅
mutex互斥锁竞争✅
threadcreate线程创建✅

HTTP 端点

UI 端点

端点方法描述
/debug/probe/GETWeb UI 入口
/debug/probe/api/typesGET获取可用类型
/debug/probe/api/profileGET获取 profile (JSON)
/debug/probe/api/flamegraphGET获取火焰图数据
/debug/probe/api/historyGET列出历史记录
/debug/probe/api/diffGET对比两个 profile
/debug/probe/api/statsGET获取 Go 运行时统计
/debug/probe/api/stats/streamGETSSE 实时统计流
/debug/probe/api/sysmonGET获取系统监控数据
/debug/probe/api/sysmon/streamGETSSE 系统监控流
/debug/probe/api/alerts/configGET/POST告警配置
/debug/probe/api/alerts/activeGET活跃告警
/debug/probe/api/alerts/testPOST测试 Webhook
/debug/probe/api/snapshotsGET/POST快照列表/创建
/debug/probe/api/healthGET健康检查

原生 pprof 端点

端点描述
/debug/pprof/pprof 索引页
/debug/pprof/profileCPU profile
/debug/pprof/heap堆内存 profile
/debug/pprof/goroutineGoroutine profile
/debug/pprof/cmdline命令行参数
/debug/pprof/symbol符号化
/debug/pprof/trace执行追踪

功能详解

系统监控

实时监控系统和进程级指标：

系统级:

  • CPU 使用率（用户态/内核态/IO等待）
  • 内存使用（总量/已用/可用/缓存）
  • 系统负载（1/5/15 分钟）
  • 磁盘 IO（读写速率、IOPS）
  • 网络流量（收发速率、包数）

进程级:

  • CPU 使用率
  • 内存使用（RSS/VMS）
  • 线程数
  • 文件描述符数
  • 网络连接数
  • IO 读写

告警系统

支持多种阈值告警：

// Go 运行时阈值
- Goroutine 数量
- 堆内存大小
- GC 暂停时间
- Goroutine 泄漏检测

// 系统级阈值
- CPU 使用率
- 内存使用率
- 系统负载
- 磁盘 IO 速率
- 网络流量

// 进程级阈值
- 进程 CPU/内存
- 文件描述符数
- 连接数

Webhook 支持模板变量：

{
  "msgtype": "markdown",
  "markdown": {
    "content": "## {{status}} {{level_cn}}\n**类型**: {{type}}\n**消息**: {{message}}\n**当前值**: {{value}}\n**阈值**: {{threshold}}\n**时间**: {{time}}"
  }
}

健康检查

curl http://localhost:6060/debug/probe/api/health

返回：

{
  "status": "healthy",
  "timestamp": "2024-01-01T12:00:00Z",
  "uptime": "24h30m",
  "version": "1.0.0",
  "checks": {
    "goroutines": { "status": "pass", "value": "50" },
    "memory": { "status": "pass", "value": "128 MB" },
    "gc": { "status": "pass", "value": "1.2 ms" }
  }
}

快照功能

保存完整的运行时状态，支持对比分析：

# 创建快照
curl -X POST http://localhost:6060/debug/probe/api/snapshots \
  -H "Content-Type: application/json" \
  -d '{"label": "优化前", "note": "版本 v1.0"}'

# 对比快照
curl "http://localhost:6060/debug/probe/api/snapshots/compare?id1=snap-1&id2=snap-2"

与 go tool pprof 配合使用

# CPU 分析
go tool pprof http://localhost:6060/debug/pprof/profile?seconds=30

# 内存分析
go tool pprof http://localhost:6060/debug/pprof/heap

# Goroutine 分析
go tool pprof http://localhost:6060/debug/pprof/goroutine

技术栈

  • 后端: Go 1.24+, gopsutil v4
  • 前端: React 18, D3.js, TailwindCSS
  • 构建: Vite
  • 通信: JSON API, SSE

许可证

MIT

© 2026 Tencent, Inc. Supported by Tencent Cloud
About Us
Privacy Policy
Terms of Service
SLA
API
Docs
Showcase
Feedback
35/F,Tencent Building,Kejizhongyi Avenue,Nanshan District,Shenzhen
京ICP备11018762号-111
粤公网安备44030002006058号粤公网安备44030002006058号