traceback no Python: erros e pilha

Quando uma exceção não é tratada, o Python mostra uma sequência de arquivos, linhas e chamadas que levou ao erro. Essa sequência é o traceback. O módulo traceback no Python permite capturar, formatar, limitar, armazenar e exibir essas informações de maneira controlada, sendo útil em CLIs, APIs, tarefas assíncronas, sistemas de logging e ferramentas de diagnóstico.

Neste guia, você aprenderá a usar print_exc(), format_exc(), extract_tb(), TracebackException, StackSummary e clear_frames(). O conteúdo complementa nossos artigos sobre depuração com pdb, introspecção com inspect, vazamentos de memória e PermissionError.

O que existe em um traceback

Uma exceção guarda uma referência ao objeto de traceback em __traceback__. Cada entrada representa um frame da pilha de chamadas e contém arquivo, número da linha, nome da função e contexto do código-fonte.

def dividir(a, b):
    return a / b

def executar():
    return dividir(10, 0)

try:
    executar()
except ZeroDivisionError as erro:
    print(type(erro.__traceback__))

Os frames formam uma cadeia por meio de tb_next. Em geral, não é necessário percorrê-la manualmente porque o módulo oferece APIs de extração e formatação.

Imprimir a exceção atual com print_exc()

Dentro de um bloco except, traceback.print_exc() reproduz uma saída semelhante à do interpretador.

import traceback

try:
    executar()
except Exception:
    traceback.print_exc()

Por padrão, a saída vai para sys.stderr. É possível redirecioná-la para um arquivo ou fluxo:

import sys

try:
    executar()
except Exception:
    traceback.print_exc(file=sys.stdout)

Use esse recurso em ferramentas interativas. Em aplicações de produção, prefira integrar o erro ao sistema de logging, preservando contexto estruturado.

Obter o traceback como string

format_exc() retorna uma única string em vez de imprimir imediatamente.

try:
    executar()
except Exception:
    texto = traceback.format_exc()
    enviar_para_monitoramento(texto)

Isso facilita salvar em um banco, anexar a um relatório ou adicionar a uma resposta administrativa. Não envie tracebacks completos para usuários finais, pois eles podem revelar caminhos, nomes internos, consultas e outros detalhes sensíveis.

Usar logging.exception()

O módulo logging já possui integração com tracebacks. Dentro de um except, logger.exception() registra a mensagem e a exceção atual.

import logging

logger = logging.getLogger(__name__)

try:
    executar()
except Exception:
    logger.exception("Falha ao executar operação")

A documentação oficial de logging explica handlers, formatadores e níveis. Evite registrar a mesma exceção em várias camadas, pois isso multiplica eventos idênticos e dificulta métricas.

Limitar a quantidade de frames

As funções de impressão e formatação aceitam limit. Um valor positivo mantém os primeiros frames selecionados pela API, enquanto um valor negativo mostra os últimos.

try:
    executar()
except Exception:
    traceback.print_exc(limit=-3)

Os últimos frames costumam estar mais próximos do ponto da falha. Contudo, remover contexto demais pode ocultar a origem da chamada. Escolha o limite de acordo com o ambiente e mantenha uma versão completa em diagnósticos internos quando necessário.

Formatar somente a exceção

Quando a pilha não é necessária, format_exception_only() produz o tipo e a mensagem.

try:
    executar()
except Exception as erro:
    linhas = traceback.format_exception_only(erro)
    mensagem = "".join(linhas)
    print(mensagem)

Erros de sintaxe recebem informações adicionais sobre linha e posição. Desde versões recentes do Python, notas adicionadas com add_note() também aparecem na formatação.

Extrair dados estruturados

extract_tb() transforma o traceback em um StackSummary, composto por objetos FrameSummary.

try:
    executar()
except Exception as erro:
    resumo = traceback.extract_tb(erro.__traceback__)
    for frame in resumo:
        print(frame.filename, frame.lineno, frame.name, frame.line)

Esse formato é melhor para gerar JSON, agrupar erros por arquivo e linha ou ocultar diretórios internos. Normalize caminhos antes de enviar dados a serviços externos.

Capturar a pilha sem uma exceção

extract_stack() e format_stack() analisam a pilha atual. São úteis para descobrir quem chamou uma função ou diagnosticar bloqueios.

def funcao_sensivel():
    pilha = traceback.extract_stack(limit=-5)
    for frame in pilha:
        print(frame.name, frame.lineno)

Capturar pilhas em cada requisição pode ter custo significativo. Use amostragem ou habilite o diagnóstico apenas quando houver uma condição anormal.

TracebackException para guardar o erro

