Boas práticas para escrita de Logs (Parte 2)

Essa é a continuação de uma conversa sobre boas práticas de Logs. Se você ainda não viu, vai lá na Parte 1 e depois volta aqui que a gente continua o papo.

Olá! Continuando nossa conversa, na primeira parte nós falamos de (1) ferramentas, (2) níveis de log, (3) efeitos colaterais e (4) escrita de mensagens concisas. Este é um texto um pouco maior porque são temas que acredito serem mais polêmicos. Sem mais delongas… Vamos continuar com as boas práticas para escrita dos seus logs:

5. Logando argumentos e valores de retorno

Quando nós encontramos um bug durante o desenvolvimento nós geralmente usamos nosso debugger para mapear e encontrar a possível causa do nosso erro. Por isso, imagine que um bug em produção aconteceu com seus clientes/usuários há 2 dias. Tudo que você terá serão os logs, pois muito provavelmente não será possível usar algo como um debugger e simular a situação de erro.

Assim sendo, considere adicionar argumentos e retorno de métodos nos seus logs. Desse modo você consegue mapear quais entradas e quais saídas estão sendo geradas e entender onde tem um bug na sua solução.

Além disso, tenha certeza de que você conseguirá identificar threads e trabalho paralelo. Use sempre identificadores para te ajudar a saber em qual fluxo você está.

Nesse exemplo de uploads, mesmo com várias threads você conseguiria identificar o fluxo de postagem de uma foto pois você sempre está logando os ids.

Também considere usar esses logs num nível apropriado (Debug, por exemplo) para não deixar sua stream de logs muito “verbosa”.

6. Preste atenção nos sistemas externos

Quando estamos em produção e interagindo com aplicações e APIs externas, provavelmente será impossível ter acesso a esses logs de terceiros. Integrações em geral demandam um esforço considerável então considere logar* as informações que saem e voltam para seu sistema. Desse modo você conseguirá mapear se uma informação enviada a um sistema externo está voltando da maneira esperada.

O valor gerado aqui é que você conseguirá mapear quando e com quais dados alguma comunicação externa pode ter dado errado.

7. Registre suas exceções de maneira apropriada

Quando você escolhe logar simplesmente a mensagem de uma exceção, provavelmente você terá informações de qual linha do código gerou essa exceção e de qual classe/método aquele erro se originou. No entanto será difícil saber quais dados geraram determinada exceção somente olhando a stacktrace.

Se você realmente precisa logar a stacktrace da sua exceção, tenha certeza que você deixando claro (e sucinto) no seu log as causas daquela exceção. Dessa forma, será mais fácil rastrear o erro e identificar qual informação pode ter sido perdida.

Nesse exemplo é mostrado que: o problema foi na autenticação do usuário, qual o id do usuário e qual a exceção ocorreu.

8. O que é fácil de ler é fácil de rastrear (e parsear*)

Esse é um tópico que pode gerar mais polêmica. IMHO*, existem dois grupos de receptores interessados nos logs de uma aplicação: humanos e computadores (programas, crawlers, etc…) e eu acredito que logs devem ser adequados para esses dois grupos. Programadores ou pessoas responsáveis pelo suporte de uma aplicação em produção estarão interessados nos logs. Portanto, minha dica principal é:

• Use padrões que podem ser facilmente reconhecidos com expressões regulares.

TAG = [Pictures Upload]

Na maior parte dos casos, os logs que tenho postado como exemplo estão sempre com uma TAG. Com o uso de TAG ou estruturas semelhantes fica mais fácil fazer buscas nos logs com o uso de expressões regulares.

Por outro lado, há também muitos defensores do uso de logs no formato de dicionários json. Não sou fã dessa abordagem pois acho que o custo de manutenção é caro e a leitura por humanos pode não ser muito straightforward.

9. Encontre um padrão

Opa! Na primeira edição essa dica não saiu. Com o comentário de Roselma Mendes (Mulher Dev, amiga, Coworker) eu lembrei :)

A maioria das ferramentas/frameworks que mostram logs conseguem se ajustar a um padrão. Fica a critério de quem desenvolve escolher qual esse padrão. As vantagens é que você consegue classificar e limitar sua busca. Além de extrair informação de valor sobre o fluxo de sua aplicação em produção. E assim construir gráficos e poder fazer análises até do negócio! Os padrões mais comuns incluem: Horário, Nível do Log, Nome da thread, nome do logger e a mensagem:

Hoje, por exemplo, uso Splunk em um dos projetos para gerenciar meus logs. Sempre limito minhas buscas por período de tempo, nível de log e por fim filtro as mensagens com expressões regulares, etc. Isso se torna possível devido ao uso de um padrão.

10. Você sabe o que está logando?

Esta é a última dica e talvez a mais valiosa. Todas as vezes que você escreve um log em algum pedaço do seu código já parou para pensar no motivo daquela decisão?

Logs são streams e eventos sobre o ciclo de vida da sua aplicação. Tenha certeza de que eles contam uma história desse ciclo mostrando como sua aplicação está funcionando e como os erros podem estar acontecendo.

• Liste o fluxo da sua aplicação.
• Logue cada passo do seu fluxo (sempre no nível de log apropriado).
• Revise sempre suas mensagens de log e corrija aquilo que não traz valor ou informação de erro/negócio.

That's all, folks!

E aí? Discorda de alguma coisa? Vai começar a adotar alguma dessas práticas? Deixe sua opinião nos comentários! Obrigada por ler o texto e até a próxima!

*Logar: colocar algo em um Log.

*Parsear: fazer parsing.

*IMHO: In my humble opinion. Tradução: Na minha humilde opinião.