Nautilus

Appearance

Formato de los mensajes ​

Formato Avro ​

En el Datahub se usa el formato de Avro ya que permite evolucionar los esquemas e ir creando nuevas versiones sin romper consumidores ni productores. Para ello hay que seguir dos reglas:

  • Los nuevos campos deben poseer un valor por defecto, es decir, poseer la propiedad default.
  • Borrar sólo los campos con un valor por defecto, es decir, que tengan la propiedad default.

Todos los mensajes que sean mandados al datahub deben cumplir el siguiente formato:

  • id: Campo compuesto de distintos identificadores que sirven para identificar el mensaje.
    • eventId: GUID del evento.
    • parentId : GUID del evento que desencadena la creación del nuevo evento (null si es el mensaje origen)​.
    • correlationId: Id de correlación de la transacción.
    • parentCorrelationIds: Id de correlación con la transacción padre (en principio debería ser null). Éste permitiría crear un nuevo proceso (transacción) a partir del anterior (por ejemplo creación de alarmas, consumos,…)​.
  • created: Fecha de creación​ del evento.
  • eventType: Tipo de evento. Recomendable poner el enumerado de tipos que se permiten y que no sea una cadena, ya que con una cadena puede haber problemas.​
  • payload: Aquí se define la información que va a llevar el evento y que es única para ese eventType.

Esquema de ejemplo:

Importante: El namespace del avro tiene que ser igual al nombre del topic o al nombre base del topic en caso de ser un topic multitenant.

js
{
  "type": "record",
  "name": "ejemplo",
  "namespace": "acua.event.ejemplo"
  "doc": "Información importante sobre el esquema que describa el topic",
  "fields": [
    {
      "name": "id",
      "type": {
        "type": "record",
        "name": "composite_id",
        "fields": [
          {
            "name": "eventId",
            "doc": "the event id",
            "type": "string"
          },
          {
            "name": "parentId",
            "doc": "the parent event id",
            "type": ["null", "string"],
            "default": null
          },
          {
            "name": "correlationId",
            "doc": "the correlation id of the main parent message",
            "doc": "id de co",
            "type": ["null", "string"],
            "default": null
          },
          {
            "name": "parentCorrelationIds",
            "doc": "the correlations ids of all the parent messages",
            "type": ["null", {
                "type": "array",
                "items": ["string"]
            }],
            "default": null
          }
        ]
      }
    },
    {
      "name": "created",
      "doc": "the creation timestamp",
      "type": "string"
    },
    {
      "name": "eventType",
      "doc": "allowed event types for the schema",
      "type": {
        "type": "enum",
        "name": "EventType",
        "symbols": ["type1", "type2"]
      }
    },
    {
      "name": "payload",
      "doc": "the event data",
      "type": {}
    }
  ]
}
{
  "type": "record",
  "name": "ejemplo",
  "namespace": "acua.event.ejemplo"
  "doc": "Información importante sobre el esquema que describa el topic",
  "fields": [
    {
      "name": "id",
      "type": {
        "type": "record",
        "name": "composite_id",
        "fields": [
          {
            "name": "eventId",
            "doc": "the event id",
            "type": "string"
          },
          {
            "name": "parentId",
            "doc": "the parent event id",
            "type": ["null", "string"],
            "default": null
          },
          {
            "name": "correlationId",
            "doc": "the correlation id of the main parent message",
            "doc": "id de co",
            "type": ["null", "string"],
            "default": null
          },
          {
            "name": "parentCorrelationIds",
            "doc": "the correlations ids of all the parent messages",
            "type": ["null", {
                "type": "array",
                "items": ["string"]
            }],
            "default": null
          }
        ]
      }
    },
    {
      "name": "created",
      "doc": "the creation timestamp",
      "type": "string"
    },
    {
      "name": "eventType",
      "doc": "allowed event types for the schema",
      "type": {
        "type": "enum",
        "name": "EventType",
        "symbols": ["type1", "type2"]
      }
    },
    {
      "name": "payload",
      "doc": "the event data",
      "type": {}
    }
  ]
}

Cómo plantear tus topics ​

  • Nombre del topic: Siempre usar un nombre que represente claramante los datos que están en el topic. Usar siempre nuestra convención de nombres.
  • Creando un topic para cada tipo de evento: Es lo que se suele pensar cuando usamos colas de mensajes, pero ¿realmente interesa que sea así?. Por ejemplo, si se tiene la entidad Cuenta, la cual tiene varios tipos de eventos, como ADDED,UPDATED y DELETED, y tenemos cada evento en un topic, puede llegar antes un mensaje del tipo DELETED que uno del tipo ADDED al leer de topics separados y eso podría generar un problema de inconsistencia de datos.
  • Definir correctamente el esquema Avro: Aunque Avro permite realizar evolutivos sobre un esquema, es bastante complicado cambiar la estructura del mismo, ya que sólo se permite hacer cambios en campos que poseen valores por defecto.

Documentación de los esquemas AVRO ​

La documentación avrodoc se genera cada día con los esquemas AVRO de cada entorno. Solo se visualizan los schemas cuyo namespace corresponde al nombre del topic donde se han publicado. La pipeline Jenkins que genera el entorno es DATAHUB_AVRO_DOCUMENTATION. Los enlaces de cada entorno: