Pprof Analyzer

Analise perfis de desempenho pprof do Go (CPU, heap, goroutine, etc.) e gere flamegraphs.

GitHub
50
Experimente este MCPPatrocinado

Documentação

简体中文 | English

Pprof Analyzer MCP Server

smithery badge Build Status License Go Version GoDoc

Este é um servidor Model Context Protocol (MCP) implementado em Go, fornecendo uma ferramenta para analisar perfis de desempenho pprof do Go. Construído com o Model Context Protocol Go SDK oficial.

Recursos

  • Ferramenta analyze_pprof:
    • Analisa o arquivo pprof do Go especificado e retorna resultados de análise serializados (por exemplo, lista Top N ou JSON de flame graph).
    • Tipos de Perfil Suportados:
      • cpu: Analisa o consumo de tempo de CPU durante a execução do código para encontrar pontos críticos.
      • heap: Analisa o uso atual de memória (alocações de heap) para encontrar objetos e funções com alto consumo de memória. Aprimorado com contagem de objetos, local de alocação e informações de tipo.
      • goroutine: Exibe stack traces de todas as goroutines atuais, usado para diagnosticar deadlocks, vazamentos ou uso excessivo de goroutines.
      • allocs: Analisa alocações de memória (incluindo as liberadas) durante a execução do programa para localizar código com alocações frequentes. Fornece informações detalhadas sobre o local de alocação e contagem de objetos.
      • mutex: Analisa contenção em mutexes para encontrar locks que causam bloqueio. Fornece estatísticas detalhadas incluindo contagens de contenção, tempos de atraso e porcentagens.
      • block: Analisa operações que causam bloqueio de goroutines (por exemplo, esperas em canais, chamadas de sistema). Fornece estatísticas abrangentes de bloqueio com cálculos de atraso médio.
    • Formatos de Saída Suportados: text, markdown, json (lista Top N), flamegraph-json (dados hierárquicos de flame graph, padrão).
      • text, markdown: Texto legível ou formato Markdown.
      • json: Gera resultados Top N em formato JSON estruturado (implementado para cpu, heap, goroutine, allocs, mutex, block).
      • flamegraph-json: Gera dados hierárquicos de flame graph em formato JSON, compatível com d3-flame-graph (implementado para cpu, heap, allocs, formato padrão). A saída é compacta.
    • Número configurável de resultados Top N (top_n, padrão 5, efetivo para os formatos text, markdown, json).
  • Ferramenta generate_flamegraph:
    • Usa go tool pprof para gerar um flame graph (formato SVG) para o arquivo pprof especificado, salva-o no caminho especificado e retorna o caminho e o conteúdo SVG.
    • Tipos de Perfil Suportados: cpu, heap, allocs, goroutine, mutex, block.
    • Requer que o usuário especifique o caminho do arquivo SVG de saída.
    • Importante: Este recurso depende do Graphviz estar instalado.
  • Ferramenta open_interactive_pprof (somente macOS):
    • Tenta iniciar a interface web interativa do go tool pprof em segundo plano para o arquivo pprof especificado. Usa a porta :8081 por padrão se http_address não for fornecida.
    • Retorna o ID do Processo (PID) do processo pprof em segundo plano após a inicialização bem-sucedida.
    • Somente macOS: Esta ferramenta funcionará apenas no macOS.
    • Dependências: Requer que o comando go esteja disponível no PATH do sistema.
    • Limitações: Erros do processo pprof em segundo plano não são capturados pelo servidor. Arquivos temporários baixados de URLs remotas não são limpos automaticamente até que o processo seja encerrado (manualmente via disconnect_pprof_session ou quando o servidor MCP sair).
  • Ferramenta detect_memory_leaks:
    • Compara dois snapshots de perfil de heap para identificar possíveis vazamentos de memória.
    • Analisa o crescimento de memória por tipo de objeto e local de alocação.
    • Fornece estatísticas detalhadas sobre o crescimento de memória, incluindo mudanças absolutas e percentuais.
    • Limite de crescimento e limite de resultados configuráveis.
    • Ajuda a identificar vazamentos de memória comparando perfis obtidos em diferentes momentos.
  • Ferramenta disconnect_pprof_session:
    • Tenta encerrar um processo pprof em segundo plano iniciado anteriormente por open_interactive_pprof, usando seu PID.
    • Envia um sinal de Interrupção primeiro e, em seguida, um sinal Kill se a Interrupção falhar.
  • Ferramenta compare_profiles:
    • Compara dois arquivos de perfil (por exemplo, baseline vs. alvo) para identificar regressões ou melhorias de desempenho.
    • Suporta todos os tipos de perfil (cpu, heap, allocs, mutex, block).
    • Fornece estatísticas detalhadas de diff incluindo funções melhoradas/regredidas, funções adicionadas/removidas.
    • Indicadores visuais: 🔴 regressão, 🟢 melhoria, 🆕 adicionado, ❌ removido.
    • Suporta formatos de saída texto, markdown e JSON.
  • Ferramenta analyze_heap_time_series:
    • Analisa múltiplos perfis de heap ao longo do tempo para identificar tendências de crescimento de memória e possíveis vazamentos.
    • Requer pelo menos 3 perfis de heap fornecidos em ordem cronológica.
    • Calcula taxas de crescimento (bytes, porcentagem, MB por minuto).
    • Identifica tipos de objetos em tendência com indicadores direcionais (📈 aumentando, 📉 diminuindo, ➡️ estável).
    • Suporta rótulos personalizados para cada ponto no tempo ou gera automaticamente rótulos padrão.
    • Suporta formatos de saída texto, markdown e JSON.

