NOR_EDA v01r00

Ámbito de aplicación de la norma

Esta norma es de aplicación en desarrollos que impliquen la adopción de un enfoque basado en el procesamiento y la reacción a eventos .

Las directrices que contiene la norma son independientes de la pila tecnológica que se adopte para la arquitectura de eventos. Los objetivos y características de la arquitectura no están vinculados a la tecnología de implementación.

Por tanto, al implementar un sistema basado en eventos con una tecnología específica, hay que considerar:

• Las directrices y estándares referidos en esta página.
• Otras normas particulares para la implementación de dicha tecnología.

Diseño

Convenciones para el diseño, estructura y contenido de los mensajes que reflejen cambios significativos en el estado del sistema y tengan un propósito específico

DIR_01 Propósito del evento

OBLIGATORIO Se definirá claramente el propósito de cada tipo de evento con nombres del mensaje descriptivos y significativos para facilitar su comprensión y uso por parte de los consumidores.

Cada evento debe tener un propósito específico y claro. Esto facilita la comprensión de los eventos por parte de los consumidores y asegura que se utilicen de manera adecuada.

Ejemplo: UsuarioCreado, TicketActualizado.

DIR_02 Relevancia del evento

OBLIGATORIO Los eventos representarán cambios significativos en el estado del sistema que serán notificados a otros sistemas o componentes, evitando eventos triviales o redundantes.

Ejemplo: ReservaCancelada es significativo, mientras que un mensaje CiudadConsultada puede ser menos relevante para el control de operaciones.

DIR_03 Estructura de datos

OBLIGATORIO Se definirá una estructura de datos consistente para cada tipo de mensaje utilizando un formato como Avro o JSON.

Se definirá una estructura de datos coherente para cada tipo de mensaje para garantizar su procesamiento uniforme. Esto facilita la interoperabilidad entre los diferentes componentes del sistema. Se deberá utilizar los Schema Registry ( Ver DIR_5.3)

Ejemplo (AVRO):
messages:
  userSignedUp:
    payload:
      schemaFormat: 'application/vnd.apache.avro;version=1.9.0'
      schema:
        type: record
        name: UserSignedUp
        namespace: com.company
        doc: User sign-up information
        fields:
          - name: userId
            type: int
          - name: userEmail
            type: string

DIR_04 Formato de la nomenclatura de campos

RECOMENDADO Los campos identificativos de las cabeceras o del cuerpo del mensaje estarán definidos en un formato que siga el estándar CamelCase.

De forma general, los campos identificadores de un mensaje deben estar definidos en formato CamelCase. Se contempla el uso de otro tipo de estructura para dichos identificadores cuando la tecnología que procesa dicho mensaje así lo precise.

DIR_05 Distribución y trazabilidad de los mensajes

OBLIGATORIO Los mensajes incluirán las propiedades necesarias para su distribución y trazabilidad.

Los mensajes incluirán las siguientes propiedades estándar para permitir una adecuada gestión y trazabilidad de los eventos en sistemas distribuidos:

Propiedades obligatorias en los mensajes

• Topic: Define el topic donde se publicará el mensaje. Esta propiedad debe ser especificada por el productor para asegurar que el mensaje sea enviado al canal adecuado.
• Timestamp: Marca el momento en que el mensaje fue creado o agregado al log, y suele ser configurado por el productor o generado automáticamente (usualmente Create Time o Log Append Time).
• Payload: Cuerpo del mensaje.

Propiedades opcionales en los mensajes

• Key: Clave opcional utilizada para asegurar que los eventos relacionados (por ejemplo, un mismo pedido) se envíen a la misma partición, manteniendo el orden de los mensajes dentro de esa partición.

Ejemplo (JSON):
{
 "topic":"tramite-events",
 "timestamp": "2024-10-07T12:34:56.789Z",
 "key": "tramite-12345",
 "payload: {
 			...
           }
}

DIR_06 Cabeceras de los mensajes

RECOMENDADO Se incluirán cabeceras relevantes en los mensajes.

Se incluirán las cabeceras relevantes en la sección headers de los mensajes para proporcionar contexto adicional y facilitar su procesamiento y depuración. Estos metadatos pueden ser opcionales y definidos por cada productor, permitiendo flexibilidad en la personalización según los requisitos del servicio o aplicación.

Metadatos opcionales recomendados en headers:

• contentTipe: Define el tipo de contenido, por ejemplo, "application/json".
• traceId: Útil para la trazabilidad de solicitudes en arquitecturas de microservicios.
• userId: Información sobre el usuario que desencadena o se relaciona con el evento.
• service: Indica el servicio que produjo el mensaje
• producerId: Identificador opcional del productor para facilitar la auditoría y el seguimiento.
• eventOccurrenceTime: Marca el momento en que realmente ocurrió el evento de negocio que puede ser diferente  del timestamp de envío.

