Metadados

Os metadados são um conceito fundamental no Manufacturing Data Engine (MDE). Ele representa dados contextuais sobre fatos. Por exemplo, leituras ou eventos de sensores. Os metadados ajudam a responder a perguntas como:

Qual tag emitiu uma leitura numérica?
Qual produto estava sendo processado no momento em que uma leitura numérica foi feita?
A qual dispositivo um sensor pertence?
Qual turno estava em andamento quando um evento aconteceu?
Qual receita estava ativa no momento de uma leitura?

O MDE distingue dois tipos de metadados com base na taxa de mudança:

Metadados da nuvem que mudam lentamente.
Metadados incorporados que mudam rapidamente.

Metadados da nuvem

Metadados que mudam lentamente representam dados contextuais que permanecem inalterados por um longo período, por exemplo, contexto de recursos que descreve a máquina, a célula, a linha e a planta de um determinado sensor. Com o MDE, é possível modelar, gerenciar e analisar seus metadados de mudança lenta e vinculá-los a registros. Depois que os metadados são vinculados aos registros, é possível explorar os registros usando o contexto associado.

Os metadados que mudam lentamente no MDE são chamados de metadados da nuvem. Os metadados da nuvem têm duas funções na solução:

Para contextualizar e categorizar registros.
Servir como uma fonte de dados mestres versionados sobre entidades de fabricação, como sensores, dispositivos e linhas.

Com o MDE, os metadados da nuvem podem ser originados da borda, criados manualmente usando a interface da Web do MDE ou criados programaticamente usando a API. Com ele, é possível extrair metadados de sistemas atuais de gerenciamento de ativos empresariais (EAM) ou de gerenciamento de dados mestres (MDM).

Intervalos de metadados

Os buckets de metadados do Cloud (também chamados de "buckets" ou "buckets de metadados") são entidades de configuração que modelam um conjunto relacionado de dados contextuais que mudam lentamente. Por exemplo, um bucket pode modelar os atributos de uma tag ou receita. Os agrupamentos podem ser considerados como dimensões de dados no domínio da análise de dados.

O atributo principal de um bucket de metadados é o esquema. O esquema (expresso como um objeto de esquema JSON) define e restringe a estrutura das instâncias de metadados contidas nele. É possível criar uma nova versão do bucket de metadados, mas elas precisam obedecer às regras de controle de versões do bucket de metadados da nuvem.

Os intervalos são globais, o que significa que podem ser referenciados por qualquer tipo.

Instâncias de metadados

As instâncias de metadados representam o "conteúdo" dos buckets de metadados da nuvem. Cada instância descreve alguma entidade, como um recurso, um processo ou um aspecto dos registros que estão sendo capturados. As instâncias têm dois tipos de identificadores:

Um UUID (identificador universal exclusivo) gerado pelo sistema que identifica a instância no MDE.
Uma chave natural que identifica a entidade fora do MDE (por exemplo, um número de série de um sensor).

As instâncias de metadados são versionadas na chave natural. Isso significa que o MDE acompanha a evolução dos atributos de uma determinada chave natural. Por exemplo, uma tag com uma chave natural "tag-123" pode começar na célula "X", mas depois ser movida para a célula "Y". O MDE armazena e marca com carimbo de data/hora cada instância e atribui a ela um UUID exclusivo. Esse UUID exclusivo permite recuperar o histórico de instâncias de uma chave natural, contextualizar registros com a instância certa na ingestão e aplicar uma instância retroativamente a registros anteriores no momento da consulta.

A partir da v1.5.0, as instâncias de metadados são versionadas e processadas com base no event-time e não no processing time. Quando você envia instâncias de metadados com registros históricos, o MDE cria versões dessas instâncias com base no eventTimestamp da mensagem. Isso permite que metadados históricos e recentes coexistam sem mudar as instâncias mais recentes. Para mais informações, consulte Buckets de metadados de controle de versões.

O MDE só permite adicionar instâncias a um bucket que esteja em conformidade com o esquema de uma versão específica dele.

Esquema de bucket de metadados

Cada versão de bucket de metadados contém um esquema, e as instâncias de metadados só podem ser adicionadas a uma versão específica de um bucket. Os esquemas restringem ainda mais a estrutura das instâncias de metadados que podem ser adicionadas a uma versão de bucket.

Os esquemas de bucket de metadados são expressos como objetos de esquema JSON de acordo com a versão 2019-09 da especificação do esquema JSON.

Por exemplo, se o esquema fosse adicionado posteriormente a uma versão de bucket, ele declararia que cada objeto de instância precisa ter uma propriedade chamada deviceName com o valor string, e essa propriedade é obrigatória. Veja o exemplo a seguir:

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

Validação de instâncias de metadados

As instâncias de metadados precisam obedecer ao esquema definido para uma versão específica do bucket de metadados para serem inseridas.

Tipos de buckets

O MDE define três tipos de buckets:

Buckets de tag
Buckets de registros
Buckets de pesquisa

