Log bem feito na era dos agentes

Disclaimer

Este texto foi inicialmente concebido pela IA Generativa em função da transcrição de um vídeo do canal Dev Eficiente, apresentado por Alberto Souza. Se preferir acompanhar por vídeo, é só dar o play.

Introdução

O vídeo que deu origem a este texto foi gravado há quase três anos. Na época, o que me incomodava era simples de descrever: log é um tema comum no dia a dia, mas resolvido de forma artesanal. Cada pessoa da equipe decide, no momento em que escreve o código, se aquela linha merece registro, se o nível é info ou debug, e quais informações vão junto.

A comparação que eu fazia era com testes automatizados. Você juntava dez pessoas para escrever testes sobre o mesmo conjunto de classes e saíam baterias completamente diferentes, com abordagens diferentes, às vezes deixando uma branch de fora. Cada pessoa tinha uma opinião sobre o que era importante, e não havia um modelo de pensamento compartilhado por trás disso. Com log eu sentia algo parecido.

Como a resposta não estava clara para mim, passei uns dois dias procurando o que o mercado discutia e o que a pesquisa acadêmica tinha investigado sobre práticas de log. Reuni umas cinco ou seis referências e é isso que este post organiza: o que cada referência contribui e quais práticas dá para extrair delas.

Mantive as referências e as conclusões como estavam na época. Acrescentei apenas uma seção sobre algo que mudou bastante desde a gravação e que torna esse assunto mais relevante hoje do que era então: a quantidade de código escrito com apoio de IA e a investigação de problemas feita com apoio de agentes.

Por que log bem feito importa mais hoje

Nos últimos anos mudou bastante quem escreve o código e, principalmente, quem investiga o problema quando ele aparece.

Quando parte relevante do código é gerada com apoio de IA, a familiaridade de quem mantém aquele trecho com cada decisão tomada ali tende a ser menor. Você definiu a intenção, revisou o resultado, aprovou. Mas não construiu, linha a linha, o modelo mental que se constrói escrevendo. Na hora do incidente, o log ganha peso como fonte de verdade, porque ele registra o que o sistema de fato fez, não o que alguém lembra ter implementado.

Há um segundo ponto, talvez mais interessante. Boa parte da investigação hoje é feita com apoio de um agente: você entrega o log, o trecho de código e o contexto, e pede ajuda para levantar hipóteses. Só que um agente não tem intuição sobre o seu sistema, não participou das decisões e não sabe o que era esperado acontecer. Ele trabalha com o que está escrito. Um log que responde quem, o quê, quando, onde, por quê e como, em uma estrutura previsível, é exatamente o tipo de entrada que sustenta esse trabalho. Log solto, sem contexto e sem padrão, consome espaço de contexto e devolve hipótese fraca.

Ou seja, as práticas reunidas abaixo, pensadas para ajudar uma pessoa a investigar, hoje servem a dois leitores: a pessoa e o agente que apoia a pessoa. Os dois se beneficiam da mesma coisa, que é registro estruturado, com contexto suficiente e com critério compartilhado pela equipe.

Antes das referências: o critério que usei para escolher em que acreditar

Vale explicar por que fui atrás de tanta coisa para um tema aparentemente simples.

Mais atrás na profissão, minhas apostas em código eram menos sustentadas. Bastava observar que o mercado praticava de determinada forma para eu praticar também. Com o tempo fiquei bem mais crítico. A dimensão de mercado, sozinha, não me parece suficiente para sustentar uma decisão dentro de uma base de código, mesmo quando quem defende aquilo é uma referência forte da indústria ou autor de livros que eu respeito. É um bom sinal, mas está longe de virar lei.

No mínimo, eu junto três dimensões antes de apostar: o que o mercado pratica, o que a pesquisa acadêmica encontrou e a minha própria observação sobre o que está sendo proposto. Vale lembrar também que pesquisa em engenharia de software costuma ser contextual. São poucas as coisas que dá para generalizar quando falamos de práticas de código. O caminho é juntar várias fontes e observar o que aparece de forma consistente.

As referências, uma a uma

A palestra sobre os cinco W's

A primeira indicação veio de Rafael Ponte, colega de trabalho: uma palestra sobre os cinco W's de application logging, feita por alguém da comunidade Ruby. Eu já tinha ouvido falar dos cinco W's, mas confesso que não era uma prática comum minha na hora de logar.

