Monitorare i moduli gemelli

Si applica a: IoT Edge 1.5 IoT Edge 1.4

Importante

IoT Edge 1.5 LTS e IoT Edge 1.4 LTS sono versioni supportate. IoT Edge 1.4 LTS raggiungerà la data di fine del servizio il 12 novembre 2024. Se si usa una versione precedente, vedere Aggiornare IoT Edge.

I moduli gemelli nell'hub IoT di Azure consentono di monitorare la connettività e l'integrità delle distribuzioni di IoT Edge. I moduli gemelli archiviano informazioni utili nell'hub IoT sulle prestazioni dei moduli in esecuzione. L'agente IoT Edge e i moduli di runtime dell'hub IoT Edge mantengono rispettivamente i moduli gemelli, $edgeAgent e $edgeHub:

• $edgeAgent contiene dati sull'integrità e sulla connettività relativi sia all'agente IoT Edge che ai moduli di runtime dell'hub IoT Edge e ai moduli personalizzati. L'agente IoT Edge è responsabile della distribuzione dei moduli, del monitoraggio e della segnalazione dello stato della connessione all'hub IoT di Azure.
• $edgeHub contiene dati sulle comunicazioni tra l'hub IoT Edge in esecuzione in un dispositivo e l'hub IoT di Azure. Ciò include l'elaborazione dei messaggi in ingresso dai dispositivi downstream. L'hub IoT Edge è responsabile dell'elaborazione delle comunicazioni tra l'hub IoT di Azure e i dispositivi e i moduli IoT Edge.

I dati sono organizzati in metadati, tag, e set di proprietà desiderati e segnalati nelle strutture JSON dei moduli gemelli. Le proprietà desiderate specificate nel file deployment.json vengono copiate nei moduli gemelli. L'agente IoT Edge e l'hub IoT Edge aggiornano le proprietà segnalate per i moduli.

Allo stesso modo, le proprietà desiderate specificate per i moduli personalizzati nel file deployment.json vengono copiate nel modulo gemello, ma la soluzione è responsabile di fornire i valori delle proprietà segnalate.

Questo articolo descrive come esaminare i moduli gemelli nel portale di Azure, nell'interfaccia della riga di comando di Azure e in Visual Studio Code. Per informazioni sul monitoraggio del modo in cui i dispositivi ricevono le distribuzioni, vedere Monitorare le distribuzioni di IoT Edge. Per una panoramica sul concetto di moduli gemelli, vedere Informazioni e uso dei moduli gemelli nell'hub IoT.

Suggerimento

Le proprietà segnalate di un modulo di runtime potrebbero non essere aggiornati se un dispositivo IoT Edge viene disconnesso dall'hub IoT. È possibile effettuare il ping del modulo $edgeAgent per determinare se la connessione è stata persa.

Monitorare i moduli gemelli del runtime

Per risolvere i problemi di connettività della distribuzione, esaminare i moduli gemelli di runtime dell'agente IoT Edge e dell'hub IoT Edge e quindi eseguire il drill-down in altri moduli.

Monitorare il modulo gemello dell'agente IoT Edge

Il codice JSON seguente illustra il modulo gemello $edgeAgent in Visual Studio Code con la maggior parte delle sezioni JSON compresse.

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

Il codice JSON può essere descritto nelle sezioni seguenti, a partire dall'inizio:

• Metadati: contiene i dati di connettività. È interessante notare che lo stato della connessione per l'agente IoT Edge è sempre in uno stato disconnesso: "connectionState": "Disconnected". Il motivo per cui lo stato di connessione riguarda i messaggi da dispositivo a cloud (D2C) e l'agente IoT Edge non invia messaggi D2C.
• Proprietà: contiene le sottosezioni desired e reported.
• Properties.desired: (mostrati compressi) valori delle proprietà previsti impostati dall'operatore nel file deployment.json.
• Properties.reported: valori delle proprietà più recenti segnalati dall'agente IoT Edge.

Le sezioni properties.desired e properties.reported hanno una struttura simile e contengono metadati aggiuntivi per le informazioni sullo schema, sulla versione e sul runtime. È inclusa anche la sezione modules per tutti i moduli personalizzati (ad esempio SimulatedTemperatureSensor) e la sezione systemModules per$edgeAgent e i moduli di runtime $edgeHub.

Confrontando i valori delle proprietà segnalate con i valori desiderati, è possibile determinare le discrepanze e identificare le disconnessioni che consentono di risolvere i problemi. Per eseguire questi confronti, controllare il valore segnalato $lastUpdated nella sezione metadata per la proprietà che si sta esaminando.

Le proprietà seguenti sono importanti per esaminare la risoluzione dei problemi:

• exitcode: qualsiasi valore diverso da zero indica che il modulo è stato arrestato con un errore. Tuttavia, i codici di errore 137 o 143 vengono usati se un modulo è stato intenzionalmente impostato su uno stato arrestato.

• lastStartTimeUtc: mostra il DateTime dell'ultimo avvio del contenitore. Questo valore è 0001-01-01T00:00:00Z se il contenitore non è stato avviato.

• lastExitTimeUtc: mostra il DateTime in cui il contenitore è stato terminato per l'ultima volta. Questo valore è 0001-01-01T00:00:00Z se il contenitore è in esecuzione e non è mai stato arrestato.