Instalação (Como Biblioteca/Ferramenta)

Você pode instalar este pacote diretamente usando go install:

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

Isso instalará o executável pprof-analyzer-mcp no diretório $GOPATH/bin ou $HOME/go/bin. Certifique-se de que este diretório esteja no PATH do seu sistema para executar o comando diretamente.

Compilando a partir do Código Fonte

Certifique-se de ter um ambiente Go instalado (Go 1.18 ou superior recomendado).

No diretório raiz do projeto (pprof-analyzer-mcp), execute:

go build

Isso gerará um arquivo executável chamado pprof-analyzer-mcp (ou pprof-analyzer-mcp.exe no Windows) no diretório atual.

Usando go install (Recomendado)

Você também pode usar go install para instalar o executável no diretório $GOPATH/bin ou $HOME/go/bin. Isso permite executar pprof-analyzer-mcp diretamente da linha de comando (se o diretório for adicionado à variável de ambiente PATH do seu 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

Executando com Docker

Usar Docker é uma maneira conveniente de executar o servidor, pois ele inclui a dependência necessária do Graphviz.

  1. Construir a Imagem Docker: No diretório raiz do projeto (onde o Dockerfile está localizado), execute:

    docker build -t pprof-analyzer-mcp .

  2. Executar o Contêiner Docker:

    docker run -i --rm pprof-analyzer-mcp
    • A flag -i mantém o STDIN aberto, o que é necessário para o transporte stdio usado por este servidor MCP.
    • A flag --rm remove automaticamente o contêiner quando ele sai.

  3. Configurar o Cliente MCP para Docker: Para conectar seu cliente MCP (como Roo Cline) ao servidor em execução dentro do Docker, atualize seu .roo/mcp.json:

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

    Certifique-se de que a imagem pprof-analyzer-mcp foi construída localmente antes que o cliente tente executar este comando.

Release (Automatizado via GitHub Actions)

Este projeto usa GoReleaser e GitHub Actions para automatizar o processo de release. As releases são acionadas automaticamente quando uma tag Git correspondente ao padrão v* (por exemplo, v0.1.0, v1.2.3) é enviada para o repositório.

Checklist Pré-release:

Antes de criar uma tag de release, certifique-se de:

  • ✅ Todos os testes passam: go test ./...
  • ✅ O código compila com sucesso: go build
  • ✅ A documentação está atualizada (README, CHANGELOG, etc.)
  • ✅ As mensagens de commit seguem o formato Conventional Commits

Etapas da Release:

  1. Fazer Alterações: Desenvolva novos recursos ou corrija bugs.
  2. Fazer Commit das Alterações: Faça commit das suas alterações usando o formato Conventional Commits (por exemplo, feat: ..., fix: ..., docs: ...). Isso é importante para a geração automática do 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. Enviar Alterações: Envie seus commits para o branch principal no GitHub. 
    git push origin main
  4. Executar Testes Pré-release: Opcionalmente, execute testes localmente antes de criar a tag: 
    go test ./... -v
go build -v
  5. Criar e Enviar Tag: Quando estiver pronto para lançar, crie uma nova tag Git e envie-a para o GitHub. 
    # Example: Create tag v0.2.0
git tag v0.2.0

# Push the tag to GitHub
git push origin v0.2.0
  6. Release Automática: Enviar a tag acionará a GitHub Action GoReleaser definida em .github/workflows/release.yml. Esta ação irá:
    • Compilar binários para Linux, macOS e Windows (amd64 & arm64).
    • Gerar um changelog com base em Conventional Commits desde a última tag.
    • Criar uma nova GitHub Release com o changelog e anexar os binários compilados e checksums como assets.

Monitorando a Release:

Você pode visualizar o progresso do workflow de release na aba "Actions" do repositório GitHub. Quando concluído, a release estará disponível em:

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

Configurando o Cliente MCP

Este servidor usa o protocolo de transporte stdio. Você precisa configurá-lo no seu cliente MCP (por exemplo, extensão Roo Cline para VS Code).

Normalmente, isso envolve adicionar a seguinte configuração ao arquivo .roo/mcp.json na raiz do seu projeto:

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

Nota: Ajuste o valor de command com base no seu método de compilação (go build ou go install) e na localização real do executável. Certifique-se de que o cliente MCP possa encontrar e executar este comando.

Após a configuração, recarregue ou reinicie seu cliente MCP, e ele deverá se conectar automaticamente ao servidor PprofAnalyzer.

Dependências

  • Graphviz: A ferramenta generate_flamegraph requer Graphviz para gerar flame graphs em SVG (o comando go tool pprof chama dot ao gerar SVG). Certifique-se de que o Graphviz esteja instalado no seu sistema e que o comando dot esteja disponível na variável de ambiente PATH do seu sistema.

    Instalando o 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
    • Outros Sistemas: Consulte a página oficial de download do Graphviz.

Exemplos de Uso (via Cliente MCP)

Depois que o servidor estiver conectado, você pode chamar as ferramentas analyze_pprof e generate_flamegraph usando URIs file://, http:// ou https:// para o arquivo de perfil.

Exemplo: Analisar Perfil de CPU (formato Texto, Top 5)

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

Exemplo: Analisar 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"
  }
}

