Metadatos

Los metadatos son un concepto clave en Manufacturing Data Engine (MDE). Representa datos contextuales sobre hechos. Por ejemplo, lecturas o eventos de sensores. Los metadatos ayudan a responder preguntas como las siguientes:

  • ¿Qué etiqueta emitió una lectura numérica?
  • ¿Qué producto se estaba procesando en el momento en que se tomó una lectura numérica?
  • ¿A qué dispositivo pertenece un sensor?
  • ¿Qué turno estaba en curso en el momento en que ocurrió un evento?
  • ¿Qué receta estaba activa en el momento de la lectura?

El MDE distingue entre dos tipos de metadatos según su ritmo de cambio:

  1. Metadatos de la nube que cambian lentamente
  2. Metadatos incorporados que cambian rápidamente

Metadatos de Cloud

Los metadatos que cambian lentamente representan datos contextuales que permanecen sin cambios durante un período prolongado, por ejemplo, el contexto del activo que describe la máquina, la celda, la línea y la planta de un sensor determinado. MDE te permite modelar, administrar y explorar tus metadatos que cambian lentamente, y vincularlos a registros. Después de vincular los metadatos a los registros, puedes explorar tus registros con el contexto asociado.

Los metadatos que cambian lentamente en MDE se denominan metadatos de Cloud. Los metadatos de Cloud cumplen dos funciones en la solución:

  1. Contextualizar y categorizar registros
  2. Servir como fuente de datos maestros versionados sobre entidades de fabricación, como sensores, dispositivos y líneas

El MDE permite que los metadatos de la nube se obtengan desde el borde, se creen de forma manual con la interfaz web del MDE o se creen de forma programática con la API. Esta última te permite obtener metadatos de los sistemas existentes de administración de activos empresariales (EAM) o de administración de datos maestros (MDM).

Buckets de metadatos

Los buckets de metadatos de Cloud (también llamados "buckets" o "buckets de metadatos") son entidades de configuración que modelan un conjunto relacionado de datos contextuales que cambian lentamente. Por ejemplo, un bucket puede modelar los atributos de una etiqueta o una receta. Los discretizaciones se pueden considerar como dimensiones de datos en el dominio de la analítica de datos.

El atributo clave de un bucket de metadatos es su esquema. El esquema (expresado como un objeto de esquema JSON) define y restringe la estructura de las instancias de metadatos que contiene. Puedes crear una nueva versión del bucket de metadatos, pero las versiones nuevas deben cumplir con las reglas de versiones del bucket de metadatos de Cloud.

Los buckets son globales, lo que significa que se puede hacer referencia a ellos con cualquier tipo.

Instancias de metadatos

Las instancias de metadatos representan el "contenido" de los buckets de metadatos de Cloud. Cada instancia describe alguna entidad, como un activo, un proceso o un aspecto de los registros que se capturan. Las instancias tienen dos tipos de identificadores:

  1. Es un UUID (identificador único universal) generado por el sistema que identifica la instancia dentro del MDE.
  2. Es una clave natural que identifica la entidad fuera de MDE (por ejemplo, el número de serie de un sensor).

Las instancias de metadatos se versionan en la clave natural. Esto significa que MDE realiza un seguimiento de la evolución de los atributos para una clave natural determinada. Por ejemplo, una etiqueta con una clave natural "tag-123" podría comenzar en la celda "X", pero luego se podría trasladar a la celda "Y". El MDE almacena y registra la marca de tiempo de cada instancia, y le asigna un UUID único. Este UUID único te permite recuperar el historial de instancias para una clave natural, contextualizar registros con la instancia correcta en el momento de la transferencia y aplicar de forma retroactiva una instancia a registros anteriores en el momento de la consulta.

A partir de la versión 1.5.0, las instancias de metadatos se versionan y procesan según el event-time y no el processing time. Cuando envías instancias de metadatos con registros históricos, el MDE las versiona según el eventTimestamp del mensaje, lo que permite que los metadatos históricos y los recientes coexistan sin cambiar las instancias más recientes. Para obtener más información, consulta Control de versiones de buckets de metadatos.

MDE solo permite agregar instancias a un bucket que cumplan con el esquema de una versión específica de ese bucket.

Esquema del bucket de metadatos

Cada versión del bucket de metadatos contiene un esquema, y las instancias de metadatos solo se pueden agregar a una versión específica de un bucket. Los esquemas restringen aún más la estructura de las instancias de metadatos que se pueden agregar a una versión de bucket.

Los esquemas de bucket de metadatos se expresan como objetos de esquema JSON de acuerdo con la versión del 2019-09 de la especificación del esquema JSON.