Además de los metadatos indicados puede añadirse en la sección headers cualquier metadato necesario para el negocio.

Ejemplo (JSON):
        {
        "topic": "tramite-events",
        "timestamp": "2024-04-17T10:00:00Z",
        "headers":
        {
        "contentType": "application/json",
        "traceId": "abc123",
        "userId": "user789",
        "service": "tramite-service",
        "producerId": "tramite-service-prod-1",
        "eventOccurrenceTime": "2024-10-07T12:30:00.000Z"
        },
        "payload":
        {
        ...
        }
        }

DIR_07 Nivel de detalle de los mensajes

RECOMENDADO Se mantendrá un nivel de detalle en los mensajes adecuado, para evitar que sean excesivamente grandes o pequeños.

Se mantendrá una granularidad coherente en los mensajes para que tengan una extensión adecuada. Esto garantiza que los eventos reflejen los cambios en el sistema sin ser demasiado detallados o excesivamente generales.

Ejemplo: En lugar de un mensaje que contenga todos los detalles de un trámite, un evento como FechaTramiteActualizado es más útil que un evento genérico de TramiteActualizado.

DIR_08 Validación de los mensajes

OBLIGATORIO Se validará que los mensajes cumplan con la estructura y los requisitos de contenido esperados.

Se implementará una validación de que los mensajes cumplan con la estructura y los requisitos de contenido esperados. Esto ayuda a mantener la integridad y la consistencia de los datos. (DIR_5.2)

Ejemplo: Valida que un mensaje TicketCreado incluya campos obligatorios como el identificador del ticket, la fecha y el usuario

DIR_09 Atributos opcionales

RECOMENDADO Se definirán los atributos que pueden ser opcionales. Estos atributos pueden proporcionar información adicional según sea necesario.

Ejemplo: Un evento de CompraRealizada podría incluir un atributo opcional como moneda.

DIR_10 Consistencia en los nombres de los campos

OBLIGATORIO Se mantendrá consistencia en los nombres de los campos para evitar confusiones y errores de interpretación.

Ejemplo: Si un mensaje tiene un campo llamado idPedido, todos los eventos relacionados con pedidos deben seguir la misma convención de nombres.

Reglas y convenciones para la nomenclatura de los topics de Kafka que reflejen el propósito y el contenido de los eventos que contienen

DIR_11 Claridad en nombres de los topics

OBLIGATORIO Los nombres de los topics serán claros y descriptivos.

Los nombres de los topics (channel en AsyncAPI) reflejarán el propósito y el contenido de los eventos que contienen, facilitando su comprensión e identificación. Para ello se agregará información contextual con prefijos y sufijos significativos.

Ejemplo: orden-creada, pago-realizado, usuario-actualizado.

DIR_12 Estructura de los topics

OBLIGATORIO Los topics se agruparán y categorizarán en una estructura jerárquica.

Se utilizará una convención de nomenclatura que refleje una estructura de tipo "dominio.subdominio.nombre-evento" para organizar los topics de manera coherente y facilitar su gestión.

Ejemplo: ventas.orden-creada, ventas.pago-realizado, log.error, log.acceso.

DIR_13  Reglas básicas para la nomenclatura de los topics

OBLIGATORIO Se seguirán convenciones consistentes para la nomenclatura de los topics.

Se seguirán las reglas de nomenclatura de los topics en toda la arquitectura para una organización clara y una fácil gestión:

• Utilizar siempre minúsculas
• Separador de palabras con guiones o guiones bajos
• No usar caracteres especiales

DIR_14 Nombres de aplicaciones en la nomenclatura de los topics

OBLIGATORIO No se incluirán nombres de aplicaciones en los nombres de los topics*

Se evitarán nombres de aplicaciones como parte del nombre del topic, ya que puede generar un acoplamiento excesivo y problemas de mantenimiento.

* Se establece como OBLIGATORIO pero podrán darse excepciones que deberán ser analizadas y validadas. 

Ejemplo: Necesidad de reparticionar un topic o hacer inner join de dos topics

DIR_15 Números de versión o partición en los nombres de los topic

OBLIGATORIO No se agregarán números de versión o número de partición al nombre del topic*

No se añadirán números de versión o número de partición al nombre del topic, ya que puede provocar la creación innecesaria de muchos topics y problemas de compatibilidad entre versiones.

* Se establece como OBLIGATORIO pero podrán darse excepciones que deberán ser analizadas y validadas. 

Ejemplo: Necesidad de reparticionar un topic o hacer inner join de dos topics

DIR_16 Nombres de productores o consumidores en los nombres de los topic

