Cómo mejorar los logs de tu aplicación usando buenas prácticas
Hay dos grupos de personas, el primer grupo son personas que ya han necesitado realizar algún tipo de análisis mediante logs, y el segundo grupo son personas que pronto necesitarán realizarlo.
Los logs son fundamentales para cualquier tipo de software, pero antes de entender cómo podemos mejorar los registros de nuestras aplicaciones, comprendamos qué son los registros y su importancia, ¿de acuerdo?
¿Qué son los logs?
La palabra log traducida a español significa "registro". Los logs son registros de eventos ocurridos en un sistema, con su formato generalmente en texto y almacenados en archivos. Este texto contiene detalles sobre el evento e información sobre su cronología, como la fecha y la hora. Los archivos de registro registran información diversa, como información sobre flujos del sistema, actividades de los usuarios, integraciones entre componentes (como sistemas externos, bases de datos, sistemas operativos y otros), rendimiento del sistema, alertas y otra información.
Los logs pueden visualizarse fácilmente, principalmente porque se caracterizan por su formato de texto. Uno de los medios posibles para visualizarlos son los editores de texto, pero también existen herramientas específicas para visualizar este tipo de contenidos, como Grafana, Splunk, New Relic, etc.
¿Cuál es la importancia de los logs?
Los logs permiten varias ganancias para los equipos de desarrollo. Al usarlos, podemos visualizar fácilmente la integridad del software, la infraestructura de TI y otros componentes.
Además, también ayudan a identificar y solucionar problemas, permiten la visualización y análisis del momento exacto en que ocurrió el evento, en base a fecha y hora, brindan información basada en datos del usuario, acceso, seguridad, sistemas y accesibilidad, y no menos. Lo más importante es que ayudan a identificar problemas relacionados con la seguridad.
Entonces, ¿“es solo loguearse”?
Aunque el concepto de logs y su importancia son simples y claras, y esto también se extiende a la visualización y las herramientas que se pueden utilizar, emitir registros en su aplicación no necesariamente garantiza que usted y/o su equipo de desarrollo disfruten de la facilidad y los beneficios que brindan los registros. Debido a que es simple y claro, muchos desarrolladores no tratan los registros con la debida importancia y no prestan atención a escribir registros buenos y de calidad.
Por lo tanto, tan importante como redactar el log es escribirlo con calidad, esto no sólo te permitirá obtener beneficios, sino también apoyarse en troubleshooting (solução de problemas), pero también facilitará la comprensión de los desarrolladores y otras personas que estén teniendo contacto con el proyecto. Por lo tanto, quiero presentarles buenas prácticas de registro practicadas por la comunidad de desarrollo, que le ayudarán a mejorar los registros de su aplicación.
Buenas prácticas
Como en varios pasos y procesos de la ingeniería de software, a continuación presentaremos buenas prácticas no solo para escribir registros, sino también para escribirlos con calidad. Para ejemplificar algunos temas, el lenguaje Kotlin en línea con el paquete kotlin-logging-jvm (marco de registro para Kotlin, escrito íntegramente en Kotlin):
Evaluar qué información se registrará
Existe un enorme volumen de información que se puede registrar a través de logs, desde información de las capas del sistema, hasta información relacionada con algún tipo de integración, como una consulta a una base de datos. Sin embargo, es necesario valorar qué información es relevante para ser registrada, debiendo cumplir tanto con los lineamientos de la organización como con las leyes del país, como la LGPD.
Este paso es fundamental para una buena gestión de los registros y se puede realizar fácilmente, utilizando pautas y alineándose con el equipo para definir qué es relevante registrar en los registros. La información comúnmente registrada en los registros es: eventos del sistema (ejemplo: comunicación entre servicios), información comercial (ejemplo: recorridos del sistema), operaciones de datos (ejemplo: estado nuevo y anterior de un conjunto de datos).
Define un patrón
Una buena práctica es definir un estándar para los registros, esto incluye la estructura del mensaje (se recomienda agregar el nombre del registrador – el contexto), idioma (se recomienda usar inglés), tiempo, límite de caracteres, nivel de registro entre otras características. Este estándar lo definen los responsables de desarrollo, tener un estándar permite disfrutar de varios beneficios como mantener organizados los registros, realizar filtros más efectivos e incluso crear paneles para análisis.
Registra mensajes objetivos y descriptivos
El mensaje registrado en el log nos ayuda a entender el flujo del sistema, también necesita agregar valor, por lo que el mensaje debe ser claro y descriptivo, permitiendo a quien lo revisa identificar la causa del evento, el momento y las entradas. /salidas. Mensajes como los que se muestran a continuación son ejemplos de mensajes que no son ni claros ni descriptivos, y probablemente no nos ayuden:
logger.error("Caching service is not working.")
logger.error("Error caching service.")
Estos registros anteriores no muestran qué o dónde está sucediendo el evento, por lo que podemos mejorar los mensajes de registro escribiéndolos con más objetivos y con una mejor descripción, como por ejemplo:
logger.error("[UserRepository] Could not connect to caching service, invalid credentials.").
No registres información sensible
Como se mencionó anteriormente, es importante cumplir con los lineamientos de la organización y las leyes del país en materia de datos. Igual de importante es no registrar información sensible, ya que esto aumenta posibles problemas de seguridad, como fugas de datos. Información como credenciales, números de documentos personales, contraseñas, claves API y otras en el mismo sentido son consideradas información sensible.
❌ 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).
Prueba tus logs
También es importante realizar pruebas a tus logs, pero no te equivoques, estas no son pruebas unitarias, esta prueba consiste en que tú valides lo que realmente se está mostrando al registrar el log. Al hacer esto, estarás validando y comprobando la elegibilidad de los textos, pregúntate si está acorde con la idea/contexto, si es comprensible, si la gramática es correcta y si no hay inconsistencia. Además, puede compartir los registros con un colega y comprobar si les resulta claro.
Usa niveles de logs (y de forma correcta 👀)
Una buena práctica es utilizar el concepto de nivel de registro, permite clasificar la información que se registrará según su relevancia. Establecer el nivel de registro no es una tarea fácil. Sin embargo, usar troubleshootings ayudará mucho y habilitará filtros y visualización según el nivel, como por ejemplo buscar logs con el nivel "ERROR". Los niveles de registro comúnmente utilizados son:
- Info: Se utiliza para información general, diseño de desarrollo de acciones que pueden ser impulsadas por el usuario o específicas del sistema.
logger.info("[UserController] Starting process to get userinformation.").
- Warn: Se utiliza para eventos que podrían convertirse en un posible error.
logger.warn("[UserRepository] Call to database to get user data took 60000 milliseconds, default time is 30000 milliseconds.").
- Error: Se utiliza para todas las condiciones de error, ya sean errores internos o externos.
logger.error("[UserService] An error occurred while searching the user's data, this user has the status of blocked.").
- Debug: Se utiliza para mostrar todo lo que sucede en el software, se usa comúnmente durante la depuración (ejecutar código paso a paso).
logger.debug("[UserService] The value of the user variable is {}", user).
Hay otros niveles de registros que su aplicación puede utilizar, cada nivel tiene su propósito y puede facilitar tanto su proceso de desarrollo de software como los futuros troubleshootings. Los niveles de registro son necesarios y esenciales para cualquier tipo de sistema. Te sugiero que te tomes un tiempo para estudiar los niveles de registro, ¿de acuerdo?
Agrega IDs de rastreo
Actualmente, la mayoría de los equipos de desarrollo de software han utilizado arquitectura de microservicios/sistemas distribuidos, permitiendo dividir una aplicación en partes pequeñas e independientes. Ante esta interdependencia, es importante utilizar logs para la trazabilidad de eventos, sin embargo, este punto es uno de los desafíos arquitectónicos y está exactamente relacionado con la trazabilidad de eventos entre las pequeñas partes que componen la aplicación. Un buen hábito es registrar los ID de seguimiento en los registros, esto ayudará al seguimiento y monitoreo necesarios de los eventos que suceden entre las “pequeñas partes”.
Conclusión
Los registros son fundamentales para el desarrollo y soporte del software. En este artículo, se presentaron buenas prácticas para logs, aunque es importante resaltar que existen muchas otras buenas prácticas (que tal vez no haya mencionado aquí) y pueden ayudarte en el proceso continuo de mejora de tus logs.
En la sección de referencias, hay excelentes artículos relacionados con buenas prácticas de registro. Siéntete libre de explorar y adquirir más y más conocimientos sobre las mejores prácticas para registros.
Referencias
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
Listopro Community da la bienvenida a todas las razas, etnias, nacionalidades, credos, géneros, orientaciones, puntos de vista e ideologías, siempre y cuando promuevan la diversidad, la equidad, la inclusión y el crecimiento profesional de los profesionales en tecnología.