Como encontrar um vazamento de memória com snapshots do tracemalloc

Objetivo

Atribuir o crescimento de memória de um processo Python de longa duração às linhas de código que a alocam, usando apenas a biblioteca padrão.

Pré-requisitos

Uma reprodução do problema (um loop, uma sequência de requisições ou um job após o qual a memória residente fica maior do que antes), a possibilidade de reiniciar o processo com uma variável de ambiente ou uma flag, e Python 3.

Passos

1. Inicie o rastreamento antes de o código suspeito ser executado: PYTHONTRACEMALLOC=25, -X tracemalloc=25 ou tracemalloc.start(25) o mais cedo possível. O número é a profundidade do traceback armazenado por alocação; segundo a documentação, o padrão é um único frame, que apenas indica a linha que alocou, e são necessários mais frames para agrupar as estatísticas por traceback completo.
2. Faça o aquecimento: execute a operação algumas vezes para que imports, caches e pools de conexões cheguem a um estado estável e, em seguida, tire s1 = tracemalloc.take_snapshot().
3. Execute a operação um número conhecido de vezes, por exemplo 100, e tire s2.
4. Filtre o ruído como no exemplo da documentação: s.filter_traces((tracemalloc.Filter(False, "<frozen importlib._bootstrap>"), tracemalloc.Filter(False, "<unknown>"))).
5. Compare: for stat in s2.compare_to(s1, "lineno")[:10]: print(stat). As entradas são ordenadas pela diferença absoluta de tamanho; um vazamento aparece como uma linha cujos size_diff e count_diff escalam com o número de iterações. Execute novamente com a chave "traceback" e imprima stat.traceback.format() para ver quem chegou a essa linha.
6. Confirme com um número diferente de iterações: um vazamento cresce proporcionalmente, enquanto um cache se estabiliza.
7. Para picos, e não para crescimento, envolva o bloco com get_traced_memory() (atual e pico) e reset_peak(), como faz o exemplo da documentação.
8. Persista com snapshot.dump(path) para que outra pessoa possa usar Snapshot.load(path) e inspecionar sem precisar reproduzir o problema.

Resultado esperado

Uma lista curta de linhas de código com o crescimento por iteração e o caminho de chamadas que leva a elas. Os culpados habituais são uma lista ou um dict que recebe itens e nunca é reduzido, um cache sem limite, objetos retidos por uma closure ou por lru_cache em um método, e handlers registrados repetidamente.

Limites e base de verificação

O tracemalloc enxerga as alocações feitas pelos alocadores do Python; a memória que bibliotecas em C alocam diretamente e a fragmentação do heap ficam invisíveis, de modo que o tamanho residente pode crescer sem que o tamanho rastreado cresça. O rastreamento consome memória e CPU, e esse custo aumenta com a profundidade de frames (a documentação oferece get_tracemalloc_memory() para medi-lo); por isso, use-o em uma reprodução e não de forma permanente em produção. O procedimento segue a documentação citada; nenhuma medição é afirmada.