Exemplo: Analisar Perfil de Goroutine (formato Texto, Top 5)

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

Exemplo: Gerar Flame Graph 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"
  }
}

Exemplo: Gerar Flame Graph 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"
  }
}

Exemplo: Analisar 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"
  }
}

Exemplo: Analisar Perfil de CPU (formato JSON de Flame Graph padrão)

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

Exemplo: Analisar Perfil de Heap (formato JSON de Flame Graph explícito)

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

Exemplo: Analisar Perfil de CPU Remoto (de URL HTTP)

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

Exemplo: Analisar Perfil de CPU Online (de URL Raw do 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
  }
}

Exemplo: Gerar Flame Graph para Perfil de Heap Online (de URL Raw do 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"
  }
}

Exemplo: Abrir UI Interativa do Pprof para Perfil de CPU Online (somente 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
  }
}

Exemplo: Detectar Vazamentos de Memória Entre Dois Perfis 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
  }
}

Exemplo: Desconectar uma Sessão Pprof

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

Melhorias Futuras (TODO)

  • Adicionar tratamento de tipo MIME nos resultados MCP com base em output_format.
  • Adicionar tratamento de erros mais robusto e controle de nível de logging.
  • Adicionar testes de integração para interações ponta a ponta das ferramentas MCP.
  • Otimizações de desempenho para arquivos de perfil grandes (>1GB).

Recentemente Concluído (v0.3.0)

  • ✅ Implementar gráficos de chama diferenciais para visualizar mudanças entre perfis. (Concluído - ferramenta compare_profiles)
  • ✅ Adicionar análise de séries temporais para perfis de memória para rastrear crescimento ao longo de múltiplos snapshots. (Concluído - ferramenta analyze_heap_time_series)
  • ✅ Adicionar CI/CD automatizado com GitHub Actions testando em cada PR.
  • ✅ Implementar lógica de análise completa para perfis mutex, block. (Concluído em v0.2.0)
  • ✅ Implementar formato de saída json para tipos de perfil mutex, block. (Concluído em v0.2.0)
  • ✅ Migrado para o Model Context Protocol Go SDK oficial.
  • ✅ Considerar suporte a URIs de arquivos pprof remotos (por exemplo, http://, https://). (Concluído em v0.2.0)
  • ✅ Implementar lógica de análise completa para perfis allocs. (Concluído em v0.2.0)
  • ✅ Implementar formato de saída json para o tipo de perfil allocs. (Concluído em v0.2.0)
  • ✅ Adicionar capacidades de detecção de vazamento de memória. (Concluído em v0.2.0)