O tipo de um bucket é definido quando ele é criado e não pode ser alterado depois.

Tags de bucket

Os buckets de tag representam buckets que contextualizam tags. Isso significa que a chave natural das instâncias contidas no bucket precisa ser o nome da tag.

Buckets de registros

Os intervalos de registros podem contextualizar qualquer grupo de registros que compartilham uma chave natural comum. A chave natural das instâncias de bucket de registro pode ser qualquer valor.

Buckets de pesquisa

Os intervalos de pesquisa representam intervalos que não contextualizam registros diretamente, mas fornecem dados de referência que podem ser usados no analisador. A chave natural das instâncias de bucket de pesquisa pode ser qualquer valor.

As instâncias de bucket de registros nunca são vinculadas a registros. Em vez disso, as instâncias podem ser recuperadas de um bucket de pesquisa chamando a função mde::lookupByKey em um script do Whistle. A função usa a pesquisa bucketName, bucketVersion e naturalKey como argumentos e retorna a instância de metadados mais recente para a chave natural fornecida. Você pode usar a instância para preencher campos em um registro proto no analisador.

Buckets de metadados com controle de versão

O esquema dos intervalos de metadados pode evoluir, mas é necessário criar uma nova versão de um intervalo para modificar o esquema. As versões de bucket e as entidades de configuração que referenciam versões anteriores de um bucket não são afetadas por essa operação. Para garantir a consistência dos dados durante todo o ciclo de vida de um bucket de metadados, as novas versões de esquemas estão sujeitas às seguintes restrições:

As novas versões podem:

Adicione novos campos opcionais.
Marcar um campo obrigatório como opcional.

As novas versões não podem:

Remova os campos.
Mudar o tipo de dados dos campos atuais.
Marcar um atributo opcional como obrigatório.

A partir da v1.5.0, a resolução das instâncias de metadados também se baseia no carimbo de data/hora do evento. Isso significa que o MDE resolve a instância de metadados mais recente em comparação com o horário do evento do registro. Isso generaliza o conceito de metadados de vinculação de MDE para funcionar em diferentes períodos, que são controlados pela mensagem de origem. Para melhorar a legibilidade da consulta das instâncias de metadados, o MDE v1.5.0 apresenta um novo campo chamado validFrom, que designa o momento em que uma instância de metadados específica entra em vigor. Esse campo é usado pelo MDE para verificar qual instância de metadados escolher com base no horário do evento da mensagem de origem.

Por exemplo, para uma chave natural sensor-a, suponha que você envie hoje para o MDE uma instância de metadados com o seguinte valor:


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

O MDE versiona essa instância com base no valor eventTimestamp da mensagem recebida, em que essa instância de metadados foi enviada. Como o carimbo de data/hora foi definido como hoje, o MDE trata essa instância como a mais recente recebida até agora para essa chave natural. O valor do validFrom para essa instância de metadados recém-versionada será o valor do eventTimestamp da mensagem recebida.

Agora suponha que você envie uma instância de metadados históricos (por exemplo, do ano passado) para a mesma chave natural sensor-a com o seguinte valor:


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

Neste exemplo, o MDE compara a instância com as instâncias de metadados mais recentes disponíveis na data ou antes da eventTimestamp recebida (por exemplo, no ano passado) e a insere no lugar certo nas linhas do tempo, que é a diferença fundamental entre as versões 1.4.x e 1.5.0. Quando o MDE recebe eventos de registros históricos, ele resolve a entrada de metadados históricos mais recente no momento do evento. O diagrama a seguir mostra como a lógica de processamento e vinculação funciona:

Lógica de metadados de controle de versão

Como vincular instâncias de metadados da nuvem a registros

Para adicionar contexto a um registro, vincule-o a uma instância de metadados. Isso é feito armazenando uma referência ao UUID da instância de metadados no registro. O MDE oferece duas maneiras de criar esse link no analisador:

Ao fornecer a chave natural de uma instância.
Ao fornecer uma instância de metadados proto.

Por exemplo, o gravador de dados do BigQuery armazena referências a instâncias de metadados por bucket em um campo chamado cloud_metadata_ref. Confira um exemplo de como uma referência de instância de metadados aparece em um registro do 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"
}

Como vincular um registro a uma instância de metadados da nuvem usando uma chave natural

É possível vincular um registro a uma instância de metadados fornecendo, no analisador, uma referência a uma versão de bucket de metadados da nuvem e a chave natural da instância no registro do proto. O MDE troca automaticamente a chave natural pelo UUID da instância, se houver, e armazena o link no registro. Se houver várias instâncias para a chave natural fornecida, o MDE vai escolher a mais recente (com o created_timestamp mais recente).

Se o bucket referenciado for um bucket TAG, fornecer uma chave natural será opcional. Se a chave natural for omitida, o MDE usará o valor do campo tagName por padrão.

Para informações sobre como vincular registros a instâncias de metadados usando uma chave natural, consulte Resolver um instance_id de metadados por chave natural.