OBLIGATORIO No se agregarán nombres de los productores o consumidores al nombre del topic.*

Los nombres de los topics no estarán vinculados a los nombres de los servicios, a menos que sean exclusivamente internos a un único servicio y no estén destinados a ser producidos o consumidos por ningún otro servicio externo.

* Se establece como OBLIGATORIO pero podrán darse excepciones que deberán ser analizadas y validadas. 

Ejemplo: Necesidad de reparticionar un topic o hacer inner join de dos topics

DIR_17 Longitud de los nombres de los topics y campos del evento

OBLIGATORIO Los nombres de los topics y los campos del evento serán concisos.

Los nombres serán cortos, con una longitud suficiente para ser descriptivos y facilitar su comprensión. 

Construcción

Estándares para la implementación de productores y consumidores de eventos, asegurando la consistencia en la forma en que se publican y consumen los eventos

DIR_18 Nomenclatura de productores y consumidores

OBLIGATORIO Se seguirán las convenciones de nomenclatura de productores y consumidores.

Los clientes de productores y consumidores seguirán una convención de nombres descriptiva y coherente, que refleje su función y contexto dentro del sistema. Esto garantiza consistencia y facilita la identificación y comprensión del propósito de cada clase cliente.

Ejemplo: una clase cliente responsable de enviar eventos de registro de actividad podría llamarse RegistroActividadProducer y por tanto otra que consuma dicho evento se llamaría RegistroActividadConsumer.

DIR_19 Distribución de carga

OBLIGATORIO Se configurará el manejo de las particiones de los topics para distribuir la carga y garantizar un rendimiento adecuado.

Los productores especificarán la clave de partición adecuada para asegurar que los mensajes relacionados se envíen a la misma partición y se procesen en orden.

DIR_20 Seguimiento de la entrega

OBLIGATORIO Se implementarán políticas para la retransmisión de mensajes en caso de fallos temporales en la entrega.

Se implementarán estrategias de reintento con un límite máximo de intentos para manejar errores temporales, como problemas de red o indisponibilidad del servidor.

DIR_21 Gestión de errores en productores y consumidores

OBLIGATORIO Se implementarán lógicas de gestión de errores en los productores y consumidores.

Se registrarán errores y eventos importantes en los logs con suficiente detalle, incluyendo información como la marca de tiempo, el tipo de error y el contexto relevante.

DIR_22 Protección de productores y consumidores

OBLIGATORIO Se establecerán políticas de seguridad y autorización para proteger los productores y consumidores de eventos, garantizando que solo los usuarios autorizados puedan acceder a ellos.

Se implementará autenticación basada en certificados SSL/TLS para garantizar la seguridad de las conexiones entre productores, consumidores y brokers.

DIR_23 Documentación de productores y consumidores

RECOMENDADO Se documentará de forma detallada la implementación de productores y consumidores, incluyendo configuraciones, dependencias, versiones, etc.

Se documentarán los parámetros de configuración utilizados, las dependencias de bibliotecas externas y ejemplos de uso para los desarrolladores.

DIR_24 Documentación de la entrega

RECOMENDADO Se documentará de manera detallada la garantía de entrega en sistemas de eventos, especificando si se utiliza el modelo at-most-once, at-least-once o exactly-once y cómo se maneja la transaccionalidad de los eventos.

Esta documentación incluirá las configuraciones técnicas necesarias para garantizar la entrega, como la configuración de offsets, reintentos y confirmaciones de mensajes.

La documentación también debe abordar el impacto en la consistencia de los datos y cómo se manejan las transacciones en caso de fallo, garantizando la integridad del sistema. 

Reglas de validación de datos en los productores y consumidores de eventos, asegurando la integridad y la coherencia de los datos que se publican y consumen

DIR_25 Validación de formato y estructura de datos en productores y consumidores

OBLIGATORIO Los productores y consumidores validarán el formato y la estructura de los datos para garantizar su integridad.

Si no se utiliza un Schema Registry, se validará que los datos publicados y consumidos cumplan con el formato y la estructura esperados, evitando errores de procesamiento y garantizando la consistencia de los datos. Si se usa Schema Registry se comprobará que las validaciones que realiza el componente son suficientes, en caso de que no lo sean, se completarán con validaciones en los productores y consumidores.

Ejemplo: Verificar que un campo de fecha tenga el formato adecuado (por ejemplo, "YYYY-MM-DD") antes de publicar un evento.

DIR_26 Validación de valores en los datos en productores y consumidores

OBLIGATORIO Los productores y consumidores validarán los valores permitidos para los datos.