Na formulação mais usada são cinco W's e um H: quem, o quê, quando, onde, por quê e como.

O que essa referência contribui: um checklist curto e memorizável para avaliar qualquer linha de log. Contribui menos, no entanto, com a justificativa. Alguém poderia subir no palco defendendo oito W's com a mesma convicção.

A origem dos cinco W's

Fui atrás justamente disso, e a resposta que me acalmou veio da origem do conceito. Os cinco W's são um método clássico de coleta de informação, usado em investigação e em resolução de problemas: são as perguntas que precisam ser respondidas para reconstruir o que aconteceu em uma situação.

E, quando você escreve um log, você está registrando aquilo porque acredita que vai ser útil em algum processo investigativo no futuro. A ligação é direta: se o log existe para investigar, faz sentido que ele responda às perguntas que uma investigação faz.

O que essa referência contribui: a sustentação que faltava. Deixa de ser recomendação de alguém e passa a ser consequência do propósito do log.

Um parêntese para evitar confusão comum: cinco W's não são os cinco porquês. A técnica dos cinco porquês é uma cadeia de perguntas encadeadas para chegar à causa raiz. São coisas diferentes, ainda que ambas circulem no mesmo território de resolução de problemas.

O estudo da Microsoft, de 2014

Empresas com bases de código enormes e muita gente trabalhando nelas costumam fazer estudos quantitativos e qualitativos sobre a própria realidade. Esse é um desses casos: duas bases analisadas, uma com cerca de 2,5 milhões e outra com cerca de 10,4 milhões de linhas de código, com o resultado cruzado depois com um questionário respondido por 54 pessoas desenvolvedoras.

O estudo classifica os logs encontrados em cinco categorias:

1. Logs de asserção: gerados por checagens no próprio código, como garantir que determinada referência não pode ser nula.
2. Logs de verificação de retorno: você chama uma função, pega o valor de retorno e verifica se ele condiz com o esperado.
3. Logs de exceção: o caso mais clássico. Deu problema, você registra o problema.
4. Logs de branch: entrou neste if, entrou naquele else, e você registra por onde a execução passou.
5. Logs de ponto de observação: registros ao longo do fluxo de execução, mais próximos de um trace.

E, acima dessas categorias, faz a separação que me pareceu a parte mais valiosa de tudo que li: existem duas grandes dimensões, as situações inesperadas, quando acontece algo que não deveria acontecer, e os pontos de execução, quando você apenas registra o caminho percorrido.

Na pesquisa com as pessoas desenvolvedoras, os pontos de execução apareceram na frente, seguidos de erro, branch e retorno, enquanto as asserções foram citadas por cerca de metade do grupo.

O que essa referência contribui: uma taxonomia observada em código real, e não proposta no papel, além da separação em duas dimensões que dá uma heurística direta de nível.

Sobre a categoria das asserções, faço um parêntese, porque é uma prática de que gosto muito. Quando você escreve um produto digital, tem uma certeza e um desejo: ele tem bug, e talvez seja útil para alguém. Partindo daí, eu quero que cada pedaço do software seja o mais revelador de bug possível, em todas as suas esferas, e não só por meio de uma bateria de testes. Checar pré-condições, pós-condições e invariantes ajuda a encontrar o erro mais cedo, ainda em desenvolvimento ou em homologação. E quando o erro escapa, ele aparece mais perto da origem, com stack trace menor, impedindo mais rapidamente que o sistema siga operando com estado equivocado.

O texto de Anton Chuvakin

Essa foi a referência que mais me ajudou, porque vai direto ao coração da pergunta que eu tinha: o que eu logo? O autor tem doutorado na área, escreveu um livro sobre logging e log management e trabalha com o tema há bastante tempo. O texto é daquele tipo mais aprofundado, com referências, escrito para comunidades científicas, quase um post de blog apurado.

Ele propõe tipos de evento que merecem registro:

• Autenticação, autorização e eventos de acesso: sucesso e falha de login, acessos remotos, um componente acessando outro.
• Mudanças: dados novos, dados alterados, dados removidos, mudanças de configuração ou de instalação. Esse me pareceu especialmente valioso, porque os erros mais críticos costumam aparecer justamente quando algo está sendo alterado.
• Problemas de disponibilidade: a aplicação não subiu, um componente ficou indisponível.
• Problemas de recurso: o pool de conexões esgotou, um serviço remoto não respondeu, problemas de conectividade em geral.
• Indícios de uso indevido: alguém alcançou um recurso que só deveria ser acessado por navegação interna do sistema, uma tentativa de acesso sem autorização, uma entrada inválida com conteúdo potencialmente malicioso.

Além disso, o texto dá exemplos de como responder a cada um dos W's, o que é a parte mais prática de todas.

O que essa referência contribui: o catálogo concreto que faltava. Os tipos de evento respondem quando logar, e os exemplos respondem o que colocar dentro do log.

O cruzamento entre essa referência e o estudo anterior é a parte que mais gostei. Os tipos de evento se encaixam nas duas dimensões: acessos e mudanças são bons candidatos a pontos de execução; disponibilidade, recursos e uso indevido tendem a cair em situações inesperadas. Com esse cruzamento você já tem um esquema capaz de guiar a equipe inteira a logar de maneira sistemática.

O episódio do Software Engineering Radio

Um episódio antigo, o 220, de 2015, com Jon Gifford, que trabalhava com logging e infraestrutura de log. É um podcast que eu ouvia bastante quando queria conteúdo sobre arquitetura de software, com convidados que de fato construíram coisas relevantes.

Desse episódio ficou uma opinião que não foi tão convergente entre as fontes, mas que vale registrar: se estiver em dúvida, logue. Pode ser que aquilo suje o log e torne a busca mais difícil, é verdade. Mas, entre deixar de registrar uma informação importante e registrar uma que não era importante, a preferência dele é pela segunda, porque isso maximiza as chances de o que realmente importa estar lá quando você precisar.

O que essa referência contribui: um critério de desempate para a zona cinzenta, que é onde a maioria das dúvidas vive.

A pesquisa acadêmica sobre onde logar

Vale registrar que existe pesquisa indo além disso, com trabalhos que treinam modelos de aprendizado de máquina para sugerir em quais pontos do código o log deveria existir. Na época já era um caminho que eu achava particularmente interessante, e hoje ele conversa bem com a ideia de ter um agente ajudando na revisão desse tipo de decisão.

As práticas sugeridas

Reunindo tudo, estas são as práticas que eu extrairia dessas referências.

1. Trate cada log como insumo de investigação

Antes de escrever a linha, verifique se ela ajuda alguém a responder quem, o quê, quando, onde, por quê e como. Se o registro não ajuda a responder nenhuma dessas perguntas, provavelmente ele não vale a poluição que causa.

2. Use as duas dimensões para escolher o nível

Situações inesperadas, como uma asserção que falhou, um retorno indevido ou uma exceção, tendem a virar erro, ou info quando você registra um retorno para seguir o fluxo e ele ainda está dentro do esperado. Pontos de execução tendem a cair em debug e trace.

Uma heurística simples que ficou comigo: se aquele registro é algo que você colocaria em um sysout só para acompanhar o que está acontecendo, provavelmente é um bom candidato a trace.

3. Use o catálogo de eventos como gatilho

Em vez de decidir linha a linha, decida por tipo de evento: autenticação e acesso, mudanças de dados e de configuração, indisponibilidade, esgotamento de recurso e indícios de uso indevido. Se o trecho que você está escrevendo cai em uma dessas categorias, a pergunta deixa de ser se loga e passa a ser o que precisa estar no registro.

4. Dê contexto ao log em vez de repetir dados em cada chamada

Pense no quem. Em vários pontos do sistema você simplesmente não tem o usuário em mãos. Existe uma função que recebe um parâmetro qualquer, um texto, mas que foi disparada dentro do contexto de uso de uma pessoa específica. Como esse nome entra no log daquela função?

Você provavelmente vai precisar de um interceptador, de um aspecto ou do mecanismo de contexto da sua biblioteca de log, como o MDC do SLF4J, que Rafael Ponte me lembrou na época. Repare no movimento: partir do que precisa estar registrado te faz avaliar com mais critério tanto a ferramenta quanto o log que você escreve.

5. Estruture a saída

