Como melhorar os logs da sua aplicação usando boas práticas
Existem dois grupos de pessoas, o primeiro grupo são de pessoas que já precisaram realizar algum tipo de análise por meio de logs, e o segundo grupo são de pessoas que logo, logo precisarão realizar isto.
Os logs são fundamentais para qualquer tipo de software, mas antes de entendermos como podemos melhorar os logs das nossas aplicações, vamos entender, o que são os logs e a sua importância, tudo bem?
O que são logs?
A palavra log traduzida para o português significa "registro", os logs são registros de eventos que ocorreram em um sistema, com seu formato geralmente em texto e armazenado em arquivos. Este texto contém tanto detalhes sobre o evento, quanto informações da cronologia do evento, como data e hora. Nos arquivos de logs são registradas diversas informações, como informações dos fluxos do sistema, as atividades dos usuários, integrações entre componentes (como sistemas externos, banco de dados, sistema operacional e outros), desempenho do sistema, alertas e outras informações.
Os logs podem ser facilmente visualizados, principalmente por ter como característica o seu formato em texto, um dos meios possíveis para visualização são os editores de texto, porém existem também ferramentas especificas para visualizar este tipo de conteúdo, como Grafana, Splunk, New Relic, etc.
Qual a importância dos logs?
Os logs permitem diversos ganhos para as equipes de desenvolvimento. Com a utilização deles temos facilidade para visualizar a integridade de softwares, infraestrutura de TI e outros componentes.
Além disso, eles ajudam também a identificar e solucionar problemas, permitem a visualização e análise do exato momento que o evento ocorreu, tendo como base data e hora, fornecem informações baseadas em dados de usuários, acessos, segurança, sistemas e acessibilidade, e não menos importante, eles ajudam a identificar problemas relacionados à segurança.
Então, “é só logar”?
Embora o conceito de logs e a sua importância sejam simples e claras, e isso também se estende para a visualização e as ferramentas que pode se utilizar, emitir logs em sua aplicação não necessariamente garante que a você e/ou a sua equipe de desenvolvimento irão desfrutar da facilidade e os benefícios que os logs trazem; pelo fato de ser simples e claro, muitos desenvolvedores, não tratam os logs com a sua devida importância e nem se atentam em escrever bons logs e com qualidade.
Por isso, tão importante quanto escrever o log, é escrevê-lo com qualidade, isso permitirá não apenas colher os benefícios, como por exemplo apoiar em troubleshooting (solução de problemas), mas também facilitará o entendimento de desenvolvedores e outras pessoas que estão tendo contato com o projeto. Dessa forma, quero apresentar a você, boas práticas de logs exercidas pela comunidade de desenvolvimento, que te ajudarão a melhorar os logs da sua aplicação.
Boas práticas
Como em diversas etapas e processos na engenharia de software, a seguir serão apresentadas boas práticas para não somente escrever os logs, mas escrevê-los com qualidade. Para exemplificar alguns tópicos será utilizada a linguagem Kotlin em consonância com o pacote kotlin-logging-jvm (estrutura de log para Kotlin, escrita totalmente em Kotlin):
Avalie quais informações serão registradas
Há um volume enorme de informações que podem ser registradas por meio dos logs, desde informações das camadas do sistema, até informações relacionadas a algum tipo de integração, como por exemplo, uma consulta no banco de dados. Entretanto, é necessário avaliar quais informações são relevantes para serem registradas, e devem estar em conformidade tanto com as diretrizes da organização quanto as leis do país, como por exemplo a LGPD.
Este passo é fundamental para um bom gerenciamento de logs, e pode ser facilmente executado, utilizando-se do levantamento das diretrizes e um alinhamento com a equipe para a definição do que é relevante registrar nos logs. As informações comumente registradas nos logs são: eventos do sistema (exemplo: comunicação entre serviços), informações de negócios (exemplo: jornadas do sistema), operações de dados (exemplo: estado novo e anterior de um conjunto de dados).
Defina um padrão
Uma boa prática, é definir um padrão para os logs, isto inclui a estrutura da mensagem (recomenda-se adicionar o nome do logger – o contexto), idioma (recomenda-se utilizar o inglês), horário, limite de caracteres, nível de log entre outras características. Este padrão é definido pelos responsáveis pelo desenvolvimento, ter um padrão permite usufruir de diversos benefícios como, manter os logs organizados, realizar filtros mais efetivos, e até mesmo criar dashboards para análises.
Registre mensagens objetivas e descritivas
A mensagem registrada no log nos auxilia a compreender o fluxo do sistema, ela também precisa agregar valor, assim é necessário que a mensagem seja clara e descritiva, permitindo a quem está verificando a identificação da causa do evento, o momento e as entradas/saídas. Mensagens como as que serão mostradas a seguir, são exemplos de mensagens que não são claras e nem descritivas, e provavelmente não nos ajudará:
logger.error("Caching service is not working.")
logger.error("Error caching service.")
Estes logs acima, não mostram o que e nem onde está acontecendo o evento, dessa forma podemos melhorar as mensagens de logs escrevendo-as com mais objetivo e com uma descrição melhor, como:
logger.error("[UserRepository] Could not connect to caching service, invalid credentials.").
Não registre informações sensíveis
Como já citado anteriormente, é importante estar em conformidade com as diretrizes da organização e as leis do país com relação a dados. Tão importante quanto, é não registrar informações sensíveis, pois isso potencializa possíveis problemas de segurança, como por exemplo, o vazamento de dados. Informações como credenciais, números de documentos pessoais, senhas, chaves de APIs e outros nesse mesmo sentido, são consideradas informações sensíveis.
❌ logger.error("[UserService] Unable to login for user with email: {}, and password: {}", email, password).
✅ logger.error("[UserService] Unable to login for user with id: {}", userId).
Teste os seus logs
É importante também, realizar testes em seus logs, mas não se engane, não são testes unitários, esse teste consiste em que você valide o que de fato está sendo exibido ao registrar o log. Ao fazer isso, você estará validando e verificando a elegibilidade dos textos, questione-se, se está de acordo com a ideia/contexto, se está compreensível, se a gramática está correta e se não há nenhuma inconsistência. Além disso, você pode compartilhar os logs com um colega, e verificar se ficou claro para ele.
Use níveis de logs (e de forma correta 👀)
Uma boa prática, é a utilização do conceito de nível do log, ele permite classificar a informação que será registrada de acordo com a sua relevância. Definir o nível do log não é uma tarefa fácil, entretanto, facilitará futuros troubleshootings e possibilitará filtros e visualização de acordo com o nível, como por exemplo, realizar buscas de logs com o nível de "ERROR". Os níveis de logs comumente utilizados são:
- Info: Utilizado para informações gerais, projetando o desenvolvimento da ação que pode ser orientada pelo usuário ou específicas do sistema.
logger.info("[UserController] Starting process to get userinformation.").
- Warn: Utilizado para eventos que podem se tornar um possível erro.
logger.warn("[UserRepository] Call to database to get user data took 60000 milliseconds, default time is 30000 milliseconds.").
- Error: Utilizado para todas as condições de erro, sejam erros internos ou externos.
logger.error("[UserService] An error occurred while searching the user's data, this user has the status of blocked.").
- Debug: Utilizado para mostrar tudo o que acontece no software, é comumente utilizado durante a depuração (execução do código passo a passo).
logger.debug("[UserService] The value of the user variable is {}", user).
Há outros níveis de logs que podem ser utilizados pela sua aplicação, cada nível tem o seu propósito, e poderá facilitar tanto o seu processo de desenvolvimento de software, quanto futuros troubleshootings. Os níveis de logs são necessários e indispensáveis para qualquer tipo de sistema. Sugiro a você separar um tempo para estudar os níveis de logs, OK 😊?
Adicione IDs de rastreamento
Atualmente, grande parte das equipes de desenvolvimento de softwares tem utilizado a arquitetura de microserviços / sistemas distribuídos, permitindo que uma aplicação seja dívida em pequenas partes e que sejam independentes. Tendo em vista está interdependência, é importante utilizar-se de logs para a rastreabilidade de eventos, entretanto, este ponto é um dos desafios de arquiteturas e está exatamente relacionado a rastreabilidade dos eventos entre as pequenas partes que compõe a aplicação. Um bom hábito é registrar nos logs, os IDs de rastreamento, isso favorecerá para que seja necessário o rastreamento e acompanhamento de eventos que estão acontecendo entre as “pequenas partes”.
Conclusão
Os logs, portanto, são fundamentais para o desenvolvimento e sustentação do software. Neste artigo foram apresentadas boas práticas para os logs, é importante destacar que existem muitas outras boas práticas (e que eu posso não ter citado aqui) e podem te auxiliar no processo contínuo de melhoria dos seus logs.
Na seção de referências, há ótimos artigos relacionados a boas práticas de logs, fique à vontade para explorar, e adquirir cada vez mais conhecimento sobre as melhores práticas para logs.
Referências
https://www.hostmidia.com.br/blog/logs-do-sistema-operacional/
https://support.ankama.com/hc/pt-br/articles/203790076-O-que-%C3%A9-um-log-
https://smanager.com.br/gerenciamento-logs/
https://dev.to/vepo/deixando-rastros-ou-como-usar-log-peg
https://www.ibm.com/docs/pt-br/was-nd/8.5.5?topic=logger-log-levels
https://levelup.gitconnected.com/9-logging-best-practices-da9457e33305
https://www.dataset.com/blog/the-10-commandments-of-logging/
https://medium.com/everything-full-stack/logging-best-practices-e26d0a3e2697
https://www.chaossearch.io/blog/log-management-best-practices
A Revelo Content Network acolhe todas as raças, etnias, nacionalidades, credos, gêneros, orientações, pontos de vista e ideologias, desde que promovam diversidade, equidade, inclusão e crescimento na carreira dos profissionais de tecnologia.