Monitorar módulos gêmeos

Artigo
06/03/2024

Aplica-se a: IoT Edge 1.5 IoT Edge 1.4

Importante

O IoT Edge 1.5 LTS e o IoT Edge 1.4 LTS são versões com suporte. O IoT Edge 1.4 LTS chegará ao fim da vida útil em 12 de novembro de 2024. Se você estiver em uma versão anterior, confira Atualizar o IoT Edge.

Os módulos gêmeos do Hub IoT do Azure permitem monitorar a conectividade e a integridade das suas implantações do IoT Edge. Eles armazenam informações úteis sobre o desempenho dos módulos em execução no hub IoT. O agente do IoT Edge e os módulos de runtime de hub do IoT Edge mantêm o módulo gêmeos, $edgeAgent e $edgeHub, respectivamente:

$edgeAgent contém dados de integridade e conectividade sobre os módulos de runtime do agente do IoT Edge e do hub do IoT Edge e seus módulos personalizados. O agente do IoT Edge é responsável por implantar os módulos, monitorá-los e relatar o status da conexão para o Hub IoT do Azure.
$edgeHub contém dados sobre comunicações entre o hub do IoT Edge em execução em um dispositivo e o Hub IoT do Azure. Isso inclui o processamento de mensagens de entrada de dispositivos downstream. O hub do IoT Edge é responsável por processar as comunicações entre o Hub IoT do Azure e os dispositivos e módulos do IoT Edge.

Os dados são organizados em metadados e marcas, juntamente com os conjuntos de propriedades desejados e relatados nas estruturas JSON dos módulos gêmeos. As propriedades desejadas que você especificou no arquivo deployment.json são copiadas para os módulos gêmeos. O agente do IoT Edge e o hub do IoT Edge atualizam as propriedades relatadas dos módulos.

Da mesma forma, as propriedades desejadas especificadas para seus módulos personalizados no arquivo deployment.json são copiadas para o módulo gêmeo, mas sua solução é responsável por informar os valores de propriedade relatados.

Este artigo descreve como examinar os módulos gêmeos no portal do Azure, na CLI do Azure e no Visual Studio Code. Para saber como monitorar os dispositivos que recebem as implantações, confira Monitorar implantações do IoT Edge. Para ter uma visão geral do conceito de módulo gêmeo, confira Entender e usar os módulos gêmeos no Hub IoT.

Dica

As propriedades relatadas de um módulo de runtime podem estar obsoletas se um dispositivo IoT Edge for desconectado de seu hub IoT. Você pode executar ping no módulo $edgeAgent para saber se a conexão foi perdida.

Monitorar os módulos gêmeos do runtime

Para solucionar problemas de conectividade de implantação, examine os módulos gêmeos do runtime do agente do IoT Edge e do hub do IoT Edge e, em seguida, faça uma busca detalhada em outros módulos.

Monitorar o módulo gêmeo do agente do IoT Edge

O JSON a seguir mostra o módulo gêmeo $edgeAgent no Visual Studio Code com a maior parte das seções de JSON recolhidas.

{
  "deviceId": "Windows109",
  "moduleId": "$edgeAgent",
  "etag": "AAAAAAAAAAU=",
  "deviceEtag": "NzgwNjA1MDUz",
  "status": "enabled",
  "statusUpdateTime": "0001-01-01T00:00:00Z",
  "connectionState": "Disconnected",
  "lastActivityTime": "0001-01-01T00:00:00Z",
  "cloudToDeviceMessageCount": 0,
  "authenticationType": "sas",
  "x509Thumbprint": {
    "primaryThumbprint": null,
    "secondaryThumbprint": null
  },
  "version": 53,
  "properties": {
    "desired": { "···" },
    "reported": {
      "schemaVersion": "1.0",
      "version": { "···" },
      "lastDesiredStatus": { "···" },
      "runtime": { "···" },
      "systemModules": {
        "edgeAgent": { "···" },
        "edgeHub": { "···" }
      },
      "lastDesiredVersion": 5,
      "modules": {
        "SimulatedTemperatureSensor": { "···" }
      },
      "$metadata": { "···" },
      "$version": 48
    }
  }
}

O JSON pode ser descrito nas seções a seguir, começando na parte superior:

Metadados – Contém dados de conectividade. Curiosamente, o estado da conexão do agente do IoT Edge está sempre em um estado desconectado: "connectionState": "Disconnected". O motivo é que o estado de conexão pertence às mensagens D2C (dispositivo para nuvem), e o agente do IoT Edge não envia mensagens D2C.
Propriedades – Contêm as subseções desired e reported.
Properties.desired (recolhido) – Os valores de propriedade esperados definidos pelo operador no arquivo deployment.json.
Properties.reported – Valores de propriedade mais recentes relatados pelo agente do IoT Edge.

As seções properties.desired e properties.reported têm estruturas semelhantes e contêm metadados adicionais para informações de esquema, versão e runtime. Também está incluída a seção modules para quaisquer módulos personalizados (como SimulatedTemperatureSensor), e a seção systemModules para $edgeAgent e os módulos de runtime $edgeHub.

Ao comparar os valores de propriedade relatada com os valores desejados, é possível identificar discrepâncias e desconexões, e isso ajuda a solucionar problemas. Ao fazer essas comparações, verifique o valor relatado $lastUpdated na seção metadata da propriedade que você está investigando.

É importante examinar estas propriedades ao solucionar problemas:

exitcode – Qualquer valor diferente de zero indica que o módulo parou com uma falha. No entanto, os códigos de erro 137 ou 143 serão usados se um módulo tiver sido intencionalmente definido com o status parado.
lastStartTimeUtc – Mostra o DateTime em que o contêiner foi iniciado pela última vez. Esse valor será 0001-01-01T00:00:00Z se o contêiner não tiver sido iniciado.
lastExitTimeUtc – Mostra o DateTime em que o contêiner foi encerrado pela última vez. Esse valor será 0001-01-01T00:00:00Z se o contêiner estiver em execução e nunca tiver sido parado.

runtimeStatus – Pode ser um dos seguintes valores:

Valor	Descrição
unknown	Estado padrão até a implantação ser criada.
backoff	O módulo está agendado para iniciar, mas não está em execução no momento. Esse valor é útil para um módulo que está passando por alterações de estado na reinicialização. Quando um módulo com falha estiver aguardando a reinicialização durante o período de resfriamento, ele estará em um estado de retirada.
executando	Indica se o módulo está em execução no momento.
unhealthy	Indica que uma verificação de investigação de integridade falhou ou atingiu o tempo limite.
stopped	Indica que o módulo foi encerrado com êxito (com um código de saída zero).
falhou	Indica que o módulo foi encerrado com um código de saída de falha (diferente de zero). O módulo pode voltar ao estado de retirada dependendo da política de reinicialização em vigor. Esse estado pode indicar que o módulo apresentou um erro irrecuperável. A falha ocorre quando o MMA (Microsoft Monitoring Agent) não pode mais ressucitar o módulo, exigindo uma nova implantação.

Confira Propriedades relatadas do EdgeAgent para saber detalhes.

Monitorar o módulo gêmeo do hub do IoT Edge

O JSON a seguir mostra o módulo gêmeo $edgeHub no Visual Studio Code com a maior parte das seções de JSON recolhidas.

{
  "deviceId": "Windows109",
  "moduleId": "$edgeHub",
  "etag": "AAAAAAAAAAU=",
  "deviceEtag": "NzgwNjA1MDU2",
  "status": "enabled",
  "statusUpdateTime": "0001-01-01T00:00:00Z",
  "connectionState": "Connected",
  "lastActivityTime": "0001-01-01T00:00:00Z",
  "cloudToDeviceMessageCount": 0,
  "authenticationType": "sas",
  "x509Thumbprint": {
    "primaryThumbprint": null,
    "secondaryThumbprint": null
  },
  "version": 102,
    "properties": {
      "desired": { "···" },
      "reported": {
        "schemaVersion": "1.0",
        "version": { "···" },
      "lastDesiredVersion": 5,
      "lastDesiredStatus": { "···" },
      "clients": {
        "Windows109/SimulatedTemperatureSensor": {
          "status": "Disconnected",
          "lastConnectedTimeUtc": "2020-04-08T21:42:42.1743956Z",
          "lastDisconnectedTimeUtc": "2020-04-09T07:02:42.1398325Z"
        }
      },
      "$metadata": { "···" },
      "$version": 97
    }
  }
}

