Pprof Analyzer MCP Server

简体中文 | 英语

Pprof Analyzer MCP 服务

这是一个用 Go 实现的 Model Context Protocol（MCP）服务，提供用于分析 Go pprof 性能分析文件的工具。该服务基于官方 Model Context Protocol Go SDK 构建。

功能

• analyze_pprof 工具：
  • 分析指定的 Go pprof 文件，并返回序列化的分析结果（例如 Top N 列表或火焰图 JSON）。
  • 支持的配置文件类型：
    • cpu：分析代码执行期间的 CPU 时间消耗，以查找热点。
    • heap：分析当前内存使用情况（堆分配），以查找内存消耗较高的对象和函数。增强了对象数量、分配位置和类型信息。
    • goroutine：显示所有当前 goroutine 的堆栈跟踪，用于诊断死锁、泄漏或 goroutine 使用过多的问题。
    • allocs：分析程序执行期间的内存分配（包括已释放的分配），以定位频繁分配的代码。提供详细的分配位置和对象数量信息。
    • mutex：分析互斥锁争用，以查找导致阻塞的锁。提供详细统计信息，包括争用次数、延迟时间和百分比。
    • block：分析导致 goroutine 阻塞的操作（例如通道等待、系统调用）。提供全面的阻塞统计信息，并计算平均延迟。
  • 支持的输出格式：text、markdown、json（Top N 列表）、flamegraph-json（分层火焰图数据，默认格式）。
    • text、markdown：易于阅读的文本或 Markdown 格式。
    • json：以结构化 JSON 格式输出 Top N 结果（已为 cpu、heap、goroutine、allocs、mutex、block 实现）。
    • flamegraph-json：以 JSON 格式输出分层火焰图数据，兼容 d3-flame-graph（已为 cpu、heap、allocs 实现，默认格式）。输出内容紧凑。
  • 可配置 Top N 结果的数量（top_n，默认为 5，适用于 text、markdown、json 格式）。
• generate_flamegraph 工具：
  • 使用 go tool pprof 为指定的 pprof 文件生成火焰图（SVG 格式），将其保存到指定路径，并返回该路径和 SVG 内容。
  • 支持的配置文件类型：cpu、heap、allocs、goroutine、mutex、block。
  • 用户必须指定输出 SVG 文件路径。
  • **重要：**此功能依赖已安装的 Graphviz。
• open_interactive_pprof 工具（仅限 macOS）：
  • 尝试在后台为指定的 pprof 文件启动 go tool pprof 交互式 Web UI。如果未提供 http_address，默认使用端口 :8081。
  • 成功启动后，返回后台 pprof 进程的进程 ID（PID）。
  • **仅限 macOS：**此工具仅适用于 macOS。
  • **依赖项：**系统 PATH 中必须包含 go 命令。
  • **限制：**服务不会捕获后台 pprof 进程产生的错误。远程 URL 下载的临时文件不会自动清理，只有在进程终止时才会清理（可手动调用 disconnect_pprof_session 终止进程，或等待 MCP 服务退出）。
• detect_memory_leaks 工具：
  • 比较两个堆配置文件快照，以识别潜在的内存泄漏。
  • 按对象类型和分配位置分析内存增长情况。
  • 提供内存增长的详细统计信息，包括绝对变化量和百分比变化。
  • 可配置增长阈值和结果上限。
  • 通过比较不同时间点采集的配置文件，帮助识别内存泄漏。
• disconnect_pprof_session 工具：
  • 使用 PID 尝试终止先前由 open_interactive_pprof 启动的后台 pprof 进程。
  • 先发送 Interrupt 信号；若失败，则发送 Kill 信号。
• compare_profiles 工具：
  • 比较两个配置文件（例如基线与目标配置文件），以识别性能回退或提升。
  • 支持所有配置文件类型（cpu、heap、allocs、mutex、block）。
  • 提供详细的差异统计信息，包括性能提升或回退的函数，以及新增或移除的函数。
  • 可视化标记：🔴 性能回退，🟢 性能提升，🆕 新增，❌ 移除。
  • 支持 text、markdown 和 JSON 输出格式。