Se definirán reglas para validar que los valores de los campos de datos estén dentro de rangos aceptables o sean valores válidos según las reglas de negocio, evitando la publicación o el consumo de datos incorrectos. Siempre que sea posible, se utilizará un Schema Registry y se definirá el formato del esquema del mensaje incluyendo el rango de valores permitidos. Se comprobará que las validaciones definidas en el Schema Registry son suficientes, en caso de que no lo sean, se completarán con validaciones en los productores y consumidores.

Ejemplo: Verificar que un campo de cantidad no sea negativo antes de publicar un evento.

DIR_27 Validación de relaciones entre datos

RECOMENDADO Se validarán las relaciones entre diferentes datos dentro de un mensaje.

Se asegurará que las relaciones entre los datos dentro de un mensaje son coherentes y válidas, evitando inconsistencias que puedan surgir de relaciones incorrectas o incompletas entre los datos. 

Ejemplo: Verificar que un número de identificación de un ciudadano referenciado en un evento exista en el sistema antes de publicar o consumir el evento.

DIR_28 Validación de compatibilidad en productores y consumidores

RECOMENDADO Se validará el esquema y la versión de los datos para garantizar la compatibilidad.

En el caso de usar Schema Registry , se utilizará un esquema de datos versionado. El Schema Registry validará la versión específica del esquema para asegurar la compatibilidad entre productores y consumidores. Si se usa un esquema de datos, pero no un Schema Registry o las validaciones de este componente no son suficientes, se completarán con validaciones en los productores y consumidores.  ( Ver DIR_6.2)

DIR_29 Validación del tamaño del mensaje

OBLIGATORIO Se comprobará si en el broker esta bien definido el tamaño del mensaje para evitar desbordamientos.

DIR_30 Traza de mensajes

RECOMENDADO Cuando un mensaje no sea válido, se registrará en las trazas de logs.

En el proceso de validación de formato, estructura y contenido de un mensaje, se recomienda registrar el error en los logs del sistema

Procedimientos y estándares para registrar los esquemas de los eventos en el Schema Registry

DIR_31  Formato de los esquemas de eventos

RECOMENDADO Se definirán los esquemas de eventos utilizando Avro o JSON en su defecto:

Se recomienda definir los esquemas de eventos en Avro como formato preferido, dadas sus ventajas en eficiencia y soporte para la evolución de esquemas, incluyendo la especificación de cada campo, su tipo de datos, restricciones opcionales (como valores predeterminados) y la versión correspondiente, asegurando la interoperabilidad y la compatibilidad entre diferentes sistemas. Sin embargo, se permite el uso de JSON como alternativa cuando sea necesario o preferible por razones específicas del proyecto o del equipo de desarrollo.

DIR_32 Validación de los esquemas de eventos

OBLIGATORIO Los esquemas de eventos se validarán antes de su registro en el Schema Registry.

Se implementará lógica de validación para asegurar que los esquemas de eventos cumplen con los requisitos de formato y estructura definidos y compatibilidad con la infraestructura y los consumidores previstos antes de ser registrados en el Schema Registry. Esto incluye verificar la validez sintáctica del esquema, su compatibilidad con versiones anteriores y su capacidad para representar correctamente los datos que se espera que maneje.

Ejemplo: Configurar la validación de esquemas en los productores y consumidores de eventos utilizando la biblioteca de Avro para Java proporcionada por Apache Kafka, o implementando lógica personalizada de validación de esquemas utilizando las API nativas de Kafka.

DIR_33 Registro de los esquemas de eventos

OBLIGATORIO Los esquemas de eventos se registrarán en el Schema Registry.

Se registrarán los esquemas de eventos en el Schema Registry mediante las diferentes opciones disponibles. Esto incluye la utilización de herramientas de línea de comandos, librerías cliente, o integración con frameworks de desarrollo, según las necesidades del proyecto y las preferencias del equipo.

Ejemplo: Registrar un esquema en el Schema Registry utilizando la herramienta de línea de comandos kafka-schema-registry, integrar la funcionalidad de registro en una aplicación Java utilizando la librería kafka-schema-registry-client, o utilizar un conector específico de Apache Kafka para integrar la funcionalidad de registro con un framework de desarrollo como Springboot.

DIR_34 Documentar los esquemas de eventos

RECOMENDADO Documentar de forma detallada cada esquema registrado en el Schema Registry:

Cada vez que se registre un esquema en el Schema Registry, se recomienda generar y mantener una documentación completa que describa su estructura, propósito y uso previsto. Esto incluye información sobre los campos del esquema, sus tipos de datos, cualquier restricción o validación aplicada, así como ejemplos de datos que cumplen con el esquema.

