Pprof Analyzer

Analiza perfiles de rendimiento pprof de Go (CPU, heap, goroutine, etc.) y genera gráficos de llama.

GitHub
50

Documentación

简体中文 | Español

Servidor MCP de Pprof Analyzer

smithery badge Build Status License Go Version GoDoc

Este es un servidor de Protocolo de Contexto de Modelo (MCP) implementado en Go, que proporciona una herramienta para analizar perfiles de rendimiento pprof de Go. Construido con el SDK de Go del Protocolo de Contexto de Modelo oficial.

Características

  • Herramienta analyze_pprof:
    • Analiza el archivo pprof de Go especificado y devuelve resultados de análisis serializados (por ejemplo, lista Top N o JSON de gráfico de llama).
    • Tipos de perfil compatibles:
      • cpu: Analiza el consumo de tiempo de CPU durante la ejecución del código para encontrar puntos críticos.
      • heap: Analiza el uso actual de memoria (asignaciones de heap) para encontrar objetos y funciones con alto consumo de memoria. Mejorado con recuento de objetos, sitio de asignación e información de tipo.
      • goroutine: Muestra los stack traces de todas las goroutines actuales, utilizado para diagnosticar deadlocks, fugas o uso excesivo de goroutines.
      • allocs: Analiza las asignaciones de memoria (incluidas las liberadas) durante la ejecución del programa para localizar código con asignaciones frecuentes. Proporciona información detallada del sitio de asignación y recuento de objetos.
      • mutex: Analiza la contención en mutexes para encontrar bloqueos que causan bloqueos. Proporciona estadísticas detalladas que incluyen recuentos de contención, tiempos de retardo y porcentajes.
      • block: Analiza operaciones que causan bloqueo de goroutines (por ejemplo, esperas de canal, llamadas al sistema). Proporciona estadísticas completas de bloqueo con cálculos de retardo promedio.
    • Formatos de salida compatibles: text, markdown, json (lista Top N), flamegraph-json (datos de gráfico de llama jerárquico, predeterminado).
      • text, markdown: Formato de texto legible por humanos o Markdown.
      • json: Genera resultados Top N en formato JSON estructurado (implementado para cpu, heap, goroutine, allocs, mutex, block).
      • flamegraph-json: Genera datos de gráfico de llama jerárquico en formato JSON, compatible con d3-flame-graph (implementado para cpu, heap, allocs, formato predeterminado). La salida es compacta.
    • Número configurable de resultados Top N (top_n, predeterminado 5, efectivo para formatos text, markdown, json).
  • Herramienta generate_flamegraph:
    • Utiliza go tool pprof para generar un gráfico de llama (formato SVG) para el archivo pprof especificado, lo guarda en la ruta especificada y devuelve la ruta y el contenido SVG.
    • Tipos de perfil compatibles: cpu, heap, allocs, goroutine, mutex, block.
    • Requiere que el usuario especifique la ruta del archivo SVG de salida.
    • Importante: Esta característica depende de que Graphviz esté instalado.
  • Herramienta open_interactive_pprof (solo macOS):
    • Intenta iniciar la interfaz web interactiva de go tool pprof en segundo plano para el archivo pprof especificado. Utiliza el puerto :8081 de forma predeterminada si no se proporciona http_address.
    • Devuelve el ID de proceso (PID) del proceso de pprof en segundo plano tras un inicio exitoso.
    • Solo macOS: Esta herramienta solo funcionará en macOS.
    • Dependencias: Requiere que el comando go esté disponible en el PATH del sistema.
    • Limitaciones: Los errores del proceso de pprof en segundo plano no son capturados por el servidor. Los archivos temporales descargados de URLs remotas no se limpian automáticamente hasta que el proceso se termina (ya sea manualmente mediante disconnect_pprof_session o cuando el servidor MCP sale).
  • Herramienta detect_memory_leaks:
    • Compara dos instantáneas de perfil de heap para identificar posibles fugas de memoria.
    • Analiza el crecimiento de memoria por tipo de objeto y sitio de asignación.
    • Proporciona estadísticas detalladas sobre el crecimiento de memoria, incluidos cambios absolutos y porcentuales.
    • Umbral de crecimiento y límite de resultados configurables.
    • Ayuda a identificar fugas de memoria comparando perfiles tomados en diferentes puntos en el tiempo.
  • Herramienta disconnect_pprof_session:
    • Intenta terminar un proceso de pprof en segundo plano iniciado previamente por open_interactive_pprof, usando su PID.
    • Envía primero una señal de interrupción y luego una señal de kill si la interrupción falla.
  • Herramienta compare_profiles:
    • Compara dos archivos de perfil (por ejemplo, línea base vs. objetivo) para identificar regresiones o mejoras de rendimiento.
    • Admite todos los tipos de perfil (cpu, heap, allocs, mutex, block).
    • Proporciona estadísticas de diff detalladas que incluyen funciones mejoradas/regresadas, funciones agregadas/eliminadas.
    • Indicadores visuales: 🔴 regresión, 🟢 mejora, 🆕 agregada, ❌ eliminada.
    • Compatible con formatos de salida de texto, markdown y JSON.
  • Herramienta analyze_heap_time_series:
    • Analiza múltiples perfiles de heap a lo largo del tiempo para identificar tendencias de crecimiento de memoria y posibles fugas.
    • Requiere al menos 3 perfiles de heap proporcionados en orden cronológico.
    • Calcula tasas de crecimiento (bytes, porcentaje, MB por minuto).
    • Identifica tipos de objetos con tendencia con indicadores direccionales (📈 aumentando, 📉 disminuyendo, ➡️ estable).
    • Admite etiquetas personalizadas para cada punto de tiempo o genera etiquetas predeterminadas automáticamente.
    • Compatible con formatos de salida de texto, markdown y JSON.