Manter a própria exceção pode reter frames e todos os objetos referenciados por variáveis locais. TracebackException captura informações suficientes para formatar o erro depois sem preservar o grafo completo.

from traceback import TracebackException

try:
    executar()
except Exception as erro:
    capturado = TracebackException.from_exception(
        erro,
        limit=-10,
        capture_locals=False,
        compact=True,
    )

texto = "".join(capturado.format())

A documentação oficial de traceback recomenda essa classe quando o erro precisa ser armazenado ou transportado para formatação posterior.

Cuidado com capture_locals

capture_locals=True inclui representações das variáveis locais. Isso ajuda na investigação, mas pode expor senhas, tokens, dados pessoais e objetos muito grandes.

capturado = TracebackException.from_exception(
    erro,
    capture_locals=True,
)

Use somente em ambientes controlados, aplique mascaramento e limite o acesso. Mesmo uma chamada a repr() pode ser cara ou produzir uma saída enorme.

Exceções encadeadas

Quando uma exceção ocorre durante o tratamento de outra, o Python mantém __context__. A sintaxe raise NovaExcecao() from original define uma causa explícita em __cause__.

try:
    int("abc")
except ValueError as original:
    raise RuntimeError("Configuração inválida") from original

As funções de traceback exibem a cadeia quando chain=True, que é o padrão. Esse histórico ajuda a separar a falha de baixo nível da mensagem de domínio.

ExceptionGroup

Em operações concorrentes, várias falhas podem ser agrupadas em ExceptionGroup. TracebackException expõe as exceções aninhadas e permite limitar profundidade e largura.

capturado = TracebackException.from_exception(
    erro,
    max_group_width=8,
    max_group_depth=4,
)

Esses limites evitam relatórios gigantes quando um lote produz centenas de erros semelhantes.

Liberar referências de frames

Se você trabalhar diretamente com o traceback, chame clear_frames() quando terminar para remover variáveis locais dos frames.

try:
    executar()
except Exception as erro:
    tb = erro.__traceback__
    try:
        processar(traceback.extract_tb(tb))
    finally:
        traceback.clear_frames(tb)

Isso reduz o risco de retenção de memória em workers persistentes. Ainda assim, a opção preferida para armazenamento prolongado é converter a exceção em TracebackException.

Sanitizar caminhos e mensagens

Um traceback pode revelar a estrutura do servidor, nomes de usuários, parâmetros e trechos de código. Antes de enviá-lo a terceiros, remova prefixos de diretório, filtre mensagens e aplique uma política de dados.

from pathlib import Path

def frame_publico(frame):
    return {
        "arquivo": Path(frame.filename).name,
        "linha": frame.lineno,
        "funcao": frame.name,
    }

Para o usuário final, retorne um identificador de incidente e uma mensagem simples. O relatório completo deve ficar protegido em logs internos.

Traceback não substitui depuração

A pilha mostra onde o erro se propagou, mas não explica necessariamente por que o estado ficou inválido. Combine tracebacks com logs estruturados, métricas, testes reproduzíveis e o depurador pdb. Para falhas nativas, travamentos ou deadlocks, módulos como faulthandler podem oferecer informações adicionais.

Erros frequentes

• Usar format_exc() fora do bloco except.
• Mostrar tracebacks completos ao visitante de uma aplicação web.
• Capturar variáveis locais contendo segredos.
• Guardar exceções e frames por tempo indefinido.
• Registrar o mesmo erro em todas as camadas.
• Remover tantos frames que a origem da chamada desaparece.
• Transformar qualquer erro esperado em evento crítico.
• Ignorar exceções encadeadas.

Boas práticas

• Use logger.exception() dentro de except.
• Converta para TracebackException quando precisar guardar o diagnóstico.
• Desative capture_locals por padrão.
• Sanitize caminhos e dados antes de exportar.
• Limite grupos e pilhas muito grandes.
• Libere frames quando trabalhar com objetos reais.
• Mantenha um ID de correlação entre usuário e log.
• Teste a formatação com exceções encadeadas e grupos.

Conclusão

O módulo traceback no Python transforma a pilha de exceções em dados que podem ser impressos, formatados, filtrados e armazenados. As funções de nível superior resolvem diagnósticos imediatos, enquanto TracebackException, StackSummary e FrameSummary atendem sistemas estruturados e persistentes.

O uso seguro exige equilíbrio: contexto suficiente para investigar, mas sem vazar informações nem manter grandes grafos de objetos vivos. Com logging centralizado, sanitização, limites e liberação de frames, tracebacks tornam-se uma ferramenta operacional confiável em vez de apenas uma mensagem vermelha no terminal.