• analyze_heap_time_series 工具：
  • 分析多个按时间排序的堆配置文件，以识别内存增长趋势和潜在泄漏。
  • 至少需要按时间顺序提供 3 个堆配置文件。
  • 计算增长率（字节、百分比、MB/分钟）。
  • 识别呈现趋势的对象类型，并使用方向标记（📈 增长，📉 减少，➡️ 稳定）。
  • 支持为每个时间点自定义标签，也可自动生成默认标签。
  • 支持 text、markdown 和 JSON 输出格式。

安装（作为库/工具）

你可以直接使用 go install 安装此软件包：

go install github.com/ZephyrDeng/pprof-analyzer-mcp@latest

这会将 pprof-analyzer-mcp 可执行文件安装到 $GOPATH/bin 或 $HOME/go/bin 目录。请确保此目录位于系统的 PATH 中，以便直接运行该命令。

从源代码构建

请确保已安装 Go 环境（建议使用 Go 1.18 或更高版本）。

在项目根目录（pprof-analyzer-mcp）中运行：

go build

这会在当前目录中生成名为 pprof-analyzer-mcp 的可执行文件（Windows 上为 pprof-analyzer-mcp.exe）。

使用 go install（推荐）

你也可以使用 go install 将可执行文件安装到 $GOPATH/bin 或 $HOME/go/bin 目录。这样一来，只要将该目录添加到系统的 PATH 环境变量中，就可以直接从命令行运行 pprof-analyzer-mcp。

# Installs the executable using the module path defined in go.mod
go install .
# Or directly using the GitHub path (recommended after publishing)
# go install github.com/ZephyrDeng/pprof-analyzer-mcp@latest

使用 Docker 运行

使用 Docker 运行服务十分方便，因为它已包含所需的 Graphviz 依赖项。

1. 构建 Docker 镜像： 在项目根目录（即 Dockerfile 所在目录）中运行：

   docker build -t pprof-analyzer-mcp .
   

2. 运行 Docker 容器：

   docker run -i --rm pprof-analyzer-mcp
   

   • -i 标志会保持 STDIN 打开，这是此 MCP 服务使用的 stdio 传输方式所必需的。
   • --rm 标志会在容器退出时自动将其删除。

3. 为 Docker 配置 MCP 客户端： 若要将 MCP 客户端（如 Roo Cline）连接到 Docker 中运行的服务，请更新 .roo/mcp.json：

   {
     "mcpServers": {
       "pprof-analyzer-docker": {
         "command": "docker run -i --rm pprof-analyzer-mcp"
       }
     }
   }
   

   请确保客户端运行此命令前，已在本地构建 pprof-analyzer-mcp 镜像。

发布（通过 GitHub Actions 自动完成）

本项目使用 GoReleaser 和 GitHub Actions 自动完成发布流程。向仓库推送符合 v* 模式的 Git 标签（例如 v0.1.0、v1.2.3）时，会自动触发发布。

发布前检查清单：

创建发布标签前，请确认：

• ✅ 所有测试均通过：go test ./...
• ✅ 代码成功编译：go build
• ✅ 文档均为最新版本（README、CHANGELOG 等）
• ✅ 提交消息遵循 Conventional Commits 格式

发布步骤：

1. 进行更改： 开发新功能或修复错误。
2. 提交更改： 使用 Conventional Commits 格式提交更改（例如 feat: ...、fix: ...、docs: ...）。这对自动生成更新日志很重要。

   git add .
   git commit -m "feat: Add awesome new feature"
   # or
   git commit -m "fix: Resolve issue #42"
   # or
   git commit -m "docs: Update README for new feature"
   

3. 推送更改： 将提交推送到 GitHub 上的 main 分支。

   git push origin main
   

4. 运行发布前测试： 可选择在打标签前于本地运行测试：

   go test ./... -v
   go build -v
   