Instalación (como biblioteca/herramienta)

Puede instalar este paquete directamente usando go install:

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

Esto instalará el ejecutable pprof-analyzer-mcp en su directorio $GOPATH/bin o $HOME/go/bin. Asegúrese de que este directorio esté en el PATH de su sistema para ejecutar el comando directamente.

Compilación desde el código fuente

Asegúrese de tener un entorno Go instalado (se recomienda Go 1.18 o superior).

En el directorio raíz del proyecto (pprof-analyzer-mcp), ejecute:

go build

Esto generará un archivo ejecutable llamado pprof-analyzer-mcp (o pprof-analyzer-mcp.exe en Windows) en el directorio actual.

Usando go install (recomendado)

También puede usar go install para instalar el ejecutable en su directorio $GOPATH/bin o $HOME/go/bin. Esto le permite ejecutar pprof-analyzer-mcp directamente desde la línea de comandos (si el directorio se agrega al variable de entorno PATH de su sistema).

# 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

Ejecutar con Docker

Usar Docker es una forma conveniente de ejecutar el servidor, ya que incluye la dependencia necesaria de Graphviz.

  1. Construir la imagen de Docker: En el directorio raíz del proyecto (donde se encuentra Dockerfile), ejecute:

    docker build -t pprof-analyzer-mcp .

  2. Ejecutar el contenedor de Docker:

    docker run -i --rm pprof-analyzer-mcp
    • La bandera -i mantiene abierto el STDIN, lo cual es necesario para el transporte stdio utilizado por este servidor MCP.
    • La bandera --rm elimina automáticamente el contenedor cuando sale.

  3. Configurar el cliente MCP para Docker: Para conectar su cliente MCP (como Roo Cline) al servidor que se ejecuta dentro de Docker, actualice su .roo/mcp.json:

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

    Asegúrese de que la imagen pprof-analyzer-mcp se haya construido localmente antes de que el cliente intente ejecutar este comando.

Lanzamiento (automatizado mediante GitHub Actions)

Este proyecto utiliza GoReleaser y GitHub Actions para automatizar el proceso de lanzamiento. Los lanzamientos se activan automáticamente cuando se envía una etiqueta de Git que coincida con el patrón v* (por ejemplo, v0.1.0, v1.2.3) al repositorio.

Lista de verificación previa al lanzamiento:

Antes de crear una etiqueta de lanzamiento, asegúrese de:

  • ✅ Todas las pruebas pasan: go test ./...
  • ✅ El código compila correctamente: go build
  • ✅ La documentación está actualizada (README, CHANGELOG, etc.)
  • ✅ Los mensajes de confirmación siguen el formato de Conventional Commits

Pasos para el lanzamiento:

  1. Realizar cambios: Desarrolle nuevas funciones o corrija errores.
  2. Confirmar cambios: Confirme sus cambios usando el formato de Conventional Commits (por ejemplo, feat: ..., fix: ..., docs: ...). Esto es importante para la generación automática de changelog. 
    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. Empujar cambios: Empuje sus confirmaciones a la rama principal en GitHub. 
    git push origin main
  4. Ejecutar pruebas previas al lanzamiento: Opcionalmente, ejecute pruebas localmente antes de etiquetar: 
    go test ./... -v
go build -v
  5. Crear y empujar la etiqueta: Cuando esté listo para lanzar, cree una nueva etiqueta de Git y empújela a GitHub. 
    # Example: Create tag v0.2.0
git tag v0.2.0

