Repolode
Enviar
benfred

benfred/py-spy

Profiler por amostragem para programas Python, que se conecta a processos em execução sem modificar o código nem reiniciá-los.

Ver no GitHub
Estrelas
15,628
Forks
560
Issues abertas
236
Último commit
há 9 horas

O que é?

O py-spy permite ver onde um programa Python em execução está gastando tempo. Ele coleta amostras do processo-alvo externamente, sem precisar alterar o código, adicionar imports ou reiniciar o programa. Escrito em Rust, ele roda em um processo separado daquele que está sendo analisado, mantendo a sobrecarga baixa o suficiente para uso em serviços de produção.

A ferramenta tem três subcomandos. `record` grava perfis nos formatos SVG de flame graph, speedscope ou raw; `top` mostra uma visão ao vivo, atualizada continuamente, das funções que mais consomem tempo; e `dump` imprime as pilhas de chamadas atuais de todas as threads, opcionalmente com variáveis locais. Há opções adicionais para configurar a taxa de amostragem, coletar amostras apenas enquanto o GIL estiver ativo, incluir frames de extensões nativas em C/C++ ou Cython e acompanhar subprocessos, como workers de multiprocessing ou gunicorn.

O py-spy roda em Linux, macOS, Windows e FreeBSD e oferece suporte a uma ampla variedade de versões do CPython. No Linux, conectar-se a um PID existente geralmente exige root ou configurações de ptrace menos restritivas. No Docker ou Kubernetes, o contêiner precisa da capability SYS_PTRACE.

Recursos principais

  • 01Conecta-se a processos Python em execução pelo PID, sem alterações no código ou reinicializações.
  • 02Gera flame graphs em SVG, perfis speedscope ou dados raw.
  • 03Oferece uma visão `top` ao vivo das funções que mais consomem tempo.
  • 04Exibe a pilha de chamadas de todas as threads, com opção de incluir variáveis locais.
  • 05Pode filtrar threads que estão com o GIL e analisar extensões nativas.
  • 06Acompanha processos filhos, como multiprocessing ou workers do gunicorn.

Casos de uso

  • Encontrar funções lentas em um serviço Python de produção sem fazer novo deploy.
  • Investigar um processo travado exibindo as pilhas atuais de suas threads.
  • Analisar um script iniciando-o com py-spy record.
  • Identificar gargalos de CPU em extensões Cython ou C junto com frames Python.

Início rápido

  1. 1

    Instale o binário pré-compilado pelo PyPI

    pip install py-spy
  2. 2

    Faça o profiling de um processo em execução e gere um flame graph

    py-spy record -o profile.svg --pid 12345
  3. 3

    Veja um resumo ao vivo, no estilo do top, de um processo em execução

    py-spy top --pid 12345

Antes de usar

  • No Linux, geralmente é necessário ter permissões de root para fazer o profiling de outro processo.
  • No OSX, é sempre necessário ter permissões de root, e o System Integrity Protection bloqueia o profiling do /usr/bin/python incluído no sistema.
  • O profiling de extensões nativas via --native só está disponível em algumas combinações de plataforma e arquitetura.

Tópicos

#profiling#performance-analysis#python#debugging#flame-graph#rust#profiler

Perguntas frequentes

O que é py-spy?
Profiler por amostragem para programas Python, que se conecta a processos em execução sem modificar o código nem reiniciá-los. O py-spy permite ver onde um programa Python em execução está gastando tempo. Ele coleta amostras do processo-alvo externamente, sem precisar alterar o código, adicionar imports ou reiniciar o programa. Escrito em Rust, ele roda em um processo separado daquele que está sendo analisado, mantendo a sobrecarga baixa o suficiente para uso em serviços de produção.
py-spy é gratuito? Qual é a licença?
py-spy é open source sob a licença MIT. Confira os termos da licença antes de usá-lo em produtos comerciais.
py-spy ainda é mantido?
Manutenção ativa. O último commit de py-spy foi em 6 de nov. de 2026.
Para que posso usar py-spy?
Encontrar funções lentas em um serviço Python de produção sem fazer novo deploy. Investigar um processo travado exibindo as pilhas atuais de suas threads. Analisar um script iniciando-o com py-spy record. Identificar gargalos de CPU em extensões Cython ou C junto com frames Python.
Como instalar py-spy?
Instale o binário pré-compilado pelo PyPI: pip install py-spy Faça o profiling de um processo em execução e gere um flame graph: py-spy record -o profile.svg --pid 12345 Veja um resumo ao vivo, no estilo do top, de um processo em execução: py-spy top --pid 12345
Onde consigo py-spy?
O código-fonte e as instruções de instalação estão no GitHub: https://github.com/benfred/py-spy

Resumo gerado por IA a partir do README do projeto. As estatísticas do GitHub são atualizadas diariamente.

Projetos relacionados