O JSON pode ser descrito nas seções a seguir, começando na parte superior:

Metadados – Contém dados de conectividade.
Propriedades – Contêm as subseções desired e reported.
Properties.desired (recolhido) – Os valores de propriedade esperados definidos pelo operador no arquivo deployment.json.
Properties.reported – Valores de propriedade mais recentes relatados pelo hub do IoT Edge.

Examine esses dados se tiver problemas com os dispositivos downstream.

Monitorar módulos gêmeos personalizados

As informações sobre a conectividade de seus módulos personalizados são mantidas no módulo gêmeo do agente do IoT Edge. O módulo gêmeo do módulo personalizado é usado principalmente para manter os dados da solução. As propriedades desejadas que você definiu no arquivo deployment.json são refletidas no módulo gêmeo, e seu módulo pode atualizar os valores de propriedade relatada conforme necessário.

É possível usar sua linguagem de programação preferida com os SDKs de Dispositivo do Hub IoT do Azure para atualizar os valores de propriedade relatada no módulo gêmeo com base no código do aplicativo do seu módulo. O procedimento a seguir usa o SDK do Azure para .NET para fazer isso, usando o código do módulo SimulatedTemperatureSensor:

Crie uma instância de ModuleClient com o método CreateFromEnvironmentAsync.
Obtenha uma coleção das propriedades do módulo gêmeo com o método GetTwinAsync.
Crie um ouvinte (passando um retorno de chamada) para detectar alterações nas propriedades desejadas com o método SetDesiredPropertyUpdateCallbackAsync.
No seu método de retorno de chamada, atualize as propriedades relatadas no módulo gêmeo com o método UpdateReportedPropertiesAsync, passando um TwinCollection dos valores de propriedade que você deseja definir.

Acessar o módulo gêmeos

É possível examinar o JSON dos módulos gêmeos no Hub IoT do Azure, no Visual Studio Code e na CLI do Azure.

Monitorar no Hub IoT do Azure

Para ver o JSON do módulo gêmeo:

Entre no Portal do Azure e navegue até o Hub IoT.
Selecione Dispositivos, no menu Gerenciamento de dispositivos.
Selecione a ID do dispositivo do dispositivo IoT Edge com os módulos que você deseja monitorar.
Selecione o nome do módulo na guia Módulos e, em seguida, clique em Identidade do Módulo Gêmeo na barra de menus superior.

Se a mensagem de erro "Não há uma identidade para este módulo" for exibida, significa que a solução de back-end que criou a identidade originalmente não está mais disponível.

Monitorar módulos gêmeos no Visual Studio Code

Para analisar e editar um módulo gêmeo:

Instale as extensões do Azure IoT Edge e do Hub IoT do Azure se elas ainda não estiverem instaladas. A extensão das Ferramentas de Azure IoT Edge para Visual Studio Code está em modo de manutenção.
No Gerenciador, expanda o Hub IoT do Azure e expanda o dispositivo com o módulo que você deseja monitorar.
Clique com o botão direito do mouse e selecione Editar Módulo Gêmeo. Um arquivo temporário do módulo gêmeo será baixado para o computador e exibido no Visual Studio Code.

Se você fizer alterações, selecione Atualizar Módulo Gêmeo acima do código no editor para salvar as alterações no hub IoT.

Captura de tela mostrando como atualizar um módulo gêmeo no Visual Studio Code.

Monitorar módulos gêmeos na CLI do Azure

Para ver se IoT Edge está em execução, use az iot hub invoke-module-method para executar ping no agente do IoT Edge.

A estrutura az iot hub module-twin fornece estes comandos:

az iot hub module-twin show – Mostra uma definição de módulo gêmeo.
az iot hub module-twin update – Atualiza uma definição de módulo gêmeo.
az iot hub module-twin replace – Substitui uma definição de módulo gêmeo com um JSON de destino.

Dica

Para direcionar os módulos de runtime com comandos da CLI, talvez seja necessário escapar o caractere $ na ID do módulo. Por exemplo:

az iot hub module-twin show -m '$edgeAgent' -n <hub name> -d <device name>

Ou:

az iot hub module-twin show -m \$edgeAgent -n <hub name> -d <device name>

Próximas etapas

Aprenda a comunicar-se com o EdgeAgent usando os métodos diretos integrados.

Compartilhar via