Por ejemplo, si el esquema se agregó más tarde a una versión de bucket, se indicaría que cada objeto de instancia debe tener una propiedad llamada deviceName con el valor string, y esta propiedad es obligatoria. Consulta el siguiente ejemplo:

{
  "$schema": "https://json-schema.org/draft/2019-09/schema#",
  "type": "object",
  "properties": {
    "deviceName": {
      "type": "string"
    }
  },
  "required": ["deviceName"]
}

Validación de instancias de metadatos

Para que se inserten, las instancias de metadatos deben cumplir con el esquema definido para una versión específica del bucket de metadatos.

Tipos de buckets

El MDE define tres tipos de buckets:

  1. Buckets de etiquetas
  2. Buckets de registros
  3. Buckets de búsqueda

El tipo de bucket se define cuando se crea y no se puede cambiar después.

Buckets de etiquetas

Los buckets de etiquetas representan buckets que contextualizan las etiquetas. Esto significa que la clave natural de las instancias contenidas en el bucket debe ser el nombre de la etiqueta.

Buckets de registros

Los buckets de registros representan buckets que pueden contextualizar cualquier grupo de registros que compartan una clave natural común. La clave natural de las instancias de bucket de registros puede ser cualquier valor.

Buckets de búsqueda

Los buckets de búsqueda representan buckets que no contextualizan registros directamente, sino que proporcionan datos de referencia que se pueden usar en el analizador. La clave natural de las instancias de bucket de búsqueda puede ser cualquier valor.

Las instancias de bucket de registros nunca se vinculan a los registros. En su lugar, las instancias se pueden recuperar de un bucket de búsqueda llamando a la función mde::lookupByKey en una secuencia de comandos de Whistle. La función toma la búsqueda bucketName, bucketVersion y naturalKey como argumentos, y devuelve la instancia de metadatos más reciente para la clave natural proporcionada. Puedes usar la instancia para completar campos en un registro .proto en el analizador.

Control de versiones de buckets de metadatos

El esquema de los buckets de metadatos puede evolucionar. Sin embargo, debes crear una versión nueva de un bucket para modificar el esquema. Esta operación no afecta a las versiones de buckets existentes ni a las entidades de configuración existentes que hacen referencia a versiones anteriores de un bucket. Para garantizar la coherencia de los datos durante la vida útil de un bucket de metadatos, las versiones nuevas de los esquemas de los buckets de metadatos están sujetas a las siguientes restricciones:

Las versiones nuevas pueden hacer lo siguiente:

  • Se agregaron nuevos campos opcionales.
  • Marcar un campo obligatorio como opcional

Las versiones nuevas no pueden hacer lo siguiente:

  • Quita campos.
  • Cambiar el tipo de datos de los campos existentes
  • Marcar un atributo opcional como obligatorio

A partir de la versión 1.5.0, la resolución de las instancias de metadatos también se basa en la marca de tiempo del evento. Esto significa que MDE resuelve la instancia de metadatos que era más reciente en comparación con la hora del evento del registro. Esto generaliza el concepto de metadatos de vinculación de MDE para que funcione en diferentes momentos, lo que controla el mensaje fuente. Para mejorar la legibilidad de las consultas de las instancias de metadatos, MDE v1.5.0 introduce un nuevo campo llamado validFrom que designa el momento en que una instancia de metadatos en particular es efectiva. MDE usa este campo para verificar qué instancia de metadatos debe elegir según la hora del evento del mensaje fuente.

Por ejemplo, para una clave natural sensor-a, supongamos que hoy envías a MDE una instancia de metadatos con el siguiente valor:


{
    "naturalKey": "sensor-a",
    "instance": {
        "site": "ONE",
        "factory": "ONE",
        "floor": "ONE",
        "line": "ONE",
        "cell": "ONE"
    }
}

MDE versiona esta instancia según el valor de eventTimestamp del mensaje entrante, en el que se envió esta instancia de metadatos, y, como la marca de tiempo se estableció en hoy, MDE tratará esta instancia como la más reciente absoluta recibida hasta el momento para esa clave natural. El valor de validFrom para esta instancia de metadatos con versión nueva será el valor de eventTimestamp del mensaje entrante.

Ahora supongamos que envías una instancia de metadatos históricos (por ejemplo, del año pasado) para la misma clave natural sensor-a con el siguiente valor:


{
    "naturalKey": "sensor-a",
    "instance": {
        "site": "OLD",
        "factory": "OLD",
        "floor": "OLD",
        "line": "OLD",
        "cell": "OLD"
    }
}

En este ejemplo, la MDE compara esta instancia con las instancias de metadatos más recientes que estaban disponibles en la fecha eventTimestamp recibida o antes de ella (por ejemplo, el año pasado) y la insertará en el lugar correcto de las líneas de tiempo, lo que constituye la diferencia fundamental entre las versiones 1.4.x y 1.5.0. Cuando MDE recibe eventos de registros históricos, resuelve la entrada de metadatos históricos que era la más reciente en el momento del evento. En el siguiente diagrama, se muestra cómo funciona la lógica de procesamiento y vinculación:

Control de versiones de la lógica de metadatos

Vincula instancias de metadatos de Cloud a registros

Agregar contexto a un registro implica vincularlo a una instancia de metadatos. Esto se logra almacenando una referencia al UUID de la instancia de metadatos en el registro. MDE proporciona dos formas de crear este vínculo en el analizador:

  1. Proporcionando la clave natural de una instancia
  2. Proporcionando una instancia de metadatos de .proto

Por ejemplo, el receptor de datos de BigQuery almacena referencias a instancias de metadatos por bucket en un campo llamado cloud_metadata_ref. Este es un ejemplo de cómo aparece una referencia de instancia de metadatos en un registro de BigQuery:

{
  "id": "e4b66cb9-7c60-4473-b1a1-1954eca92405",
  "tag_name": "primepaintingrobot-01-airpressure",
  "type_version": "1",
  "event_timestamp": "2023-06-20 07:11:59.757000 UTC",
  "value": "762.53",
  "embedded_metadata": {},
  "materialized_cloud_metadata": {
    "device-metadata": {
      "deviceName": "example-device"
    }
  },
  "cloud_metadata_ref": {
    "device-metadata": {
      "bucket_number": 143,
      "bucket_version": 1,
      "instance_id": "50e156a0-dbd9-4f9b-bdc8-1e77574bc4b1"
    }
  },
  "ingest_timestamp": "2023-06-20 07:12:06.335000 UTC",
  "source_message_id": "8434396321424812"
}

Vincula un registro a una instancia de metadatos de Cloud con una clave natural

Puedes vincular un registro a una instancia de metadatos si proporcionas, en el analizador, una referencia a una versión del bucket de metadatos de Cloud y la clave natural de la instancia en el registro .proto. El MDE intercambia automáticamente la clave natural por el UUID de la instancia, si existe, y almacena el vínculo en el registro. Si hay varias instancias para la clave natural proporcionada, MDE elige la instancia más reciente (la instancia con el created_timestamp más reciente).

Si el bucket al que se hace referencia es un bucket de TAG, proporcionar una clave natural es opcional. Si se omite la clave natural, MDE usa el valor del campo tagName de forma predeterminada.

Para obtener información sobre cómo vincular registros a instancias de metadatos con una clave natural, consulta Cómo resolver un instance_id de metadatos por clave natural.

Vincula un registro a una instancia de metadatos de Cloud con una instancia de metadatos de proto

Puedes vincular un registro a una instancia de metadatos proporcionando una referencia a una versión del bucket de metadatos de Cloud y suministrando una instancia de metadatos de proto y, de manera opcional, una clave natural en el registro de proto en el analizador. Este método para vincular instancias de metadatos es particularmente útil si los mensajes fuente ya contienen información contextual para construir una instancia de .proto válida.

Ten en cuenta lo siguiente cuando vincules un registro a una instancia de metadatos de Cloud con una instancia de metadatos de proto:

  • Si omites la clave natural, MDE elegirá una automáticamente según el tipo de bucket.
  • Si omites la clave natural en una instancia de .proto dentro del contexto de un bucket de TAG, MDE elige automáticamente el tagName como clave natural.
  • Si omites la clave natural en una instancia de .proto dentro del contexto de un bucket de RECORD, MDE genera automáticamente un valor hash del objeto de mensaje y lo usa como clave natural.
  • Si la instancia de .proto proporcionada coincide con la instancia de metadatos más reciente para la clave natural proporcionada, MDE intercambia la instancia de .proto proporcionada por el UUID de la instancia coincidente y almacena el UUID en el registro.
  • Si la instancia de .proto proporcionada no coincide con la instancia de metadatos más reciente para la clave natural proporcionada, MDE crea una nueva instancia de metadatos para la clave natural proporcionada y almacena el UUID de la instancia recién creada en el registro. Este comportamiento del sistema te permite propagar de forma dinámica los buckets de metadatos con instancias generadas a partir de mensajes fuente.

Para obtener información sobre cómo vincular registros a instancias de metadatos con una instancia de metadatos .proto, consulta Cómo resolver un ID de instancia de metadatos por valor de instancia.

Materialización de instancias

En lugar de solo almacenar el UUID de una instancia de metadatos, los registros pueden incluir, de forma opcional, la instancia completa. Esto se denomina materialización. Este comportamiento se puede configurar para cada receptor a nivel del tipo, estableciendo el valor del campo materializeCloudMetadata de un receptor en true.