• runtimeStatus: può essere uno dei seguenti valori:

  Valore	Descrizione
  Sconosciuto	Stato predefinito fino alla creazione della distribuzione.
  backoff	Il modulo è pianificato per l'avvio, ma non è attualmente in esecuzione. Questo valore è utile per un modulo che subisce cambiamenti di stato nel riavvio. Quando un modulo non riuscito è in attesa di riavvio durante il periodo di disattivazione, il modulo si trova in uno stato di backoff.
  in esecuzione	Indica che il modulo è attualmente in esecuzione.
  non integro	Indica un controllo probe di integrità non riuscito o timeout.
  arrestato	Indica che il modulo è stato chiuso correttamente (con un codice di uscita zero).
  failed	Indica che il modulo è stato chiuso con un codice di uscita di errore (diverso da zero). Il modulo può tornare al backoff da questo stato a seconda dei criteri di riavvio in vigore. Questo stato può indicare che il modulo ha riscontrato un errore irreversibile. L'errore si verifica quando Microsoft Monitoring Agent (MMA) non è più in grado di rianimare il modulo, richiedendo una nuova distribuzione.

Per informazioni dettagliate, vedere Proprietà segnalate di EdgeAgent.

Monitorare il modulo gemello dell'hub IoT Edge

Il codice JSON seguente illustra il modulo gemello $edgeHub in Visual Studio Code con la maggior parte delle sezioni JSON compresse.

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

Il codice JSON può essere descritto nelle sezioni seguenti, a partire dall'inizio:

• Metadati: contiene i dati di connettività.

• Proprietà: contiene le sottosezioni desired e reported.

• Properties.desired: (mostrati compressi) valori delle proprietà previsti impostati dall'operatore nel file deployment.json.

• Properties.reported: valori delle proprietà più recenti segnalati dall'hub di IoT Edge.

Se si verificano problemi con i dispositivi downstream, l'analisi di questi dati è un buon punto di partenza.

Monitorare i moduli gemelli personalizzati

Le informazioni sulla connettività dei moduli personalizzati vengono mantenute nel modulo gemello dell'agente IoT Edge. Il modulo gemello per il modulo personalizzato viene usato principalmente per la gestione dei dati per la soluzione. Le proprietà desiderate definite nel file deployment.json vengono riflesse nel modulo gemello e il modulo può aggiornare i valori delle proprietà segnalate in base alle esigenze.

È possibile usare il linguaggio di programmazione preferito con gli SDK per dispositivi dell'hub IoT di Azure per aggiornare i valori delle proprietà segnalate nel modulo gemello, in base al codice dell'applicazione del modulo. La procedura seguente usa Azure SDK per .NET per eseguire questa operazione usando il codice del modulo SimulatedTemperatureSensor:

1. Creare un'istanza del ModuleClient con il metodo CreateFromEnvironmentAysnc.

2. Ottenere una raccolta delle proprietà del modulo gemello con il metodo GetTwinAsync.

3. Creare un listener (passando un callback) per intercettare le modifiche alle proprietà desiderate con il metodo SetDesiredPropertyUpdateCallbackAsync.

4. Nel metodo di callback aggiornare le proprietà segnalate nel modulo gemello con il metodo UpdateReportedPropertiesAsync, passando un TwinCollection dei valori delle proprietà da impostare.

Accedere ai moduli gemelli

È possibile esaminare il JSON per i moduli gemelli nell'hub IoT di Azure, in Visual Studio Code e con l'interfaccia della riga di comando di Azure.

Monitorare nell'hub IoT di Azure

Per visualizzare il codice JSON per il modulo gemello:

1. Accedere al portale di Azure e passare all'hub IoT.

2. Selezionare Dispositivi nel menu Gestione dispositivi.

3. Selezionare l’ID dispositivo del dispositivo IoT Edge con i moduli da monitorare.

4. Selezionare il nome del modulo nella scheda Moduli e quindi selezionare Identità del modulo gemello nella barra dei menu superiore.

   

Se viene visualizzato il messaggio "Per questo modulo non esiste un'identità di modulo", questo errore indica che la soluzione back-end non è più disponibile che ha originariamente creato l'identità.

Monitorare i moduli gemelli in Visual Studio Code

Per esaminare e modificare un modulo gemello:

1. Se non sono già installati, installare Azure IoT Edge e le estensioni dell'hub IoT di Azure. L'estensione Azure IoT Edge Tools per Visual Studio Code è in modalità manutenzione.

2. In Explorer espandere l’hub IoT di Azure e quindi espandere il dispositivo con il modulo da monitorare.

3. Fare clic con il pulsante destro del mouse sul modulo e selezionare Modifica modulo gemello. Un file temporaneo del modulo gemello viene scaricato nel computer e visualizzato in Visual Studio Code.

   

Se si apportano modifiche, selezionare Aggiorna modulo gemello sopra il codice nell'editor per salvare le modifiche nell'hub IoT.

Monitorare i moduli gemelli nell’interfaccia della riga di comando di Azure

Per verificare se IoT Edge è in esecuzione, usare il az iot hub invoke-module-method per eseguire il ping dell'agente IoT Edge.

La struttura az iot hub module-twin fornisce questi comandi:

• az iot hub module-twin show - Mostrare una definizione del modulo gemello.
• az iot hub module-twin update - Aggiornare una definizione del modulo gemello.
• az iot hub module-twin replace - Sostituire una definizione del modulo gemello con un codice JSON di destinazione.

Suggerimento

Per impostare come destinazione i moduli di runtime con i comandi dell'interfaccia della riga di comando, potrebbe essere necessario eseguire l'escape del carattere $ nell'ID modulo. Ad esempio:

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

Oppure:

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

Passaggi successivi

Leggere le informazioni su come comunicare con EdgeAgent usando i metodi diretti predefiniti.