Neste artigo
- O que torna um log debugável?
- O formato: um JSON por linha
- Os campos que não podem faltar
- Nível de log com disciplina
- Do arquivo solto à consulta única
- Onde o log estruturado vale mais na prática
- JSON em log não fica ilegível no terminal?
- Onde entra o identificador da requisição?
- Quanto tempo guardar os logs?
- Registrar dado de usuário no log é seguro?
O log de texto livre guarda a informação no meio da frase, e cada serviço escreve do seu jeito. Quando o bug aparece, a investigação vira scroll e leitura. O log estruturado inverte isso: cada linha é um registro com campos fixos, e achar a causa vira uma consulta por campo em vez de uma busca por palavra.
O log fica debugável quando cada evento é um registro com formato fixo, campos padronizados e nível coerente. O primeiro passo é padronizar a saída, o segundo é definir os campos obrigatórios, e o terceiro é aprender a consultar, o que os comandos essenciais do Linux no dia a dia ajudam a fazer direto no servidor.
O que torna um log debugável?
Um log é debugável quando responde três perguntas sem esforço: o que aconteceu, em qual requisição e com qual resultado. O texto livre depende de quem escreveu a frase, e frases diferentes para o mesmo evento quebram qualquer busca. O registro estruturado garante que o mesmo evento tenha sempre os mesmos campos, então a consulta por nível, por rota ou por usuário funciona em qualquer dia.
O formato: um JSON por linha
O formato mais usado é um objeto JSON por linha, que preserva o texto simples do log e continua legível por máquina. Quase toda linguagem tem biblioteca que emite nesse formato, e o custo de adoção é trocar a interpolação de string por pares de chave e valor na chamada.
{"ts":"2026-03-10T14:02:11Z","level":"error","service":"checkout","request_id":"a1b2c3","user_id":821,"msg":"falha ao gravar pedido","err":"timeout do pagamento"}
Essa linha conta a história completa: quando, onde, quem, o que falhou e por quê. Com texto livre, a mesma informação estaria espalhada em uma frase que mudaria de formato a cada revisão do código.
Os campos que não podem faltar
Quatro campos sustentam a depuração: timestamp com fuso explícito, nível, identificador da requisição e mensagem curta. O identificador da requisição é o mais valioso: ele costura os logs de vários serviços em uma única história, porque entra junto na chamada e é repetido em cada log pela cadeia inteira. Campos de contexto, como usuário e rota, entram por evento, nunca no campo de mensagem.
💡 Dica: a mensagem é um texto curto e estável, e o contexto vai nos campos. Quando a mensagem muda a cada deploy, a busca antiga quebra, e a série histórica perde o valor.
Nível de log com disciplina
Erro é falha que pede ação, aviso é comportamento anômalo aceito, informação é evento de negócio relevante e debug é detalhe para investigação. A disciplina vale mais que a escala: dois níveis usados com coerência valem mais que quatro usados por humor. E produção não deve rodar em debug por padrão, porque o volume custa e o ruído esconde o erro real.
Do arquivo solto à consulta única
Em ambiente com containers, a aplicação escreve no stdout e a plataforma recolhe, o que o guia de Docker para quem nunca usou mostra na prática. A partir daí, os logs vão para um lugar único onde a consulta por campo funciona, e o pipeline de entrega também se beneficia, já que o deploy automático por CI gera eventos que merecem log estruturado do próprio pipeline.
O custo escondido do log mal distribuído é o volume: na escala, amostrar requests saudáveis e guardar integralmente apenas o erro e a borda reduz a conta a uma fração, sem cegar a investigação. Defina níveis de log com intenção clara: info para fluxo, warn para anomalia esperada e error para o que precisa de ação. Um padrão consistente de nível torna a consulta tão simples quanto previsível.
Onde o log estruturado vale mais na prática
Nem todo evento merece o mesmo esforço de instrumentação. Os quatro pontos de maior retorno são conhecidos: a borda, onde cada requisição chega e sai, com rota, status e duração; as chamadas para serviço externo, que são a causa mais frequente de lentidão intermitente; os fluxos de negócio, como pedido criado e pagamento confirmado, porque são a linguagem que a área de suporte entende; e o caminho do erro capturado, com a pilha completa e o contexto que a rodeava.
O teste de qualidade é simples: escolha um incidente antigo e simule a investigação com o log atual. Se a pergunta por identificador de requisição reúne a história em uma consulta, a instrumentação está boa; se a história exige ler código e adivinhar, o furo está mapeado. Instrumentar seguindo o incidente é mais eficiente que instrumentar por conjectura, porque cada campo adicionado passa a ter um caso de uso real que justifica o volume.
Com o tempo, essa coleção de eventos vira a documentação factual do sistema: o que ele realmente faz, em que ordem e com que duração, informação que diagrama desatualizado nunca entrega. Times que tratam log como produto mantêm o esquema versionado junto com o código, e a mudança de campo aparece no review como o que ela é, uma decisão de contrato.
Perguntas frequentes
Não. O custo de adotar é baixo na biblioteca de log e o benefício aparece no primeiro bug de produção. Em projeto pequeno, até o comando de busca por campo no servidor já substitui horas de leitura de texto livre.
JSON em log não fica ilegível no terminal?
Fica menos legível a olho nu, e ferramentas resolvem: formatadores de linha embelezam o JSON na hora da leitura. Em troca, a consulta por campo compensa com folga, e a legibilidade humana volta com um filtro simples.
Onde entra o identificador da requisição?
Ele nasce na borda do sistema, no primeiro ponto que recebe a chamada, e viaja no cabeçalho até os serviços internos. Cada log da cadeia repete o mesmo valor, o que permite reunir todos os eventos de uma requisição em uma consulta.
Quanto tempo guardar os logs?
O suficiente para investigar e para cumprir obrigação legal, que varia por setor. Uma prática comum é retenção curta com detalhe completo e retenção longa com resumo agregado, o que equilibra custo e capacidade de investigação.
Registrar dado de usuário no log é seguro?
Com cuidado: dado pessoal em log cria obrigação de proteção e retenção, e logs raramente têm o mesmo controle de acesso do banco. Registre identificadores mínimos, evite conteúdo sensível e trate o log como parte da superfície de segurança.