O que realmente é um log na prática
Log é, de forma direta, um registro cronológico de eventos gerados por um sistema. Pode ser um arquivo texto simples, uma entrada em banco de dados ou até um fluxo em tempo real enviado para um serviço de monitoramento. A definicao de log envolve basicamente três coisas: timestamp, nível de severidade e a mensagem em si. O que muda entre equipes é só como elas estruturam o resto. Eu já vi gente gastar duas semanas construindo um parser complexo para logs JSON porque o time anterior decidia gravar objetos aninhados sem nenhum esquema definido. A solução mais simples foi um regex que extrai as chaves principais e joga o resto num campo raw. Funciona bem o suficiente para investigação e não quebra quando alguém adiciona um campo novo sem avisar.
Como construir a definicao de log do zero
Comece decidindo o formato. Texto separado por espaços funciona para logs simples. JSON é o padrão da indústria hoje porque permite estruturação sem ambiguidade. Se você usar JSON, defina um schema antes de começar a escrever. Eu usei um schema flexível com campos obrigatórios fixos e campo adicional para o resto, o que evitou breaking changes quando o time de backend mudou o payload três vezes num mês. Os níveis padrão são DEBUG, INFO, WARN, ERROR e FATAL. A maioria dos sistemas não precisa de mais que isso. Já vi equipe usar NINE níveis diferentes de warn, o que só servia para confundir quem lia o log às três da manhã quando o alerta disparava.
Um problema real que eu encontrei
Num projeto anterior, o log de erros parou de ser coletado porque alguém configurou o app para logar em stdout, mas o container estava redirecionando stdout para /dev/null por um script de entrypoint mal escrito. Levei quatro horas pra descobrir porque o log aparecia normalmente quando rodava localmente e sumia no ambiente de staging. A workaround foi adicionar um logger secundário que escrevia direto num arquivo no volume mountado, ignorando completamente o stdout do container.
Insights que ninguém conta nos tutoriais
A primeira coisa que todo mundo erra é o volume de logs de DEBUG em produção. Um endpoint que loga cada parâmetro de entrada e cada retorno pode gerar entre 2 e 5 GB por dia dependendo do tráfego. Isso age como um ataque DDoS no seu sistema de coleta e encarece a conta de storage à toa. A regra prática que eu sigo: desliga DEBUG em produção e usa WARN ou ERROR só para o que realmente precisa de atenção. A segunda armadilha é o que eu chamo de log spoofing. Se o timestamp vier do lado do cliente ou do servidor de aplicação e não do sistema operacional, alguém com acesso ao app pode manipular a ordem dos eventos. Sempre faça o timestamp no nível mais baixo possível da stack, preferencialmente no kernel ou na camada de rede, não no código da aplicação.
👉 Clique no botão abaixo para saber mais sobre o assunto!
Ferramentas e como escolher
Para log leve, a pilha syslog + rsyslog funciona e gasta quase nada de recurso. Para algo mais robusto, Elasticsearch com Filebeat é o combo mais usado, mas exige pelo menos 4 GB de RAM só pro Elasticsearch rodando direito. Se o orçamento for apertado, Loki com Promtail é uma alternativa que consome cerca de um quinto dos recursos e faz agregação por labels sem precisar indexar todo o conteúdo do log. O Loki tem uma limitação importante que todo mundo esquece: ele não indexa o corpo do log, só os labels. Isso quer dizer que buscas por texto livre dentro da mensagem são lentas e custosas em termos de I/O. Se seu time precisa fazer grep pesado em logs, o Loki vai doer. Nesse caso, volte pro Elasticsearch ou considere o ClickHouse com seu motor de busca full-text integrado.
Download e configuração prática
Para começar rápido, o pacote do Promtail vem nos repositórios oficiais do Grafana Labs. O install em Ubuntu é um wget direto do release mais recente e um dpkg -i. A config mínima que eu uso tem três partes: o target apontando para os arquivos de log da aplicação, o pipeline_steps com um parser JSON e um label de app_id fixo. Leva cerca de 10 minutos pra subir tudo funcionando. Eu costumo manter um template de config no meu GitHub pessoal que já vem com as configurações para Docker, systemd e arquivos planos. Quem quiser usar pode clonar e ajustar os caminhos dos logs conforme o ambiente. A versão mais recente é a 2.9.0, que traz suporte nativo a multiline com regex, algo que antes exigia um sidecar separado.
Quando log simplesmente não resolve o problema
Existe um cenário em que log é a ferramenta errada: rastreamento de transações distribuídas com latência crítica. Se você precisa saber o tempo exato que cada microserviço levou numa requisição que passa por sete serviços, log aggregation não vai te dar isso com precisão. Aí você precisa de tracing com contexto propagado, tipo OpenTelemetry. Log ainda serve pra guardar o que aconteceu, mas não pra medir latência entre serviços com margem de erro menor que 10 milissegundos. Outro caso onde log falha como única fonte de verdade é em sistemas transacionais financeiros. O log pode ser apagado, corrompido ou mal ordenado por clock skew entre servidores. Nesses cenários, o registro permanente precisa vir do banco de dados com checksums e append-only logs, não de arquivos de log da aplicação. Eu aprendi isso na pior forma quando precisei reconstruir o histórico de uma transação e o log do serviço não batia com o registro no banco por causa de um replay de mensagem que não foi devidamente tratado.
Dicas que economizam tempo
Roteirize os logs por data e serviço desde o primeiro dia. Estruturas tipo /var/log/app/nome_do_servico/ano/mes/dia.log salvam horas de caça quando o volume cresce. Mantenha retention policy definida antes de ir pra produção. Deixar pra depois é o caminho mais rápido pra encher o disco e ter que decidir na hora do susto o que fica e o que vai pro lixo. Se você estiver construindo a definicao de log do zero agora, pegue o template do Promtail, defina os três campos obrigatórios, desligue DEBUG em produção e teste a coleta antes de submeter qualquer aplicação ao ambiente. O resto se resolve com ajuste fino, não com arquitetura complexa desde o início.
