Logs bons economizam horas de sustentação

Quando uma automação funciona, quase ninguém presta atenção nos logs.

Quando ela falha, eles viram uma das coisas mais importantes do processo.

Essa é uma das diferenças que aparecem quando saímos de uma automação feita apenas para demonstrar um fluxo e passamos a lidar com algo que precisa rodar em produção.

Durante o desenvolvimento, normalmente sabemos exatamente o que estamos testando. Estamos acompanhando a execução, conhecemos os dados utilizados e conseguimos reproduzir o cenário.

Em produção, isso muda.

A falha pode acontecer de madrugada, em uma máquina diferente, com um registro que nunca vimos e depois de centenas de transações processadas corretamente.

Nesse momento, um log como:

Erro no processamento.

é quase a mesma coisa que não ter log nenhum.

Log não é só mensagem de erro

É comum pensar em logging apenas como uma forma de registrar que alguma coisa deu errado.

Mas logs deveriam contar a história da execução.

Eles precisam ajudar a responder perguntas como:

• quando a execução começou?
• qual processo estava rodando?
• qual transação estava sendo tratada?
• em qual etapa ocorreu a falha?
• qual sistema ou serviço estava envolvido?
• qual foi o retorno recebido?
• houve nova tentativa?
• o item foi reprocessado ou descartado?
• a execução conseguiu continuar?

Essas informações reduzem muito o espaço de investigação.

Sem elas, a sustentação vira tentativa e erro.

O problema do “deu erro”

Imagine uma automação que processa 500 registros.

O item 347 falha.

No log existe apenas:

Falha ao processar item.

A primeira pergunta já aparece imediatamente:

qual item?

Depois vêm outras:

em qual etapa?

por quê?

já tinha sido processado?

é seguro tentar novamente?

Agora imagine outra mensagem:

Processo=AtualizacaoCadastral
Transacao=347
Etapa=EnvioAPI
StatusCode=503
Tentativa=2/3
Resultado=Falha temporaria

Ainda existe um problema, mas já existe contexto.

Isso muda completamente a sustentação.

Contexto vale mais do que quantidade

Uma automação pode gerar milhares de linhas de log e ainda assim ser difícil de analisar.

Quantidade não significa qualidade.

Registrar cada clique, cada atribuição de variável e cada pequena etapa pode produzir tanto ruído que a informação importante acaba escondida.

O objetivo não deveria ser “logar tudo”.

Deveria ser registrar o que ajuda a entender o comportamento da automação.

Para mim, alguns tipos de informação são especialmente úteis:

• início e fim da execução;
• identificador do processo;
• identificador da transação;
• etapas relevantes;
• integrações externas;
• quantidade de itens encontrados;
• quantidade processada;
• erros de negócio;
• erros técnicos;
• tentativas de recuperação;
• resultado final.

O nível de detalhe também depende da criticidade do processo.

Identifique a transação

Em processos que lidam com vários registros, um identificador de transação faz muita diferença.

Ele pode ser um número de solicitação, um ID interno, uma chave de fila ou outro identificador que represente aquele item.

O importante é conseguir acompanhar o mesmo registro durante todo o fluxo.

Por exemplo:

[Transacao 98124] Iniciando processamento
[Transacao 98124] Consulta realizada com sucesso
[Transacao 98124] Enviando dados para API
[Transacao 98124] Status HTTP 200
[Transacao 98124] Processamento concluido

Se essa transação falhar, existe uma trilha.

Quando alguém reportar um problema relacionado ao registro 98124, a investigação pode começar por ele.

Isso parece simples, mas faz uma enorme diferença quando o volume cresce.

Diferencie informação, aviso e erro

Nem todo evento precisa ter a mesma importância.

Uma estrutura básica costuma separar pelo menos:

• Info: comportamento esperado da automação;
• Warning: situação inesperada que não impediu a continuidade;
• Error: falha que afetou uma operação ou transação;
• Fatal/Critical, quando disponível: falha que impede a continuidade do processo.

Essa separação permite filtrar melhor o que está acontecendo.

Se tudo é Error, nada é realmente Error.

Se tudo é Info, problemas importantes desaparecem no meio do volume.

Erro de negócio precisa aparecer diferente

Uma regra de negócio não atendida não é necessariamente uma falha técnica.

Suponha que um registro precise conter determinado dado para poder continuar.

Se o campo estiver vazio, a aplicação pode estar funcionando perfeitamente.

A automação também.

O item simplesmente não atende às condições necessárias.

Esse tipo de ocorrência deveria ser identificável nos logs.

Por exemplo:

