Para que servem os logs?

Guia para os vibe coders.

Um cliente liga. Ele fez um pedido ontem, pagou, e o e-mail de confirmação nunca chegou. Quer saber se o pedido existe.

Você abre o painel. O pedido está lá: número 4521, pago, em preparação. Você diz que sim, que está tudo certo, e que vai reenviar o e-mail agora. O cliente fica tranquilo. Ele não está interessado em saber por que o e-mail não chegou.

Você, sim. Porque, se aconteceu com ele, aconteceu com outros, e amanhã liga o próximo. O painel não vai te contar: ele mostra o estado das coisas, não o que aconteceu.

Então você abre os logs. Busca por 4521 e a história aparece: o pedido foi salvo, o pagamento foi confirmado, o serviço de e-mail foi chamado e respondeu 429 Too Many Requests: limite diário atingido. O e-mail nunca saiu. O seu código registrou o erro e seguiu em frente como se nada tivesse acontecido. Ninguém tentou de novo, ninguém avisou.

Você busca por 429 e aparecem mais vinte e três, todos do pedido 4512 em diante. Foi um dia bom de vendas e o plano gratuito do provedor de e-mail tem um teto diário. Agora você sabe o que aconteceu, com quem aconteceu e o que precisa ser consertado: colocar os envios numa fila e tentar de novo quando a janela abrir, ou trocar de plano. Trinta segundos.

Agora imagine que não há logs. O pedido está no painel, o e-mail não chegou, e você não tem mais nada. O que você faz? Roda o fluxo de novo para ver se acontece outra vez? Pergunta ao agente que escreveu o código? Se ele só tem o código, vai lê-lo e te dizer o que deveria ter acontecido. Ele não faz ideia do que aconteceu. Ninguém faz. Você chuta.

Essa é a diferença. O código diz o que o programa faz em geral. O log diz o que ele fez daquela vez.

E nem precisa ser você a ler. Se os logs existem, você os entrega ao agente e pede que descubra o que houve com o pedido 4521. Com a evidência na frente, o agente para de chutar: encontra o 429, conta os outros vinte e três e te propõe a nova tentativa. O que muda não é o agente, é o que ele tem à mão.

Por que não basta escrever num arquivo

A forma mais simples de saber o que um programa fez é fazer com que ele escreva isso: uma linha no código que anota "cheguei até aqui" ou "o valor é tal" num arquivo. Um programador com um erro que não conseguia reproduzir na própria máquina fazia exatamente isso, subia o código para o servidor e esperava o erro voltar a acontecer.

Funciona, até parar de funcionar. O arquivo cresce até encher o disco e derrubar o servidor. Escrever em disco a cada passo deixa o programa lento. Cada programador anota num formato próprio e ninguém consegue ler o do outro. É por isso que existem as bibliotecas de logging: níveis (isto é um erro, isto é só informação), rotação de arquivos, escrita em segundo plano, um formato comum. Qualquer uma que você use hoje resolve esses mesmos problemas.

Depois vem a ideia importante: não esperar o cliente ligar. Se o log já diz que o e-mail falhou, o sistema pode te avisar na hora, e não três dias depois. Os logs deixam de ser algo que você olha quando há um problema e passam a ser algo que te diz que há um problema.

Hoje não existe sistema sério sem logs. É tão normal que ninguém mais se pergunta para que servem.

Por que se chama "log" — e por que não "diário de bordo"

Antes de existirem os computadores, os marinheiros mediam a velocidade do navio jogando na água um pedaço de madeira — um log, em inglês — preso a uma corda com nós a intervalos regulares. Contavam quantos nós passavam pela mão em meio minuto. É daí que vem o "nó" como unidade de velocidade. O resultado era anotado no logbook, junto com o rumo, a hora e o tempo, para que qualquer pessoa pudesse reconstituir a viagem depois. Quando os programadores começaram a escrever o que um programa fazia num arquivo, deram a ele o mesmo nome. É a mesma ideia: um registro do que aconteceu, feito para alguém ler depois. Em português, o livro onde tudo isso ficava anotado se chama diário de bordo, e era essa a palavra que podia ter passado para a informática. Não passou: a programação chegou aqui já falando inglês, e o que pegou foi o nome do instrumento, não o do caderno. Dizemos "olhar o log", "arquivo de log", "subir o nível de log" — falamos do pedaço de madeira, e não do livro em que o oficial de quarto escrevia. Quem pede "dá uma olhada no log" está, sem perceber, falando de uma tábua puxada por uma corda cheia de nós.

O que não muda com os agentes

Se a sua aplicação foi escrita por um agente, nada do que vimos até aqui desaparece. A rede continua falhando. O serviço de e-mail continua demorando. O provedor de pagamentos continua cobrando duas vezes quando a nova tentativa entra na hora errada. Nada disso depende de quem escreveu o código, e o agente também não está livre de cometer erros próprios. A diferença é outra.

Antes, quando algo falhava, você abria o código e lia. Hoje o código foi escrito por um agente, é mais do que uma pessoa consegue ler, e cada vez se lê menos. Muita gente já não revisa o que o agente gera; olha se funciona. Mas uma coisa é não ler o código, e outra é não saber o que ele fez quando rodou.

A distância entre você e o que aconteceu aumentou. Antes havia uma pessoa que lembrava o que tinha escrito e por quê. Agora há um agente que não lembra nada da sessão anterior e um código que ninguém leu inteiro. A única coisa que sobra no meio é o log. Se ele existe e o agente consegue consultá-lo, você sabe o que aconteceu. Se não, você pergunta e ele vai te contar o que deveria ter acontecido, com muita convicção.

Os logs servem para mais do que achar erros: com eles se analisa o que as pessoas fazem na sua aplicação e se deixa registrado o que o sistema fez e quando, caso alguém pergunte depois. Mas isso vem de brinde. Primeiro eles precisam existir.

O que fazer

O teste é o seu próprio pedido 4521: escolha qualquer pedido de ontem e peça ao seu agente que reconstitua o que aconteceu com ele. Não o código, o que aconteceu. Se ele consegue contar a sequência — o que foi chamado, com que resultado, quanto tempo levou — você tem logs e o agente consegue consultá-los. Se não consegue, falta uma de duas coisas: ou os logs não existem, ou existem e o agente não chega até eles. As duas têm conserto.

Se não existem, peça ao agente que registre cada passo importante: o que foi chamado, com que resultado, quanto tempo levou e a qual pedido corresponde. Esse último dado é o que torna possível todo o exemplo acima. E confira se ele fez, porque é a primeira coisa que fica de fora quando a única medida é se o código funciona.

Quando o cliente ligar, e ele vai ligar, que você tenha algo para olhar. E o seu agente também.