Por ejemplo, habilitar la materialización de metadatos para el receptor de BigQuery generará una fila como la siguiente para un registro que contiene una referencia de instancia de metadatos:

{
  "id": "e4b66cb9-7c60-4473-b1a1-1954eca92405",
  "tag_name": "primepaintingrobot-01-airpressure",
  "type_version": "1",
  "event_timestamp": "2023-06-20 07:11:59.757000 UTC",
  "value": "762.53",
  "embedded_metadata": {},
  "materialized_cloud_metadata": {
     "tag":{
       "bucket_number":143,
       "bucket_version":1,
       "instance":{
         "datatype":"float",
         "deviceID":"ppr-01",
         "deviceName":"primepaintingrobot-01",
         "vendor":"KUKA"
       }
     }
  },
  "cloud_metadata_ref": {
    "device-metadata": {
      "bucket_number": 143,
      "bucket_version": 1,
      "instance_id": "50e156a0-dbd9-4f9b-bdc8-1e77574bc4b1"
    }
  },
  "ingest_timestamp": "2023-06-20 07:12:06.335000 UTC",
  "source_message_id": "8434396321424812"
}

Metadatos incorporados

Los metadatos que cambian rápidamente representan datos contextuales que cambian a un ritmo acelerado. Entre los ejemplos típicos de metadatos que cambian rápidamente, se incluyen los contadores y los IDs que se incrementan automáticamente, como los números de serie o los IDs de transacción.

El MDE te permite estructurar, armonizar y transformar metadatos que cambian rápidamente con Whistle, y luego incorporarlos directamente en el registro completando un campo llamado embeddedMetadata en el registro .proto del analizador.

Todos los receptores de datos de MDE compatibles hacen que los metadatos incorporados estén disponibles. Por ejemplo, completar el campo embeddedMetadata en el registro .proto del analizador produciría una fila como esta para el registro resultante en BigQuery:

{
  "id": "e4b66cb9-7c60-4473-b1a1-1954eca92405",
  "tag_name": "primepaintingrobot-01-airpressure",
  "type_version": "1",
  "event_timestamp": "2023-06-20 07:11:59.757000 UTC",
  "value": "762.53",
  "embedded_metadata": {
    "transactionNumber": "1234"
  },
  "materialized_cloud_metadata": {},
  "cloud_metadata_ref": {},
  "ingest_timestamp": "2023-06-20 07:12:06.335000 UTC",
  "source_message_id": "8434396321424812"
}

Eliminación automática de metadatos

En ambos casos, tanto para los metadatos de registros como de etiquetas, el MDE realiza un seguimiento de los cambios que se producen en cada clave natural comparando cada instancia nueva con la instancia anterior. Cuando se produce un cambio en cualquiera de los atributos de la instancia, el MDE crea una versión nueva y la marca como la instancia efectiva más reciente. Por diseño, se espera que los metadatos de la etiqueta y del registro tengan una granularidad de miles y menos de cien mil. Estas restricciones permiten que el MDE indexe las instancias de metadatos a medida que provienen del borde o de la API sin afectar el rendimiento del procesamiento.

A veces, debido a errores de configuración, el analizador inyectará un campo de alta cardinalidad, como una marca de tiempo, en la instancia de metadatos, lo que generará una rápida proliferación de versiones para cada clave natural. Después de un cierto umbral, esto afecta negativamente el rendimiento de la transferencia. En algunos casos, esto puede provocar la detención total del procesamiento hasta que el administrador de la solución escale los servicios de infraestructura de nube subyacentes.

A partir de la versión 1.4.0, MDE aplica una cantidad máxima de instancias por clave natural para garantizar un rendimiento coherente. Cuando la cantidad de claves naturales se acerca a este umbral (el valor predeterminado es 200), MDE enviará una advertencia a la nueva API de notificaciones para informar al usuario sobre las claves naturales que tienen una gran cantidad de versiones de instancias de metadatos. Cuando el tamaño de la instancia de claves naturales supera el umbral, MDE borrará automáticamente las instancias antiguas del almacén interno. También enviará otra notificación a la API de Notifications para informar al usuario sobre las claves naturales que se borraron.

Tanto la advertencia como las actividades de eliminación también se registran en el registro, que se podría usar para crear una política de alertas en el Cloud Monitoring del proyecto.

Restricciones de nombres para los buckets de metadatos

El nombre de un bucket de metadatos puede contener lo siguiente:

  • Letras (mayúsculas y minúsculas), números y los caracteres especiales - y _
  • Puede tener hasta 255 caracteres.

Puedes usar la siguiente expresión regular para la validación: ^[a-z][a-z0-9\\-_]{1,255}$.

Si intentas crear una entidad que incumpla las restricciones de nomenclatura, recibirás un 400 error.