Tipo=BusinessException
Transacao=98124
Motivo=Campo obrigatório não informado

É muito diferente de:

Tipo=ApplicationException
Transacao=98124
Motivo=Timeout ao consultar sistema externo

Essa distinção ajuda tanto na sustentação quanto na geração de indicadores.

Não registre segredo para conseguir contexto

Existe um limite importante.

Logs precisam ser úteis, mas não podem virar um vazamento de informação.

Nunca é uma boa ideia registrar indiscriminadamente:

• senhas;
• tokens;
• cookies;
• chaves de API;
• dados sensíveis;
• payloads completos sem necessidade;
• documentos pessoais;
• informações confidenciais.

É possível criar rastreabilidade sem despejar todos os dados do processo.

Em vez de registrar todo o objeto recebido, muitas vezes basta registrar um identificador seguro.

Em vez de salvar um token para investigar autenticação, podemos registrar que a autenticação falhou e qual status foi recebido.

Observabilidade também precisa respeitar segurança e privacidade.

Logs estruturados são ainda melhores

Quando possível, gosto da ideia de tratar logs como dados.

Em vez de depender apenas de frases:

O processamento da solicitação 98124 falhou na API.

podemos pensar em uma estrutura:

Processo=Cadastro
Transacao=98124
Etapa=API
Resultado=Falha
StatusCode=503
Tentativa=2

Isso facilita busca, filtros e dashboards.

Em ferramentas de orquestração, observabilidade ou agregadores de logs, campos bem definidos podem ser muito mais úteis do que texto livre.

Principalmente quando começamos a perguntar:

• quantas falhas ocorreram hoje?
• qual etapa falha mais?
• qual erro aparece com maior frequência?
• quantas transações precisaram de retry?
• qual processo apresenta maior taxa de erro?

A partir desse ponto, logging deixa de servir apenas para debugging.

Ele passa a ajudar na gestão do processo.

O início e o fim também importam

Outro detalhe que gosto de considerar é registrar claramente o ciclo de vida da execução.

Algo como:

Execucao iniciada
Itens encontrados: 427
Itens processados: 421
Business Exceptions: 4
Application Exceptions: 2
Execucao finalizada

Esse pequeno resumo já responde várias perguntas.

Se a execução deveria encontrar aproximadamente 400 itens e começa a encontrar zero, talvez exista um problema mesmo sem nenhuma exceção.

Observabilidade também serve para detectar comportamentos estranhos em execuções que, tecnicamente, terminaram com sucesso.

Um erro bom ajuda alguém que não escreveu o código

Uma maneira simples de avaliar a qualidade de uma mensagem é imaginar outra pessoa lendo o log.

Ela consegue entender o que aconteceu?

Ou precisa abrir o código para descobrir o significado?

Mensagens como:

Erro na atividade X.

podem fazer sentido para quem desenvolveu.

Daqui a seis meses, talvez nem essa pessoa lembre exatamente o que “atividade X” significa.

Um log melhor explica o contexto:

Falha ao consultar situação da transação 98124 no serviço de cadastro.
HTTP 503 após 3 tentativas.

O código ainda pode precisar ser analisado.

Mas a investigação já começa muito mais perto da causa.

Logs fazem parte da arquitetura

Hoje, não penso em logging como algo que adicionamos no final.

Ele influencia o desenho do processo.

Se quero rastrear uma transação, preciso definir sua identidade.

Se quero diferenciar falhas, preciso classificar exceções.

Se quero medir desempenho, preciso registrar tempos ou etapas.

Se quero monitorar volume, preciso registrar contagens.

Ou seja: observabilidade exige decisões de arquitetura.

O tempo economizado aparece depois

É difícil medir o valor de um bom log enquanto tudo está funcionando.

Ele aparece quando surge o primeiro incidente.

Depois, no segundo.

No terceiro.

Uma automação pode rodar durante meses, e cada falha mal diagnosticada pode consumir dezenas de minutos ou horas.

Quando o processo possui boa rastreabilidade, esse tempo cai.

Por isso, logs não são apenas uma ferramenta para desenvolvedores.

Eles fazem parte da sustentabilidade da solução.

Conclusão

Uma automação não deveria apenas executar.

Ela deveria conseguir explicar o que fez.

Quando começou.

O que processou.

Onde falhou.

Por que tentou novamente.

Qual item ficou pendente.

E como terminou.

Quanto melhor essa história estiver registrada, menor será o tempo gasto tentando reconstruí-la depois.

Logs bons não evitam todos os problemas.

Mas economizam muitas horas quando eles aparecem.