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 originalAs 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 blocoexcept. - 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 deexcept. - Converta para
TracebackExceptionquando precisar guardar o diagnóstico. - Desative
capture_localspor 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.
