A anatomia de uma linha de log

Nota 2 de 16 · 5 min de leitura

Diante de um log desconhecido, o técnico precisa reconhecer o que é horário, o que identifica a operação e o que descreve o resultado. Essa separação torna a leitura possível mesmo quando o formato é diferente do habitual.

As peças de um registro

Uma linha de exemplo, de uma consulta ao PBM, o programa de benefícios em medicamentos, mostra as peças mais comuns:

2026-10-01 14:32:05.118 -03:00 [ERRO] [PBM] caixa=01 operacao=OP-0001 tentativa=1 Tempo esgotado aguardando resposta (30000 ms)

Cada peça tem uma função:

Data e hora: o trecho 2026-10-01 14:32:05.118 -03:00 localiza o registro no tempo, com os milissegundos e o deslocamento em relação ao UTC;
Nível: o [ERRO] é a classificação que o programa deu à mensagem;
Componente: o [PBM] indica a parte do programa que produziu o registro;
Contexto: o caixa, a operação e a tentativa distinguem essa chamada de outras feitas ao mesmo tempo, e outros formatos trazem o usuário, o processo ou o documento;
Mensagem: descreve a espera esgotada e o limite informado, e pode vir seguida de um código, de um JSON, de um XML ou dos detalhes de uma exceção.

Nem todo log tem todas essas peças. Antes de qualquer filtro, a leitura de algumas linhas completas mostra as regras usadas naquele arquivo.

Os níveis de gravidade

Os nomes mais usados para os níveis são estes:

DEBUG e TRACE: os detalhes técnicos;
INFO: as etapas comuns do funcionamento;
WARN ou AVISO: as condições que merecem atenção;
ERROR ou ERRO: as falhas percebidas;
FATAL ou CRÍTICO: as falhas graves, em geral ligadas à interrupção do componente.

O significado exato depende do programa. Um aviso pode anteceder uma falha, e um erro pode ser tratado por uma nova tentativa que termina bem. O nível ajuda a localizar o trecho, mas a mensagem e a sequência da operação explicam o que aconteceu, e uma linha marcada como ERRO não prova, sozinha, que a operação falhou.

Os registros de várias linhas

Um XML formatado ou uma pilha de chamadas, chamada em inglês de stack trace, pode ocupar várias linhas do mesmo registro. A pilha mostra as chamadas ligadas à exceção e ajuda a localizar o ponto em que o programa percebeu o erro.

Em alguns formatos, cada registro começa com a data e a hora, e as linhas sem esse prefixo continuam o registro anterior. Essa regra precisa ser conferida em cada arquivo, porque há formatos que repetem a data em todas as linhas e arquivos que misturam mensagens sem prefixo.

Uma pesquisa por ERRO ou pela operação pode encontrar só a primeira linha do registro. A leitura do bloco completo vem antes da cópia do trecho, porque as linhas seguintes podem trazer justamente o código ou a resposta de que a análise precisa.

Os formatos comuns

Texto livre: a mensagem é uma frase escrita pelo programa;
Chave e valor: campos como terminal=01 deixam o contexto explícito;
JSON por linha: cada linha contém um valor JSON completo, em geral um objeto;
Mensagens trocadas: marcadores como Enviado e Recebido antecedem o conteúdo;
Texto posicional: a posição de cada coluna define o significado dela, e a leitura depende do layout.

O alcance dos identificadores

Um número de pedido identifica a operação comercial, uma tentativa identifica uma execução dessa operação, e um identificador de requisição pode identificar só uma chamada ao fornecedor. Esses campos não se substituem. Duas chamadas para o pedido PED-0001 podem ser uma consulta e uma confirmação, ou duas tentativas da mesma etapa.

A leitura confere onde o identificador é criado, se ele continua nas respostas e se pode se repetir em outra filial ou depois de um reinício. Quando a numeração é local, a combinação da filial, do terminal, da operação e da tentativa identifica o registro. Sem um campo que ligue dois registros, a associação fica registrada como provável, com a dúvida preservada.

Os sistemas instrumentados podem trazer os campos TraceId e SpanId: o primeiro liga um percurso de processamento, e o segundo, uma etapa desse percurso. A presença desses campos ajuda, e a ausência não significa que o evento não aconteceu.

No suporte

Antes dos filtros, convém reconhecer o início do registro, o horário, o contexto e a mensagem. O mesmo texto de erro pode aparecer em operações diferentes, e uma única operação pode produzir um registro de várias linhas.

Para guardar

O horário, o nível, o componente, o contexto e a mensagem são peças comuns, mas não obrigatórias.
O nível orienta a busca, e a sequência e a mensagem explicam a falha percebida.
Cada arquivo tem a própria regra para os registros de várias linhas.
A extração de uma ocorrência preserva o bloco completo.
Cada identificador tem um alcance, como o pedido, a tentativa ou a requisição.

Um erro aparece seguido de várias linhas sem horário. Essas linhas pertencem ao erro?

Podem pertencer, como acontece em uma pilha de chamadas. A resposta depende do formato: quando cada registro novo começa com a data e a hora, as linhas sem esse prefixo continuam o bloco anterior e são lidas com ele.

Uma linha INFO informa que a operação começou e, depois, surge uma linha ERRO. O nível basta para conhecer o resultado final?

Não. A leitura acompanha a mesma operação e a mesma tentativa até o resultado registrado. O erro pode ter interrompido a operação ou ter sido tratado por outra tentativa, e a classificação isolada não descreve essa sequência.