Como vincular um registro a uma instância de metadados da nuvem usando uma instância de metadados proto

É possível vincular um registro a uma instância de metadados fornecendo uma referência a uma versão de bucket de metadados da nuvem e uma instância de metadados proto e, opcionalmente, uma chave natural no registro proto no analisador. Esse método de vinculação de instâncias de metadados é útil principalmente se as mensagens de origem já contiverem informações contextuais para construir uma instância proto válida.

Considere o seguinte ao vincular um registro a uma instância de metadados da nuvem usando uma instância de metadados proto:

Se você omitir a chave natural, o MDE vai escolher uma automaticamente, dependendo do tipo de agrupamento.
Se você omitir a chave natural em uma instância proto no contexto de um TAG bucket, o MDE vai escolher automaticamente o tagName como a chave natural.
Se você omitir a chave natural em uma instância proto no contexto de um RECORD bucket, o MDE vai gerar automaticamente um valor de hash do objeto de mensagem e usá-lo como a chave natural.
Se a instância proto fornecida corresponder à instância de metadados mais recente para a chave natural fornecida, o MDE vai trocar a instância proto fornecida pelo UUID da instância correspondente e armazenar o UUID no registro.
Se a instância de proto fornecida não corresponder à instância de metadados mais recente para a chave natural fornecida, o MDE vai criar uma nova instância de metadados para a chave natural fornecida e armazenar o UUID da instância recém-criada no registro. Esse comportamento do sistema permite preencher dinamicamente os intervalos de metadados com instâncias geradas de mensagens de origem.

Para informações sobre como vincular registros a instâncias de metadados usando uma instância de metadados proto, consulte Resolver um ID de instância de metadados por valor de instância.

Materialização de instâncias

Em vez de apenas armazenar o UUID de uma instância de metadados, os registros podem incluir a instância inteira. Isso é chamado de materialização. Esse comportamento pode ser configurado para cada gravador no nível do tipo, definindo o valor do campo materializeCloudMetadata de um gravador como true.

Por exemplo, ao ativar a materialização de metadados para o coletor do BigQuery, uma linha como esta será gerada para um registro que contém uma referência de instância de metadados:

{
  "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"
}

Metadados incorporados

Metadados que mudam rapidamente representam dados contextuais que mudam em um ritmo acelerado. Exemplos típicos de metadados que mudam rapidamente incluem contadores e IDs que são incrementados automaticamente, como números de série ou IDs de transação.

Com o MDE, é possível estruturar, harmonizar e transformar metadados em rápida mudança usando o Whistle e incorporá-los diretamente ao registro preenchendo um campo chamado embeddedMetadata no registro proto no parser.

Todos os coletores de dados de MDE compatíveis disponibilizam metadados incorporados. Por exemplo, preencher o campo embeddedMetadata no registro proto no analisador geraria uma linha como esta para o registro resultante no 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"
}

Exclusão automática de metadados

Para os dois, os metadados de registro e tag, o MDE acompanha as mudanças que ocorrem em cada chave natural comparando cada nova instância com a antiga. Quando há uma mudança em qualquer um dos atributos da instância, o MDE cria uma nova versão e a marca como a instância efetiva mais recente. Por design, espera-se que a tag e os metadados de registro estejam na granularidade de milhares e menos de cem mil. Essas restrições permitem que o MDE indexe as instâncias de metadados conforme elas vêm da borda ou da API sem afetar a taxa de transferência de processamento.

Às vezes, devido a erros de configuração, o analisador injeta um campo de alta cardinalidade, como um carimbo de data/hora, na instância de metadados, o que resulta em uma rápida proliferação de versões para cada chave natural. Depois de um determinado limite, isso afeta negativamente o desempenho da ingestão. Em alguns casos, isso pode levar à interrupção total do processamento até que os serviços de infraestrutura em nuvem subjacentes sejam escalonados pelo administrador da solução.

A partir da v1.4.0, o MDE impõe um número máximo de instâncias por chave natural para garantir uma performance consistente. Quando o número de chaves naturais se aproxima desse limite (o padrão é 200), o MDE envia um aviso para a nova API de notificações para informar ao usuário sobre as chaves naturais que têm um grande número de versões de instâncias de metadados. Quando o tamanho da instância de chaves naturais viola o limite, o MDE exclui automaticamente as instâncias antigas do repositório interno. Ele também vai enviar outra notificação para a API Notifications informando ao usuário sobre as chaves naturais que foram excluídas.

As atividades de aviso e exclusão também são informadas no registro, que pode ser usado para criar uma política de alertas no Cloud Monitoring do projeto.

Restrições de nomenclatura para buckets de metadados

Um nome de intervalo de metadados pode conter:

Letras (maiúsculas e minúsculas), números e os caracteres especiais - e _.
Pode ter até 255 caracteres.

Você pode usar a seguinte expressão regular para validação: ^[a-z][a-z0-9\\-_]{1,255}$.

Se você tentar criar uma entidade que viole as restrições de nomenclatura, vai receber um 400 error.