Ejemplo: Crear y mantener un repositorio de documentación técnica que contenga descripciones detalladas de cada esquema registrado en el Schema Registry, junto con ejemplos de datos válidos y ejemplos de cómo se espera que se utilicen en la aplicación. Esta documentación debe estar fácilmente accesible para todos los desarrolladores y equipos que trabajen con los esquemas.

Políticas para el versionado de esquemas en el Schema Registry, incluyendo cómo manejar cambios en la estructura de los eventos y cómo gestionar las compatibilidades de versiones

DIR_35 Nomenclatura de versiones de los esquemas

OBLIGATORIO Se utilizarán números de versión semántica para identificar y gestionar las diferentes versiones de los esquemas en el Schema Registry.

Se adoptará una convención de numeración de versiones semántica, que conste de tres números (MAJOR.MINOR.PATCH), para identificar cada cambio en la estructura del esquema. Los cambios mayores indican incompatibilidad con versiones anteriores, los cambios menores añaden funcionalidades de forma retrocompatible, y los cambios de parche corrigen errores sin alterar la compatibilidad.

Ejemplo:

v1.0.0: Versión inicial del esquema. v1.1.0: Se añade un nuevo campo opcional al esquema. v2.0.0: Se realiza un cambio mayor en la estructura del esquema que rompe la compatibilidad con versiones anteriores.  

DIR_36 Evolución de los esquemas

RECOMENDADO Las reglas para la evolución de esquemas serán claras, basadas en los niveles de compatibilidad: Backward, Forward, Full o None.

Estas reglas guiarán cómo se gestionan los cambios en la estructura de los eventos, asegurando que las modificaciones no rompan la compatibilidad según el nivel de evolución seleccionado.

Se definirá qué tipos de cambios son permitidos según el nivel de compatibilidad y la versión del esquema:

• Compatibilidad Backward: Permite que los consumidores más antiguos puedan procesar eventos creados con nuevas versiones del esquema.  
  Ejemplo: En un cambio menor, se pueden añadir campos opcionales sin afectar la compatibilidad con versiones anteriores.
• Compatibilidad Forward: Permite que los consumidores más recientes puedan procesar eventos creados con versiones anteriores del esquema.  
  Ejemplo: Se pueden eliminar campos que no son críticos, siempre y cuando los consumidores más recientes no dependan de ellos.
• Compatibilidad Full: Garantiza que los consumidores, tanto antiguos como nuevos, puedan procesar eventos de cualquier versión del esquema.  
  Ejemplo: Solo se permiten cambios aditivos, como añadir campos opcionales, sin eliminar o modificar los existentes.
• Sin Compatibilidad (None): Permite cambios que pueden romper la compatibilidad.  
  Ejemplo: Un cambio mayor que requiere una migración de datos, como la eliminación de campos o cambios en la estructura fundamental del esquema.

DIR_37 Compatibilidad entre versiones de esquemas

OBLIGATORIO El sistema será compatible entre diferentes versiones de esquemas antes de su despliegue en producción.

Basándose en los niveles de compatibilidad indicados en DIR_6.2, se verificará que los cambios propuestos en la nueva versión de un esquema no deterioren la interoperabilidad entre productores y consumidores. Al notificar una nueva versión del esquema es recomendable que tanto productores como consumidores hagan pruebas de compatibilidad adaptadas al nivel de compatibilidad definido para ese esquema.

Seguridad

Establecimiento de políticas de autorización y gestión de acceso en topics

DIR_38 Autorización sobre topics

OBLIGATORIO Se deben definir políticas de autorización sobre los topics.

Es necesario establecer políticas claras que definan quién tiene acceso y qué operaciones pueden realizar en cada topic. De esta manera se garantiza que haya una comprensión clara de quién tiene autorización para realizar qué acciones en los topics, lo que ayuda a mantener la seguridad y la integridad de los datos. 

DIR_39 Mínimo privilegio y segregación de tareas

OBLIGATORIO Se seguirá el principio de mínimo privilegio y la segregación de tareas: 

Esto asegura que los usuarios tengan acceso solo a los recursos necesarios para realizar sus funciones, reduciendo así el riesgo de compromiso de datos y funciones críticas. Implementar un sistema de control de acceso efectivo es crucial para la seguridad de cualquier aplicación. 

DIR_40 Validación y saneamiento de las entradas

OBLIGATORIO Se validarán y codificarán las entradas de usuario para prevenir ataques de inyección de comandos del sistema operativo.

Este tipo de inyección viene dado cuando una entrada proporcionada por el usuario acaba siendo ejecutada en un comando de sistema operativo, pudiendo desembocar en la toma de control del servidor.

Para evitar este tipo de inyecciones, es necesario validar y sanitizar toda entrada del usuario. Crear una lista blanca de parámetros permitidos, y en el mejor de los casos, evitar ejecutar comandos de sistema operativo.         