Gere mensagens em uma estrutura como JSON, com campos correspondentes aos W's. Isso facilita a busca nos agregadores de log e, hoje, também facilita a vida de quem entrega esse log para um agente ajudar na investigação. Estrutura previsível vale mais do que mensagem bonita.

6. Na dúvida, registre

Não deliberadamente subtrair informação. Entre correr o risco de sujar o log e correr o risco de descobrir, no meio de uma investigação, que a informação que faltava nunca foi registrada, prefira o primeiro risco.

7. Documente o modelo e sustente com uma API pequena

Aqui está o ponto que mais me interessava. Sou fã de sistematização. Pensando em equipe, acredito que a produtividade e a assertividade aumentam quando conseguimos formular um modelo de pensamento, aplicá-lo por um tempo, revisitá-lo e criticá-lo. Já falei disso sobre CDD e sobre práticas de teste, e com log não é diferente.

A ideia não era construir uma biblioteca de log, e sim uma pequena API de plataforma, em cima das implementações que já existem, com objetivos claros:

• Gerar mensagens na estrutura combinada, com os campos dos W's.
• Maximizar a chance de a pessoa logar do jeito que a equipe combinou.
• Servir de referência em code review. Se um log não passa pela API e não carrega as informações combinadas, a pergunta natural é por quê, a menos que apareça uma crítica construtiva boa o bastante para mudar o entendimento do time.

Em uma organização com time de plataforma, esse seria um entregável natural: um documento explicando o que a equipe acredita que vale logar, com boas referências para leitura, acompanhado da API que materializa esse entendimento.

Conclusão

O resumo do que essas referências, juntas, sugerem:

• Log existe para uma investigação futura, então deveria responder às perguntas de uma investigação: quem, o quê, quando, onde, por quê e como.
• Duas dimensões ajudam a decidir o que registrar e em que nível: situações inesperadas e pontos de execução.
• Um catálogo de eventos dá concretude à decisão: acesso e autenticação, mudanças, disponibilidade, recursos e indícios de uso indevido.
• Partir do que precisa estar no log te torna mais crítico com a biblioteca que você usa.
• Na dúvida, registre.

E o acréscimo de hoje: com mais código sendo escrito com apoio de IA e mais investigação sendo feita com apoio de agentes, o log deixou de ser apenas um registro para a pessoa que conhece o sistema. Ele virou a entrada de trabalho de quem não conhece, seja um colega novo no time, seja um agente. Isso aumenta o valor de cada uma dessas práticas.

Referências bibliográficas

Os materiais que sustentam este texto, na ordem em que aparecem por aqui.

Busca inicial

• Query no Google Scholar por práticas de logging em sistemas, ponto de partida da pesquisa: https://scholar.google.com/scholar?hl=pt-BR&as_sdt=0%2C5&q=system+logging+practices&btnG=

Os cinco W's

• The 5 W's of Application Logging, a palestra indicada por Rafael Ponte: https://dev.to/solidusio/the-5-w-s-of-application-logging-77e
• Five Ws, com a origem do método em coleta de informação e resolução de problemas: https://en.wikipedia.org/wiki/Five_Ws

O que logar

• O artigo sobre como fazer log direito, de Anton Chuvakin, que foi a referência mais útil da pesquisa: https://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.173.2198&rep=rep1&type=pdf

Onde as pessoas realmente logam

• Where Do Developers Log? An Empirical Study on Logging Practices in Industry, a investigação da Microsoft sobre as aplicações internas deles: https://www.microsoft.com/en-us/research/wp-content/uploads/2016/07/ICSE-2014-SEIP-Where-Do-Developers-Log-An-Empirical-Study-on-Logging-Practices-in-Industry.pdf

Visão de quem constrói e opera

• Papo sobre log bem feito no canal DX Lab, indicado por Marcelo Costa: https://www.youtube.com/watch?v=F0hewZm3O2w
• Software Engineering Radio, episódio 220, com Jon Gifford sobre logging e infraestrutura de log: https://www.se-radio.net/2015/02/episode-220-jon-gifford-on-logging-and-logging-infrastructure/

Dev + Eficiente

Desenvolva software de alta qualidade e domine Engenharia de IA com o Dev + Eficiente. Cursos práticos, acesso vitalício, comunidade ativa e acesso a vagas remotas exclusivas em diversas empresas de tecnologia. Sua jornada para se tornar um dev mais eficiente pode começar agora.