Labsco
ZephyrDeng logo

Pprof Analyzer

โ˜… 50

from ZephyrDeng

Analyze Go pprof performance profiles (CPU, heap, goroutine, etc.) and generate flamegraphs.

๐Ÿ”ฅ๐Ÿ”ฅ๐Ÿ”ฅโœ“ VerifiedFreeAdvanced setup
#automation#devops#git#maps#monitoring

็ฎ€ไฝ“ไธญๆ–‡ | English

Pprof Analyzer MCP Server

smithery badge

GoDoc

This is a Model Context Protocol (MCP) server implemented in Go, providing a tool to analyze Go pprof performance profiles. Built with the official Model Context Protocol Go SDK.

Features

  • analyze_pprof Tool:
    • Analyzes the specified Go pprof file and returns serialized analysis results (e.g., Top N list or flame graph JSON).
    • Supported Profile Types:
      • cpu: Analyzes CPU time consumption during code execution to find hot spots.
      • heap: Analyzes the current memory usage (heap allocations) to find objects and functions with high memory consumption. Enhanced with object count, allocation site, and type information.
      • goroutine: Displays stack traces of all current goroutines, used for diagnosing deadlocks, leaks, or excessive goroutine usage.
      • allocs: Analyzes memory allocations (including freed ones) during program execution to locate code with frequent allocations. Provides detailed allocation site and object count information.
      • mutex: Analyzes contention on mutexes to find locks causing blocking. Provides detailed statistics including contention counts, delay times, and percentages.
      • block: Analyzes operations causing goroutine blocking (e.g., channel waits, system calls). Provides comprehensive blocking statistics with average delay calculations.
    • Supported Output Formats: text, markdown, json (Top N list), flamegraph-json (hierarchical flame graph data, default).
      • text, markdown: Human-readable text or Markdown format.
      • json: Outputs Top N results in structured JSON format (implemented for cpu, heap, goroutine, allocs, mutex, block).
      • flamegraph-json: Outputs hierarchical flame graph data in JSON format, compatible with d3-flame-graph (implemented for cpu, heap, allocs, default format). Output is compact.
    • Configurable number of Top N results (top_n, defaults to 5, effective for text, markdown, json formats).
  • generate_flamegraph Tool:
    • Uses go tool pprof to generate a flame graph (SVG format) for the specified pprof file, saves it to the specified path, and returns the path and SVG content.
    • Supported Profile Types: cpu, heap, allocs, goroutine, mutex, block.
    • Requires the user to specify the output SVG file path.
    • Important: This feature depends on Graphviz being installed.
  • open_interactive_pprof Tool (macOS Only):
    • Attempts to launch the go tool pprof interactive web UI in the background for the specified pprof file. Uses port :8081 by default if http_address is not provided.
    • Returns the Process ID (PID) of the background pprof process upon successful launch.
    • macOS Only: This tool will only work on macOS.
    • Dependencies: Requires the go command to be available in the system's PATH.
    • Limitations: Errors from the background pprof process are not captured by the server. Temporary files downloaded from remote URLs are not automatically cleaned up until the process is terminated (either manually via disconnect_pprof_session or when the MCP server exits).
  • detect_memory_leaks Tool:
    • Compares two heap profile snapshots to identify potential memory leaks.
    • Analyzes memory growth by object type and allocation site.
    • Provides detailed statistics on memory growth, including absolute and percentage changes.
    • Configurable growth threshold and result limit.
    • Helps identify memory leaks by comparing profiles taken at different points in time.
  • disconnect_pprof_session Tool:
    • Attempts to terminate a background pprof process previously started by open_interactive_pprof, using its PID.
    • Sends an Interrupt signal first, then a Kill signal if Interrupt fails.
  • compare_profiles Tool:
    • Compares two profile files (e.g., baseline vs. target) to identify performance regressions or improvements.
    • Supports all profile types (cpu, heap, allocs, mutex, block).
    • Provides detailed diff statistics including improved/regressed functions, added/removed functions.
    • Visual indicators: ๐Ÿ”ด regression, ๐ŸŸข improvement, ๐Ÿ†• added, โŒ removed.
    • Supports text, markdown, and JSON output formats.
  • analyze_heap_time_series Tool:
    • Analyzes multiple heap profiles over time to identify memory growth trends and potential leaks.
    • Requires at least 3 heap profiles provided in chronological order.
    • Calculates growth rates (bytes, percentage, MB per minute).
    • Identifies trending object types with directional indicators (๐Ÿ“ˆ increasing, ๐Ÿ“‰ decreasing, โžก๏ธ stable).
    • Supports custom labels for each time point or auto-generates default labels.
    • Supports text, markdown, and JSON output formats.

