Norma para la observabilidad

Ámbito de aplicación de la norma

Esta norma es de aplicación para la implementación de la observabilidad, independientemente de las tecnologías utilizadas.

Las directrices que contiene la norma son independientes de la pila tecnológica utilizada para el desarrollo de la solución software. Los objetivos y características de la arquitectura no dependen de la tecnología de implementación.

Por tanto, al implementar la observabilidad con una tecnología específica, deben tenerse en cuenta:

• Las directrices y estándares referidos en esta norma.
• Otras normas específicas para la tecnología utilizada.

Puedes conocer en esta sección  cómo se marca la obligatoriedad de cumplimiento de las directrices que componen la norma.

Instrumentación

DIR_01 Instrumentación automática

OBLIGATORIO Se utilizará la instrumentación automática siempre que sea posible.

La instrumentación automática reduce el esfuerzo de desarrollo, minimiza errores y garantiza la consistencia de la instrumentación. Adicionalmente a esto la instrumentación automática permite que la observabilidad abarque de forma eficaz a bibliotecas, frameworks o código legacy.

DIR_02 Configuración de la instrumentación automática

OBLIGATORIO Cuando se use instrumentación automática, se configurará y no se dejarán los valores por defecto.

Ejemplo: el filtrado de spans o el ajuste de la frecuencia de muestreo.

DIR_03 Uso combinado de instrumentación automática y manual

RECOMENDADO Se combinará la instrumentación automática con la instrumentación manual cuando sea necesario.

La instrumentación automática no siempre cubre todos los casos de uso. En algunos casos, será necesario complementar la instrumentación automática con instrumentación manual para capturar información específica o personalizar el comportamiento de la instrumentación.

Ejemplo: Añadir instrumentación manual para capturar atributos específicos o rastrear operaciones personalizadas.

DIR_04 Contexto de OpenTelemetry

OBLIGATORIO Se utilizará el contexto de OpenTelemetry.

El contexto de OpenTelemetry permite propagar información a través de las diferentes capas de la aplicación incluyendo trazas, correlación y baggage.

DIR_05 Muestreo

RECOMENDADO Se utilizará una estrategia de muestreo.

El muestreo permite reducir la cantidad de datos de telemetría que se recopilan y almacenan, minimizando el impacto en el rendimiento y los costes de almacenamiento.

DIR_06 Validación y procesamiento de los datos 

RECOMENDADO Se validarán y procesarán los datos de telemetría antes de exportarlos.

La validación y el procesamiento de los datos de telemetría garantizan la calidad de los datos y facilitan el análisis.

Ejemplo: Eliminar datos duplicados, agregar información adicional, formatear los datos utilizando procesadores en el SDK de OpenTelemetry.

DIR_07 Pruebas

OBLIGATORIO Se implementarán pruebas de observabilidad.

En el caso de la instrumentación manual, es necesario realizar test unitarios que validen el correcto funcionamiento de la observabilidad.

Ejemplo: Pruebas unitarias para verificar que los spans se crean y se etiquetan correctamente, y que las métricas se registran con los valores esperados.

Métricas

DIR_08 Nomenclatura de métricas

OBLIGATORIO Se utilizarán nombres de métricas significativos y descriptivos.

Los nombres de las métricas reflejarán claramente lo que se está midiendo y seguirán una convención de nomenclatura consistente. Serán concisos, en minúsculas y usarán guiones bajos como separadores.

DIR_09 Unidades de medida

OBLIGATORIO Se utilizarán unidades de medida estándar.

Las unidades de medida serán claras y consistentes con los estándares del Sistema Internacional de Unidades (SI).

Ejemplo: requests_per_second, bytes_received, seconds

DIR_10 Etiquetas de métricas

OBLIGATORIO Se etiquetarán las métricas con información relevante.

Las etiquetas (atributos) permiten agregar contexto a las métricas y facilitar el análisis y la agregación de datos. Se utilizarán atributos semánticos predefinidos por OpenTelemetry siempre que sea posible.

DIR_11 Tipo de instrumento

OBLIGATORIO Se elegirá el tipo de instrumento adecuado.

Se elegirá el tipo de instrumento que mejor se adapte a la métrica que se está midiendo, entre los que define OpenTelemetry (Counter, Gauge, Histogram, etc.). 

DIR_12 Prefijos de agrupación

OBLIGATORIO Se utilizarán prefijos para agrupar las métricas.

Los prefijos ayudan a organizar las métricas y evitar conflictos de nombres, especialmente cuando se instrumentan múltiples servicios o componentes.

Ejemplo: http_requests_total, database_connections_active

Logs

DIR_13 Formato de logs

OBLIGATORIO Se utilizará un formato de log estructurado.

Los logs estructurados facilitan el análisis y la búsqueda de información, permitiendo la consulta y el filtrado eficiente.

