Como ler os logs da sua aplicação (e achar o erro)

Quando uma aplicação para de responder, o log é o primeiro lugar onde olhar. Ele é o diário do processo: tudo o que o seu código imprime e tudo o que o runtime reclama vai parar ali. Saber ler esse diário economiza horas de tentativa e erro.

A dificuldade quase nunca é falta de informação, e sim excesso. Um log de produção tem centenas de linhas, e o erro útil é uma só. Para chegar nela, siga um método fixo, sempre na mesma ordem.

De onde vêm as linhas do log?#

Todo processo tem dois fluxos de saída. O stdout recebe a saída normal: console.log no Node.js, print no Python. O stderr recebe erros: console.error e a mensagem que o runtime imprime quando uma exceção não é tratada.

Em um terminal ou em um painel de hospedagem, os dois aparecem misturados, na ordem em que chegaram. Isso ajuda, porque você vê o que a aplicação estava fazendo logo antes de falhar.

No Node.js, uma exceção não tratada imprime o stack trace no stderr e encerra o processo com código 1, segundo a documentação do process. Uma promise rejeitada sem tratamento (unhandledRejection) é, por padrão, levantada como exceção não capturada. Por isso um await sem try/catch pode derrubar o bot inteiro.

Qual o método para achar o erro?#

Os passos são estes:

1. Vá ao fim do log. O que aconteceu por último é o sintoma atual.
2. Suba até a primeira linha de erro. Procure Error, Exception, Traceback, FATAL ou ECONNREFUSED. Avisos (warn) raramente são a causa.
3. Leia a mensagem inteira. Ela diz o tipo do erro e, quase sempre, o que faltou: um módulo, uma variável, uma porta.
4. Ache a primeira linha do seu código no stack trace. Linhas de node_modules ou de bibliotecas mostram por onde o erro passou. A linha com o caminho do seu arquivo mostra onde o seu código o provocou.
5. Confira o que aconteceu antes. Uma falha de conexão com o banco pode ter começado 30 linhas acima do erro final.

Se a aplicação reinicia várias vezes seguidas, o log guarda cada tentativa, uma depois da outra. Compare a última com a anterior: o erro que se repete é o que importa.

Como ler um stack trace de Node.js?#

Veja um exemplo de exceção não tratada:

/home/app/index.js:12
  const nome = usuario.perfil.nome;
                              ^

TypeError: Cannot read properties of undefined (reading 'nome')
    at buscarNome (/home/app/index.js:12:31)
    at processarMensagem (/home/app/handlers/mensagem.js:8:5)

Node.js v24.0.0

Leia de cima para baixo:

• A linha com ^ aponta o trecho exato do código.
• TypeError: ... é o tipo e a mensagem. Aqui, usuario.perfil é undefined.
• As linhas at são a pilha de chamadas, da mais recente para a mais antiga. A primeira linha com o caminho do seu projeto (/home/app/index.js:12:31) traz arquivo, linha e coluna.
• A última linha mostra a versão do Node.js, útil para confirmar o runtime em uso.

O stack trace do Node mostra o ponto onde o erro foi criado e se estende até o início da execução síncrona, ou até o limite de frames de Error.stackTraceLimit (veja a documentação de erros). Em código assíncrono, algumas chamadas intermediárias podem não aparecer.

Como ler um traceback de Python?#

O Python usa a ordem inversa: a chamada mais recente fica por último.

Traceback (most recent call last):
  File "/home/app/main.py", line 20, in <module>
    iniciar()
  File "/home/app/main.py", line 14, in iniciar
    token = os.environ["TOKEN"]
  File "<frozen os>", line 714, in __getitem__
KeyError: 'TOKEN'

Comece pela última linha: KeyError: 'TOKEN' diz que a variável de ambiente TOKEN não existe. Depois suba para achar a linha do seu código que causou isso (main.py, linha 14). O cabeçalho Traceback (most recent call last) avisa que a chamada mais recente está no fim, como mostra a documentação do módulo traceback.

Quando há duas exceções encadeadas, o Python imprime During handling of the above exception, another exception occurred: entre os blocos. A causa original está no primeiro bloco, e o erro que chegou ao fim está no último.

Quais erros aparecem mais ao subir uma aplicação?#

Se a aplicação cai e volta sem parar, o log mostra o mesmo erro a cada início. É um ciclo de reinício causado por um erro fixo, e o reinício automático só o repete. Leia o guia sobre PM2 e reinício automático para entender esse comportamento.

Como escrever logs que ajudam de verdade?#

Um bom log responde "o que, quando e com qual dado" sem expor segredos.

• Use níveis. info para marcos normais, warn para o que merece atenção, error para falhas. Assim dá para filtrar.
• Inclua contexto. falha ao salvar usuario 4821: timeout ajuda mais que erro.
• Registre o objeto de erro inteiro, não só a mensagem. Sem o stack trace você perde o local da falha.
• Nunca imprima senhas, tokens ou dados pessoais. Um log é lido por mais gente do que você imagina.
• Escreva no stdout e no stderr. Assim você não depende de caminho de arquivo nem de rotação.

Um exemplo mínimo em Node.js:

process.on("unhandledRejection", (motivo) => {
  console.error("unhandledRejection:", motivo);
});

async function salvar(id) {
  try {
    await banco.salvar(id);
    console.log(`usuario ${id} salvo`);
  } catch (erro) {
    console.error(`falha ao salvar usuario ${id}`, erro);
  }
}

Em Python, o módulo logging da biblioteca padrão faz o mesmo, e logging.exception("mensagem") já inclui o traceback.

Como fazer isso na Square Cloud#

Na Square Cloud, os logs da aplicação aparecem em tempo real no painel, na CLI, na extensão do VS Code e no app de celular. Você aplica o mesmo método e acompanha um deploy ou um erro sem abrir terminal em servidor nenhum.

As aplicações rodam em containers isolados. O reinício automático é opcional e vem ligado no deploy pelo painel: ele religa a aplicação quando o processo encerra com erro. Os logs de antes de um restart continuam visíveis, então, depois de um reinício inesperado, suba no log para achar o erro que o causou. Estouro de memória é diferente: a aplicação para e só volta quando você aumenta a RAM e a inicia de novo.

Ao mudar uma variável de ambiente, a alteração vale no próximo restart, sem rebuild: reinicie e releia o log para confirmar. O Cubic, o agente de IA do painel, também lê logs para diagnosticar falhas, sempre a seu pedido. As métricas de CPU, RAM e rede são registradas a cada 5 minutos e guardadas por 24 horas, o que ajuda a cruzar um erro de memória com o consumo real.

Veja os recursos de logs e métricas em recursos da plataforma.