5. 创建并推送标签： 准备好发布后，创建新的 Git 标签并推送到 GitHub。

   # Example: Create tag v0.2.0
   git tag v0.2.0
   
   # Push the tag to GitHub
   git push origin v0.2.0
   

6. 自动发布： 推送标签会触发 .github/workflows/release.yml 中定义的 GoReleaser GitHub Action。此操作将：
   • 为 Linux、macOS 和 Windows（amd64 和 arm64）构建二进制文件。
   • 根据自上一个标签以来的 Conventional Commits 生成更新日志。
   • 创建新的 GitHub Release，其中包含更新日志，并将构建的二进制文件和校验和作为资源附加。

监控发布：

你可以在 GitHub 仓库的“Actions”选项卡中查看发布工作流的进度。完成后，可在此处获取发布内容：

https://github.com/ZephyrDeng/pprof-analyzer-mcp/releases

配置 MCP 客户端

此服务使用 stdio 传输协议。你需要在 MCP 客户端（例如 VS Code 的 Roo Cline 扩展）中进行配置。

通常，需要将以下配置添加到项目根目录中的 .roo/mcp.json 文件：

{
  "mcpServers": {
    "pprof-analyzer": {
      "command": "pprof-analyzer-mcp"
    }
  }
}

注意： 根据构建方式（go build 或 go install）和可执行文件的实际位置调整 command 值。确保 MCP 客户端能够找到并执行此命令。

配置后，重新加载或重启 MCP 客户端，它应会自动连接到 PprofAnalyzer 服务。

依赖项

• Graphviz：generate_flamegraph 工具需要 Graphviz 来生成 SVG 火焰图（go tool pprof 命令在生成 SVG 时会调用 dot）。请确保系统已安装 Graphviz，且 dot 命令可通过系统的 PATH 环境变量访问。

  安装 Graphviz：

  • macOS（使用 Homebrew）：

    brew install graphviz
    

  • Debian/Ubuntu：

    sudo apt-get update && sudo apt-get install graphviz
    

  • CentOS/Fedora：

    sudo yum install graphviz
    # or
    sudo dnf install graphviz
    

  • Windows（使用 Chocolatey）：

    choco install graphviz
    

  • 其他系统： 请参阅 Graphviz 官方下载页面。

用法示例（通过 MCP 客户端）

连接服务后，可以使用 file://、http:// 或 https:// URI 指定配置文件，并调用 analyze_pprof 和 generate_flamegraph 工具。

示例：分析 CPU 配置文件（文本格式，前 5 项）

{
  "tool_name": "analyze_pprof",
  "arguments": {
    "profile_uri": "file:///path/to/your/cpu.pprof",
    "profile_type": "cpu"
  }
}

示例：分析堆配置文件（Markdown 格式，前 10 项）

{
  "tool_name": "analyze_pprof",
  "arguments": {
    "profile_uri": "file:///path/to/your/heap.pprof",
    "profile_type": "heap",
    "top_n": 10,
    "output_format": "markdown"
  }
}

示例：分析 Goroutine 配置文件（文本格式，前 5 项）

{
  "tool_name": "analyze_pprof",
  "arguments": {
    "profile_uri": "file:///path/to/your/goroutine.pprof",
    "profile_type": "goroutine"
  }
}

示例：为 CPU 配置文件生成火焰图

{
  "tool_name": "generate_flamegraph",
  "arguments": {
    "profile_uri": "file:///path/to/your/cpu.pprof",
    "profile_type": "cpu",
    "output_svg_path": "/path/to/save/cpu_flamegraph.svg"
  }
}

示例：为堆配置文件生成火焰图（inuse_space）

{
  "tool_name": "generate_flamegraph",
  "arguments": {
    "profile_uri": "file:///path/to/your/heap.pprof",
    "profile_type": "heap",
    "output_svg_path": "/path/to/save/heap_flamegraph.svg"
  }
}

示例：分析 CPU 配置文件（JSON 格式，前 3 项）

{
  "tool_name": "analyze_pprof",
  "arguments": {
    "profile_uri": "file:///path/to/your/cpu.pprof",
    "profile_type": "cpu",
    "top_n": 3,
    "output_format": "json"
  }
}