Ejemplo: Uso de formato JSON

DIR_14 Información contextual

OBLIGATORIO Se incluirá información contextual relevante en los logs.

La información contextual ayuda a comprender el contexto de los eventos. Se utilizarán atributos semánticos predefinidos por OpenTelemetry.

DIR_15 Niveles del log

OBLIGATORIO Se utilizarán niveles de log. Los niveles de log (debug, info, warn, error) permiten filtrar y priorizar la información.

Ejemplo: logger.error("Error al conectar a la base de datos", exception)

DIR_16 Información sensible

OBLIGATORIO No se registrará información sensible. La información sensible, como contraseñas y datos personales, no debe registrarse en los logs.

DIR_17 Logs y trazas

OBLIGATORIO Se correlacionarán los logs con trazas. La correlación entre logs y trazas permite rastrear el flujo de una solicitud a través del sistema.

Ejemplo: Incluir el ID de la traza y el ID del span en los logs.

DIR_18 Framework

OBLIGATORIO Se utilizará un framework de logging compatible con OpenTelemetry.

Un framework de logging proporciona funcionalidades adicionales, como la configuración de niveles de log, la salida a diferentes destinos y la integración con OpenTelemetry.

Ejemplo: Log4j 2 con OpenTelemetry appender, Winston con OpenTelemetry transport.

DIR_19 Salida estándar de error

OBLIGATORIO Los logs se escribirán en la salida estándar de error. Se delegará la recopilación de la información en los mecanismos de recolección de eventos de log.

DIR_20 Formato de los mensajes

OBLIGATORIO Se normalizará el formato de mensajes acorde al estándar definido por OpenTelemetry. Para ello podremos apoyarnos en las librerías (SDK) desarrolladas por OpenTelemetry. Puedes consultar la referencia al estándar.

DIR_21 Traza de la pila

RECOMENDADO Se incluirá la traza de la pila en los logs de error. La traza de la pila proporciona información detallada sobre la causa del error, facilitando la depuración.

DIR_22 Atributos adicionales

RECOMENDADO Se enriquecerán los logs con información adicional. Se pueden añadir atributos adicionales a los logs para proporcionar más contexto, como el nombre de la clase, el nombre del método, la versión de la aplicación, etc.

Ejemplo: Incluir el nombre de la clase y el método en los logs.

Trazas

DIR_23 Nomenclatura de los spans

OBLIGATORIO Se dará nombres descriptivos a los spans. Los nombres de los spans deben reflejar la operación que se está rastreando, utilizando verbos que indiquen la acción realizada.

Ejemplo: http.server /users/{id}, database.query users

DIR_24 Etiquetado de los spans

OBLIGATORIO Se etiquetarán los spans con información relevante. Las etiquetas (atributos) permiten agregar contexto a los spans y facilitar el análisis de las trazas. Se utilizarán atributos semánticos predefinidos por OpenTelemetry.

DIR_25 Propagación del contexto de trazas

OBLIGATORIO Se propagará el contexto de la traza. El contexto de la traza se propagará a través de las diferentes capas de la aplicación y los servicios, incluyendo llamadas asincrónicas y a través de diferentes protocolos de comunicación. Se utilizarán propagadores de OpenTelemetry para propagar el contexto de la traza en cabeceras.

DIR_26 Causalidad entre spans

OBLIGATORIO Se establecerá la causalidad entre spans. La causalidad entre spans permite visualizar el flujo de la solicitud a través del sistema. Se establecerán las relaciones padre-hijo entre los spans.

DIR_27 Registro de excepciones y errores

OBLIGATORIO Se registrarán las excepciones y errores en los spans, incluyendo la información de la traza de la pila.

Ejemplo: span.recordException(exception)

DIR_28 Eventos en spans

RECOMENDADO Se añadirán eventos a los spans. Los eventos permiten registrar información adicional sobre la ejecución de un span, como el inicio y el fin de una operación, el envío de un mensaje o la ocurrencia de un error.

DIR_29 Atributos

RECOMENDADO Se utilizarán atributos para registrar información contextual. Los atributos permiten añadir información contextual a los spans, como el ID del usuario, el nombre del producto y la ubicación geográfica, facilitando el análisis y la búsqueda de trazas.

DIR_30 API de Baggage

RECOMENDADO Se utilizará la API de Baggage para propagar información contextual. La API de Baggage permite propagar información contextual a través de los diferentes spans de una traza, sin necesidad de añadirla como atributos a cada span.

Anexo: estándares

Open Telemetry

OpenTelemetry es un estándar que proporciona una forma unificada de recolectar, procesar y exportar datos de telemetría (trazas, métricas y registros). Está diseñado para ser interoperable, permitiendo a los desarrolladores instrumentar sus aplicaciones de manera efectiva.

• Consulta la especificación del estándar en su última versión