Überwachen von Modulzwillingen

Artikel
06/03/2024

Gilt für: IoT Edge 1.5 IoT Edge 1.4

Wichtig

IoT Edge 1.5 LTS und IoT Edge 1.4 LTS sind unterstützte Releases. Das Ende der Lebensdauer von IoT Edge 1.4 LTS wird am 12. November 2024 erreicht. Wenn Sie ein früheres Release verwenden, finden Sie weitere Informationen unter Aktualisieren von IoT Edge.

Modulzwillinge ermöglichen in Azure IoT Hub die Überwachung der Konnektivität und Integrität ihrer IoT Edge-Bereitstellungen. Modulzwillinge speichern nützliche Informationen über die Leistung Ihrer laufenden Module in Ihrem IoT-Hub. Das IoT Edge-Agent- und IoT Edge-Hub-Runtimemodul verwalten jeweils ihre Modulzwillinge ($edgeAgent und $edgeHub), genauer:

$edgeAgent enthält Integritäts- und Konnektivitätsdaten sowohl zum IoT Edge-Agent- als auch IoT Edge-Hub-Runtimemodul sowie zu Ihren benutzerdefinierten Modulen. Der IoT Edge-Agent ist verantwortlich für die Bereitstellung der Module, deren Überwachung und das Berichten des Verbindungsstatus an Ihren Azure IoT-Hub.
$edgeHub enthält Daten über die Kommunikation zwischen dem IoT Edge-Hub, der auf einem Gerät ausgeführt wird, und Ihrem Azure IoT-Hub. Dies schließt die Verarbeitung von nachgeschalteten Geräten eingehender Nachrichten ein. Der IoT Edge-Hub ist für die Verarbeitung der Kommunikation zwischen dem Azure IoT-Hub und den IoT Edge-Geräten und -Modulen verantwortlich.

Die Daten werden zusammen mit den gewünschten und gemeldeten Eigenschaftssätzen in den JSON-Strukturen der Modulzwillinge in Metadaten und Tags organisiert. Die gewünschten Eigenschaften, die Sie in der Datei „deployment.json“ angegeben haben, werden in die Modulzwillinge kopiert. Der IoT Edge-Agent und der IoT Edge-Hub aktualisieren die gemeldeten Eigenschaften jeweils für ihre Module.

Entsprechend werden die für Ihre benutzerdefinierten Module in der Datei „deployment.json“ angegebenen gewünschten Eigenschaften in den jeweiligen Modulzwilling kopiert, aber Ihre Lösung ist dafür verantwortlich, die gemeldeten Eigenschaftswerte bereitzustellen.

In diesem Artikel wird beschrieben, wie Sie die Modulzwillinge in Azure-Portal, Azure CLI und Visual Studio Code überprüfen. Informationen dazu, wie Sie überwachen, wie Ihre Geräte die Bereitstellungen erhalten, finden Sie unter Überwachen von IoT Edge-Bereitstellungen. Eine Übersicht über das Konzept von Modulzwillingen finden Sie unter Verstehen und Verwenden von Modulzwillingen in IoT Hub.

Tipp

Die gemeldeten Eigenschaften eines Runtimemoduls können veraltet sein, wenn ein IoT Edge-Gerät von seinem IoT-Hub getrennt wird. Sie können das $edgeAgent-Modul pingen, um zu ermitteln, ob die Verbindung unterbrochen wurde.

Überwachen von Runtimemodulzwillingen

Überprüfen Sie zum Beheben von Problemen bei der Bereitstellungskonnektivität den IoT Edge-Agent- und IoT Edge-Hub-Runtimemodulzwilling, und führen Sie dann einen Drilldown bei anderen Modulen aus.

Überwachen des IoT Edge-Agent-Modulzwillings

Der folgende JSON-Code zeigt den $edgeAgent-Modulzwilling in Visual Studio Code, wobei die meisten JSON-Abschnitte reduziert sind.

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

Der JSON-Code kann in den folgenden Abschnitten oben beginnend beschrieben werden:

Metadata: enthält Konnektivitätsdaten. Interessanterweise befindet sich der IoT Edge-Agent immer im Verbindungsstatus „Getrennt“: "connectionState": "Disconnected". Der Grund dafür ist, dass sich der Verbindungsstatus auf D2C-Nachrichten (Device-to-Cloud) bezieht, und der IoT Edge-Agent sendet keine D2C-Nachrichten.
Properties: enthält die Unterabschnitte desired und reported.
Properties.desired (reduziert angezeigt): erwartete Eigenschaftswerte, die vom Operator in der Datei „deployment.json“ festgelegt wurden.
Properties.reported: zuletzt vom IoT Edge-Agent gemeldete Eigenschaftswerte.

Die Struktur der Abschnitte properties.desired und properties.reported ist ähnlich und sie enthalten zusätzliche Metadaten für Schema-, Versions- und Runtimeinformationen. Außerdem ist der modules-Abschnitt für alle benutzerdefinierten Module (z. B. SimulatedTemperatureSensor) eingeschlossen und der systemModules-Abschnitt für $edgeAgent und die $edgeHub-Runtimemodule.

Wenn Sie die gemeldeten Eigenschaftswerte mit den gewünschten Werten vergleichen, können Sie Abweichungen feststellen und Trennungen ermitteln, die Ihnen bei der Problembehandlung helfen können. Überprüfen Sie in diesen Vergleichen den gemeldeten Wert $lastUpdated im metadata-Abschnitt für die Eigenschaft, die Sie untersuchen.

Die folgenden Eigenschaften sind für die Untersuchung zur Problembehandlung wichtig:

Exitcode: Jeder andere Wert als 0 (null) gibt an, dass das Modul mit einem Fehler angehalten wurde. Allerdings werden die Fehlercodes 137 oder 143 verwendet, wenn für ein Modul absichtlich der Angehalten-Status festgelegt wurde.
lastStartTimeUtc: Zeigt DateTime für den letzten Start des Containers an. Dieser Wert ist „0001-01-01T00:00:00Z“, wenn der Container nicht gestartet wurde.
lastExitTimeUtc: Zeigt DateTime für das letzte Ausführungsende des Containers an. Dieser Wert ist „0001-01-01T00:00:00Z“, wenn der Container ausgeführt wird und nie angehalten wurde.

runtimeStatus: Kann einen der folgenden Werte aufweisen:

Wert	Beschreibung
Unbekannt	Standardstatus, bis die Bereitstellung erstellt wird.
backoff	Der Start des Moduls ist geplant, es läuft jedoch zurzeit nicht. Dieser Wert ist nützlich für ein Modul, das beim Neustart Statusänderungen durchläuft. Wenn ein fehlerhaftes Modul während des Abkühlzeitraums einen Neustart erwartet, befindet es sich im Status „backoff“.
„Wird ausgeführt“	Zeigt an, dass das Modul derzeit läuft.
Fehlerhaft	Gibt an, dass bei einem Integritätstest ein Fehler aufgetreten ist oder die Zeit überschritten wurde.
stopped	Gibt an, dass das Modul erfolgreich angehalten wurde (mit einem Exitcode von 0 (null)).
„Fehlgeschlagen“	Gibt an, dass das Modul mit einem Fehlerexitcode (ungleich 0 (null)) angehalten wurde. Das Modul kann abhängig von der geltenden Neustartrichtlinie von diesem Status zurück zu „backoff“ wechseln. Dieser Status kann darauf hinweisen, dass im Modul ein nicht behebbarer Fehler aufgetreten ist. Ein Fehler tritt auf, wenn der Microsoft Monitoring Agent (MMA) das Modul nicht mehr aktivieren kann, sodass eine neue Bereitstellung erforderlich ist.

Weitere Informationen finden Sie unter Gemeldete EdgeAgent-Eigenschaften.

Überwachen des IoT Edge-Hub-Modulzwillings

Der folgende JSON-Code zeigt den $edgeHub-Modulzwilling in Visual Studio Code, wobei die meisten JSON-Abschnitte reduziert sind.

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

Der JSON-Code kann in den folgenden Abschnitten oben beginnend beschrieben werden:

Metadata: enthält Konnektivitätsdaten.
Properties: enthält die Unterabschnitte desired und reported.
Properties.desired (reduziert angezeigt): erwartete Eigenschaftswerte, die vom Operator in der Datei „deployment.json“ festgelegt wurden.
Properties.reported: zuletzt vom IoT Edge-Hub gemeldete Eigenschaftswerte.

Wenn Probleme mit den nachgeschalteten Geräten auftreten, wäre die Untersuchung dieser Daten ein guter Ausgangspunkt.

Überwachen benutzerdefinierter Modulzwillinge

Die Informationen zur Konnektivität Ihrer benutzerdefinierten Module werden im IoT Edge-Agent-Modulzwilling verwaltet. Der Modulzwilling für Ihr benutzerdefiniertes Modul wird hauptsächlich zum Verwalten von Daten für Ihre Lösung verwendet. Die gewünschten Eigenschaften, die Sie in der Datei „deployment.json“ definiert haben, spiegeln sich im Modulzwilling wider, und das Modul kann gemeldete Eigenschaftswerte nach Bedarf aktualisieren.

Sie können Ihre bevorzugte Programmiersprache mit den Azure IoT Hub-Geräte-SDKs verwenden, um gemeldete Eigenschaftswerte im Modulzwilling basierend auf dem Anwendungscode Ihres Moduls zu aktualisieren. Im folgenden Verfahren wird das Azure SDK für .NET hierfür verwendet, wobei Code aus dem SimulatedTemperatureSensor-Modul verwendet wird:

Erstellen Sie eine Instanz des ModuleClient mit der CreateFromEnvironmentAsync-Methode.
Rufen Sie eine Sammlung der Eigenschaften des Modulzwillings mit der GetTwinAsync-Methode ab.
Erstellen Sie einen Listener (Übergabe eines Rückrufs), um Änderungen an den gewünschten Eigenschaften mit der SetDesiredPropertyUpdateCallbackAsync-Methode abzufangen.
Aktualisieren Sie in Ihrer Rückrufmethode die gemeldeten Eigenschaften im Modulzwilling mit der UpdateReportedPropertiesAsync-Methode, und übergeben Sie dabei eine TwinCollection der Eigenschaftswerte, die Sie festlegen möchten.

Zugreifen auf die Modulzwillinge

Sie können den JSON-Code für Modulzwillinge in Azure IoT Hub, in Visual Studio Code und mit Azure CLI überprüfen.

Überwachen in Azure IoT Hub

So zeigen Sie den JSON-Code für den Modulzwilling an:

Melden Sie sich beim Azure-Portal an, und navigieren Sie zu Ihrem IoT Hub.
Wählen Sie Geräte im Menü Geräteverwaltung aus.
Wählen Sie die Geräte-ID des Geräts mit den Modulen aus, die Sie überwachen möchten.
Wählen Sie auf der Registerkarte Module den Modulnamen aus, und wählen Sie dann in der oberen Menüleiste Zwilling der Modulkennung aus.

Wenn die Meldung „Eine Modulkennung ist für dieses Modul nicht vorhanden“ angezeigt wird, weist dieser Fehler darauf hin, dass die Back-End-Lösung, die ursprünglich die Kennung erstellt hat, nicht mehr verfügbar ist.