Building from Source

Ensure you have a Go environment installed (Go 1.18 or higher recommended).

In the project root directory (pprof-analyzer-mcp), run:

go build

This will generate an executable file named pprof-analyzer-mcp (or pprof-analyzer-mcp.exe on Windows) in the current directory.

You can also use go install to install the executable into your $GOPATH/bin or $HOME/go/bin directory. This allows you to run pprof-analyzer-mcp directly from the command line (if the directory is added to your system's PATH environment variable).

# 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

Releasing (Automated via GitHub Actions)

This project uses GoReleaser and GitHub Actions to automate the release process. Releases are triggered automatically when a Git tag matching the pattern v* (e.g., v0.1.0, v1.2.3) is pushed to the repository.

Pre-release Checklist:

Before creating a release tag, ensure:

  • โœ… All tests pass: go test ./...
  • โœ… Code compiles successfully: go build
  • โœ… Documentation is up to date (README, CHANGELOG, etc.)
  • โœ… Commit messages follow Conventional Commits format

Release Steps:

  1. Make Changes: Develop new features or fix bugs.
  2. Commit Changes: Commit your changes using Conventional Commits format (e.g., feat: ..., fix: ..., docs: ...). This is important for automatic changelog generation. 
    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. Push Changes: Push your commits to the main branch on GitHub. 
    git push origin main
  4. Run Pre-release Tests: Optionally, run tests locally before tagging: 
    go test ./... -v
go build -v
  5. Create and Push Tag: When ready to release, create a new Git tag and push it to GitHub. 
    # Example: Create tag v0.2.0
git tag v0.2.0

# Push the tag to GitHub
git push origin v0.2.0
  6. Automatic Release: Pushing the tag will trigger the GoReleaser GitHub Action defined in .github/workflows/release.yml. This action will:
    • Build binaries for Linux, macOS, and Windows (amd64 & arm64).
    • Generate a changelog based on Conventional Commits since the last tag.
    • Create a new GitHub Release with the changelog and attach the built binaries and checksums as assets.

Monitoring the Release:

You can view the release workflow progress in the "Actions" tab of the GitHub repository. Once complete, the release will be available at:

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

Dependencies

  • Graphviz: The generate_flamegraph tool requires Graphviz to generate SVG flame graphs (the go tool pprof command calls dot when generating SVG). Ensure Graphviz is installed on your system and the dot command is available in your system's PATH environment variable.

    Installing Graphviz:

    • macOS (using 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 (using Chocolatey): 
      choco install graphviz
    • Other Systems: Refer to the Graphviz official download page.

Future Improvements (TODO)

  • Add MIME type handling in MCP results based on output_format.
  • Add more robust error handling and logging level control.
  • Add integration tests for end-to-end MCP tool interactions.
  • Performance optimizations for large profile files (>1GB).

Recently Completed (v0.3.0)

  • โœ… Implement differential flame graphs to visualize changes between profiles. (Done - compare_profiles tool)
  • โœ… Add time-series analysis for memory profiles to track growth over multiple snapshots. (Done - analyze_heap_time_series tool)
  • โœ… Add automated CI/CD with GitHub Actions testing on every PR.
  • โœ… Implement full analysis logic for mutex, block profiles. (Done in v0.2.0)
  • โœ… Implement json output format for mutex, block profile types. (Done in v0.2.0)
  • โœ… Migrated to official Model Context Protocol Go SDK.
  • โœ… Consider supporting remote pprof file URIs (e.g., http://, https://). (Done in v0.2.0)
  • โœ… Implement full analysis logic for allocs profiles. (Done in v0.2.0)
  • โœ… Implement json output format for allocs profile type. (Done in v0.2.0)
  • โœ… Add memory leak detection capabilities. (Done in v0.2.0)