DIR_41 Nivel de detalle de los permisos

OBLIGATORIO Se proporcionarán permisos con granularidad que permita definir quién puede realizar operaciones específicas en cada topic.

Esto promueve la especificidad en la definición de permisos, lo que permite un control más preciso sobre quién puede hacer qué en los topics.

DIR_42 Listas de control

OBLIGATORIO Se configurarán listas de control de acceso (ACL) para regular las autorizaciones en los topics.

La definición de ACL asegura que se utilicen mecanismos adecuados para controlar el acceso a los topics, lo que proporciona una capa adicional de seguridad. 

Ejemplo: Configurar una ACL que permita a un componente específico del sistema leer y escribir en un topic determinado.

DIR_43 Control de acceso basado en roles

OBLIGATORIO Si se utiliza RBAC (role based access control) se asignarán roles y responsabilidades específicos en función de las operaciones que necesiten realizarse en los topics.

Esta directriz facilita la gestión de autorizaciones al asignar roles específicos en función de sus responsabilidades en el sistema.

DIR_44 Registro de eventos críticos

RECOMENDADO Se implementará un sistema de LOG para procesos y operaciones específicas, enfocado en registrar eventos críticos relacionados con las operaciones de lectura, escritura y eliminación fuera del sistema.

Este sistema de LOG mejoraría significativamente la visibilidad y la trazabilidad de dichos eventos críticos.

Es importante que este sistema de auditoría para eventos críticos utilice un canal específico, que podría persistir los eventos en una base de datos o en otro sistema que permita una mayor rastreabilidad y facilidad de auditoría.

DIR_45 Revisión de las autorizaciones

RECOMENDADO Se revisará periódicamente las autorizaciones en los topics para garantizar su adecuación y cumplimiento.

De esta manera, se promueve la revisión regular de las políticas de autorización para asegurar que sigan siendo efectivas y estén alineadas con los requisitos de seguridad y cumplimiento. 

Ejemplo: Revisar trimestralmente las ACL y los roles asignados en los topics de Kafka para asegurarse de que reflejen correctamente la estructura y las necesidades del sistema.

Errores

Procedimientos para el manejo de errores en la producción y consumo de eventos, incluyendo la gestión de eventos no procesados y la respuesta a fallos

DIR_46 Errores de validación

OBLIGATORIO Los productores y consumidores manejarán adecuadamente los errores de validación:

Se implementarán mecanismos para manejar errores de validación de datos de manera adecuada, registrando información detallada sobre los errores y tomando acciones correctivas según corresponda. Para errores de validación el mensaje deberá ser enviado directamente a la DLQ para su posterior análisis y resolución ( Ver apartado políticas de reintentos).

Ejemplo: Registrar información sobre los errores de validación en un registro de auditoría y enviar alertas para su corrección.

DIR_47 Seguimiento de errores

RECOMENDADO Se implementará un sistema de registro de errores y excepciones para registrar los problemas de validación encontrados durante la producción y consumo de eventos:

De esta manera, se facilita la identificación y resolución de problemas al proporcionar información detallada sobre los errores de validación que se producen en el sistema. 

Ejemplo: Registrar los errores de validación junto con detalles como el tipo de error, el evento afectado y la fecha y hora en que ocurrió.

DIR_48 Política de aceptación de errores de validación

OBLIGATORIO Se establecerá una política que defina los niveles de aceptación para los errores de validación, especificando cómo deben manejarse y cuándo deben ser notificados:

Se definirá cómo deben tratarse los errores de validación y cuándo deben considerarse críticos, lo que facilita la toma de decisiones y la resolución de problemas. 

Ejemplo: Definir que los errores de validación menores puedan ser registrados para su análisis posterior, mientras que los errores críticos deben desencadenar una notificación inmediata mediante un sistema de alertas como Prometheus y Grafana.

DIR_49 Manejo de los errores e información

OBLIGATORIO Se implementarán mecanismos que manejen las situaciones inesperadas de manera segura y efectiva, sin revelar información confidencial sobre la aplicación o su infraestructura subyacente:

Los errores se manejarán de manera controlada y los usuarios recibirán mensajes de error claros y concisos, sin ofrecer información que pueda comprometer la seguridad del sistema.

Ejemplo: Cuando se emite un error de autenticación si se indica que el “usuario no existe”, se estaría proporcionando a un usuario malintencionado que pruebe con otro usuario hasta que el error que se muestre sea diferente, por ejemplo “contraseña incorrecta”. Esto hace que el usuario mal intencionado pueda deducir que ha encontrado un usuario válido del que pueda inferir mediante fuera bruta una posible contraseña.

Políticas para los reintentos automáticos y el enrutamiento de eventos no procesables a Dead Letter Queues para su posterior análisis y corrección

DIR_50 Número de reintentos

OBLIGATORIO Se establecerá el número máximo de intentos de reenvío de eventos que fallen en el procesamiento antes de ser enrutados a la Dead Letter Queue.

Se definirán también los intervalos de tiempo entre cada reintento, utilizando estrategias como el reintento exponencial.

Ejemplo: Se configura una política de retries automático con un máximo de 3 intentos y un intervalo de tiempo inicial de 5 segundos, que se incrementa exponencialmente en cada reintento.

DIR_51 Colas de mensajes

OBLIGATORIO Se definirán una o varias colas de mensajes (DLQs) dedicadas a almacenar eventos que no pudieron ser procesados después de varios intentos de reenvío.

Se establecerán políticas para el enrutamiento de estos eventos a las DLQs, incluyendo la clasificación basada en el tipo de error o la causa del error.

DIR_52 Seguimiento y gestión de eventos almacenados en las colas de mensajes

RECOMENDADO Se establecerán procedimientos y herramientas para seguir y gestionar los eventos almacenados en las colas de mensajes (DLQs).

Se pueden incluir alertas automáticas para notificar sobre la acumulación de eventos, mecanismos para la visualización y búsqueda de eventos en las DLQs, y la implementación de procesos de corrección para resolver los problemas subyacentes que causaron la falla en el procesamiento.

DIR_53 Errores no reintentables

RECOMENDADO Todos los eventos que generen errores no reintentables serán enviados automáticamente a una Dead Letter Queue (DLQ) para su posterior análisis y resolución, independientemente del tipo de error ocurrido:

Se implementará un mecanismo que capture todos los eventos que, tras fallar en su procesamiento, no puedan ser reintentados de manera automática. Estos eventos deben ser redirigidos a la DLQ, donde serán almacenados con suficiente información contextual para facilitar su diagnóstico. La DLQ será monitoreada regularmente, y los eventos en ella deben ser procesados por un equipo designado, con el fin de identificar la causa del fallo, corregirla y, si es posible, reprocesar los eventos para asegurar su correcta ejecución.

Pruebas

Políticas de pruebas sobre sistemas de eventos

DIR_54 Pruebas unitarias

OBLIGATORIO Se realizarán pruebas unitarias para cubrir el mínimo porcentaje exigido de código, validando todos los componentes elementales y sus distintas rutas lógicas.

Las pruebas unitarias son la primera línea de defensa en la detección de errores, por lo que es importante que cubran la mayor parte de la lógica de forma aislada del resto.

DIR_55 Pruebas de integración de componentes

OBLIGATORIO Se realizarán pruebas para comprobar que todos los componentes de la arquitectura de eventos se integran de manera correcta.

DIR_56 Pruebas de rendimiento

OBLIGATORIO Se realizarán pruebas de rendimiento (carga, picos y estrés) en entornos no productivos para validar que la solución de eventos implementada es capaz de responder a las necesidades para las que ha sido creada.

Anexo: estándares

Avro

El estándar de definición de esquemas Avro proporciona una especificación formal para la descripción de la estructura y semántica de los datos en el formato Avro. Avro es un sistema de serialización de datos desarrollado dentro del proyecto Apache Hadoop, diseñado para ser rápido, eficiente en términos de espacio y compatible con una variedad de lenguajes de programación.

La definición de esquemas Avro sigue un formato basado en JSON que permite especificar tipos de datos simples y complejos, como cadenas de caracteres, números, registros y enumeraciones, así como relaciones entre ellos. Este estándar define una serie de reglas y convenciones para la representación precisa de la estructura de datos, lo que facilita la interoperabilidad entre diferentes sistemas y aplicaciones.

 Entre los aspectos clave del estándar de definición de esquemas Avro se incluyen:

• Declaración de Tipos de Datos: Permite la declaración de una amplia gama de tipos de datos, incluyendo primitivos como cadenas de caracteres y números, así como tipos complejos como registros y arrays.
• Soporte para Enumeraciones: Permite la definición de enumeraciones para representar conjuntos predefinidos de valores.
• Definición de Registros Anidados: Permite la creación de registros anidados que contienen una combinación de campos simples y complejos.
• Especificación de Nombres y Espacios de Nombres: Facilita la organización y gestión de esquemas mediante la especificación de nombres descriptivos y la agrupación en espacios de nombres lógicos.
• Control de la Evolución de Esquemas: Proporciona mecanismos para la evolución controlada de los esquemas a lo largo del tiempo, permitiendo cambios como la adición o eliminación de campos sin romper la compatibilidad con versiones anteriores.
• En resumen, el estándar de definición de esquemas Avro establece una especificación clara y flexible para la descripción de datos en formato Avro, lo que facilita la interoperabilidad y la evolución de esquemas en entornos distribuidos y heterogéneos.