示例：分析 CPU 配置文件（默认火焰图 JSON 格式）

{
  "tool_name": "analyze_pprof",
  "arguments": {
    "profile_uri": "file:///path/to/your/cpu.pprof",
    "profile_type": "cpu"
    // output_format defaults to "flamegraph-json"
  }
}

示例：分析堆配置文件（显式指定火焰图 JSON 格式）

{
  "tool_name": "analyze_pprof",
  "arguments": {
    "profile_uri": "file:///path/to/your/heap.pprof",
    "profile_type": "heap",
    "output_format": "flamegraph-json"
  }
}

示例：分析远程 CPU 配置文件（来自 HTTP URL）

{
  "tool_name": "analyze_pprof",
  "arguments": {
    "profile_uri": "https://example.com/profiles/cpu.pprof",
    "profile_type": "cpu"
  }
}

示例：分析在线 CPU 配置文件（来自 GitHub Raw URL）

{
  "tool_name": "analyze_pprof",
  "arguments": {
    "profile_uri": "https://raw.githubusercontent.com/google/pprof/refs/heads/main/profile/testdata/gobench.cpu",
    "profile_type": "cpu",
    "top_n": 5
  }
}

示例：为在线堆配置文件生成火焰图（来自 GitHub Raw URL）

{
  "tool_name": "generate_flamegraph",
  "arguments": {
    "profile_uri": "https://raw.githubusercontent.com/google/pprof/refs/heads/main/profile/testdata/gobench.heap",
    "profile_type": "heap",
    "output_svg_path": "./online_heap_flamegraph.svg"
  }
}

示例：为在线 CPU 配置文件打开交互式 Pprof UI（仅限 macOS）

{
  "tool_name": "open_interactive_pprof",
  "arguments": {
    "profile_uri": "https://raw.githubusercontent.com/google/pprof/refs/heads/main/profile/testdata/gobench.cpu"
    // Optional: "http_address": ":8082" // Example of overriding the default port
  }
}

示例：检测两个堆配置文件之间的内存泄漏

{
  "tool_name": "detect_memory_leaks",
  "arguments": {
    "old_profile_uri": "file:///path/to/your/heap_before.pprof",
    "new_profile_uri": "file:///path/to/your/heap_after.pprof",
    "threshold": 0.05,  // 5% growth threshold
    "limit": 15         // Show top 15 potential leaks
  }
}

示例：断开 Pprof 会话

{
  "tool_name": "disconnect_pprof_session",
  "arguments": {
    "pid": 12345 // Replace 12345 with the actual PID returned by open_interactive_pprof
  }
}

后续改进（TODO）

• 根据 output_format 在 MCP 结果中添加 MIME 类型处理。
• 增强错误处理能力，并添加日志级别控制。
• 为端到端 MCP 工具交互添加集成测试。
• 针对大型配置文件（>1GB）进行性能优化。

近期已完成（v0.3.0）

• ✅ 实现差分火焰图，以可视化配置文件之间的变化。（已完成 - compare_profiles 工具）
• ✅ 为内存配置文件添加时间序列分析，以跟踪多个快照中的增长情况。（已完成 - analyze_heap_time_series 工具）
• ✅ 添加 GitHub Actions 自动化 CI/CD，在每个 PR 上运行测试。
• ✅ 为 mutex、block 配置文件实现完整的分析逻辑。（在 v0.2.0 中完成）
• ✅ 为 mutex、block 配置文件类型实现 json 输出格式。（在 v0.2.0 中完成）
• ✅ 迁移至官方 Model Context Protocol Go SDK。
• ✅ 考虑支持远程 pprof 文件 URI（例如 http://、https://）。（在 v0.2.0 中完成）
• ✅ 为 allocs 配置文件实现完整的分析逻辑。（在 v0.2.0 中完成）
• ✅ 为 allocs 配置文件类型实现 json 输出格式。（在 v0.2.0 中完成）
• ✅ 添加内存泄漏检测功能。（在 v0.2.0 中完成）