# Push the tag to GitHub
git push origin v0.2.0
  6. Lanzamiento automático: Empujar la etiqueta activará la acción de GitHub GoReleaser definida en .github/workflows/release.yml. Esta acción:
    • Construirá binarios para Linux, macOS y Windows (amd64 y arm64).
    • Generará un changelog basado en Conventional Commits desde la última etiqueta.
    • Creará una nueva Release de GitHub con el changelog y adjuntará los binarios compilados y sumas de verificación como activos.

Monitoreo del lanzamiento:

Puede ver el progreso del flujo de trabajo de lanzamiento en la pestaña "Actions" del repositorio de GitHub. Una vez completado, la release estará disponible en:

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

Configuración del cliente MCP

Este servidor utiliza el protocolo de transporte stdio. Debe configurarlo en su cliente MCP (por ejemplo, la extensión Roo Cline para VS Code).

Normalmente, esto implica agregar la siguiente configuración al archivo .roo/mcp.json en la raíz de su proyecto:

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

Nota: Ajuste el valor de command según su método de compilación (go build o go install) y la ubicación real del ejecutable. Asegúrese de que el cliente MCP pueda encontrar y ejecutar este comando.

Después de la configuración, recargue o reinicie su cliente MCP, y debería conectarse automáticamente al servidor PprofAnalyzer.

Dependencias

  • Graphviz: La herramienta generate_flamegraph requiere Graphviz para generar gráficos de llama SVG (el comando go tool pprof llama a dot al generar SVG). Asegúrese de que Graphviz esté instalado en su sistema y que el comando dot esté disponible en el variable de entorno PATH de su sistema.

    Instalación de Graphviz:

    • macOS (usando 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 (usando Chocolatey): 
      choco install graphviz
    • Otros sistemas: Consulte la página oficial de descarga de Graphviz.

Ejemplos de uso (a través del cliente MCP)

Una vez que el servidor esté conectado, puede llamar a las herramientas analyze_pprof y generate_flamegraph usando URIs file://, http:// o https:// para el archivo de perfil.

Ejemplo: Analizar perfil de CPU (formato de texto, Top 5)

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

Ejemplo: Analizar perfil de heap (formato Markdown, Top 10)

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

Ejemplo: Analizar perfil de goroutine (formato de texto, Top 5)

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

Ejemplo: Generar gráfico de llama para perfil de 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"
  }
}

Ejemplo: Generar gráfico de llama para perfil de heap (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"
  }
}

Ejemplo: Analizar perfil de CPU (formato JSON, Top 3)

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

Ejemplo: Analizar perfil de CPU (formato JSON de gráfico de llama predeterminado)

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

Ejemplo: Analizar perfil de heap (formato JSON de gráfico de llama explícito)

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

Ejemplo: Analizar perfil de CPU remoto (desde URL HTTP)

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

Ejemplo: Analizar perfil de CPU en línea (desde URL Raw de GitHub)

{
  "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
  }
}

Ejemplo: Generar gráfico de llama para perfil de heap en línea (desde URL Raw de GitHub)

{
  "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"
  }
}

Ejemplo: Abrir interfaz interactiva de pprof para perfil de CPU en línea (solo 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
  }
}

Ejemplo: Detectar fugas de memoria entre dos perfiles de heap

{
  "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
  }
}

Ejemplo: Desconectar una sesión de pprof

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

Mejoras futuras (TODO)

  • Agregar manejo de tipos MIME en los resultados de MCP basado en output_format.
  • Agregar manejo de errores más robusto y control de nivel de registro.
  • Agregar pruebas de integración para interacciones de herramientas MCP de extremo a extremo.
  • Optimizaciones de rendimiento para archivos de perfil grandes (>1 GB).

Completado recientemente (v0.3.0)

  • ✅ Implementar gráficos de llama diferenciales para visualizar cambios entre perfiles. (Hecho - herramienta compare_profiles)
  • ✅ Agregar análisis de series temporales para perfiles de memoria para rastrear el crecimiento a lo largo de múltiples instantáneas. (Hecho - herramienta analyze_heap_time_series)
  • ✅ Agregar CI/CD automatizado con GitHub Actions probando en cada PR.
  • ✅ Implementar la lógica de análisis completa para perfiles mutex, block. (Hecho en v0.2.0)
  • ✅ Implementar el formato de salida json para tipos de perfil mutex, block. (Hecho en v0.2.0)
  • ✅ Migrado al Model Context Protocol Go SDK oficial.
  • ✅ Considerar soporte para URIs remotos de archivos pprof (p. ej., http://, https://). (Hecho en v0.2.0)
  • ✅ Implementar la lógica de análisis completa para perfiles allocs. (Hecho en v0.2.0)
  • ✅ Implementar el formato de salida json para el tipo de perfil allocs. (Hecho en v0.2.0)
  • ✅ Agregar capacidades de detección de fugas de memoria. (Hecho en v0.2.0)