JSON Schema

JSON Schema es un estándar que define la estructura, el formato y las restricciones de los datos JSON. Puede ser utilizado junto con Avro para validar los mensajes JSON producidos o consumidos por los eventos de Kafka. 

Algunas consideraciones adicionales incluyen: 

• Validación de Esquemas JSON: JSON Schema proporciona una forma de definir la estructura esperada de los datos JSON, así como las restricciones sobre los valores de los campos. Esto puede ser útil para garantizar que los mensajes JSON producidos y consumidos por Kafka cumplan con ciertos requisitos de formato y contenido.
• Generación Automática de Esquemas: Herramientas como avro-tools proporcionan funcionalidades para generar automáticamente esquemas Avro a partir de JSON Schema y viceversa. Esto facilita la interoperabilidad entre sistemas que utilizan diferentes formatos de datos y simplifica el proceso de integración con Kafka.
• Validación de Mensajes en Tiempo Real: La validación de esquemas JSON puede ser realizada en tiempo real por los productores y consumidores de eventos de Kafka. Esto asegura que los mensajes que entran y salen del sistema cumplan con las expectativas de estructura y contenido definidas en el JSON Schema correspondiente.

GraphQL

GraphQL es un lenguaje de consulta y manipulación de datos desarrollado por Facebook. Aunque no es específico de Kafka, puede ser utilizado en combinación con Kafka para definir APIs que interactúan con eventos. Algunas consideraciones adicionales incluyen: 

• Definición de Esquemas GraphQL: GraphQL utiliza un esquema para definir los tipos de datos, las consultas permitidas y las mutaciones disponibles en una API. Estos esquemas pueden ser utilizados para describir las operaciones que producen y consumen eventos en Kafka, proporcionando una capa de abstracción sobre los detalles de implementación subyacentes.
• Integración con Kafka: Las APIs GraphQL pueden ser implementadas como consumidores y productores de eventos en Kafka. Esto permite a los clientes enviar consultas GraphQL que desencadenen la producción de eventos, así como suscribirse a eventos específicos para recibir actualizaciones en tiempo real.
• Flexibilidad en las Consultas: GraphQL permite a los clientes especificar exactamente qué datos desean recuperar de la API, lo que puede reducir la cantidad de datos transferidos entre el cliente y el servidor. Esto puede ser útil en entornos distribuidos donde la eficiencia en la transferencia de datos es importante.
• Documentación Automática: Muchos frameworks de GraphQL proporcionan herramientas para generar automáticamente documentación detallada de la API a partir del esquema GraphQL definido. Esto facilita la comprensión y el uso de la API por parte de los desarrolladores que interactúan con eventos en Kafka a través de GraphQL.

AsyncAPI

AsyncAPI es una especificación para describir APIs basadas en eventos de manera legible tanto por humanos como por máquinas. Aunque no es específico de Kafka, puede ser utilizado en combinación con Kafka para definir y documentar las interfaces de eventos.

Diagrama de comunicación en asyncapi

Lo que se conoce como evento sería el Mensaje en AsyncAPI, creado a partir de un schema definido. Dicho mensaje se publica sobre un Canal, lo que se conoce como Topic, para posteriormente ser consumido por los consumidores suscritos a él.

Algunas consideraciones adicionales incluyen: 

• Descripción de Eventos Asíncronos: AsyncAPI permite describir eventos asincrónicos y sus correspondientes canales de comunicación. Esto facilita la comprensión de cómo los eventos fluyen a través del sistema y qué acciones desencadenan.
• Definición de Operaciones de Producción y Consumo: AsyncAPI permite definir las operaciones que producen y consumen eventos en Kafka, así como los detalles específicos de cada operación, como los parámetros de entrada y salida.
• Documentación Automática: Al igual que con GraphQL, AsyncAPI proporciona herramientas para generar automáticamente documentación detallada de la API a partir de la especificación AsyncAPI. Esto facilita la comprensión y el uso de la API por parte de los desarrolladores que interactúan con eventos en Kafka a través de AsyncAPI.
• Validación de Especificaciones: AsyncAPI puede ser utilizado para validar las especificaciones de eventos, garantizando que cumplan con ciertas reglas y convenciones. Esto ayuda a mantener la coherencia y la integridad de las interfaces de eventos en el ecosistema de Kafka.
• Generación de Código y Clientes: Algunas herramientas de AsyncAPI proporcionan funcionalidades para generar automáticamente código y clientes a partir de la especificación AsyncAPI. Esto acelera el proceso de desarrollo al proporcionar una base sólida para la implementación de productores y consumidores de eventos.