Behandeln von Problemen bei Ihrem IoT Edge-Gerät

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.

Wenn in Ihrer Umgebung Probleme bei der Ausführung von Azure IoT Edge auftreten, nutzen Sie diesen Artikel als Leitfaden zur Problembehandlung und Diagnose.

Führen Sie den Befehl ‚check‘ aus

Ihr erster Schritt im Rahmen der Problembehandlung bei IoT Edge sollte die Verwendung des Befehls check sein, mit dem eine Reihe von Konfigurations- und Konnektivitätstests zur Behandlung allgemeiner Probleme durchgeführt wird. Der Befehl check ist ab Release 1.0.7 verfügbar.

Hinweis

Das Problembehandlungstool kann keine Konnektivitätsprüfungen durchführen, wenn sich das IoT Edge-Gerät hinter einem Proxyserver befindet.

Sie können den Befehl check wie folgt ausführen oder das Flag --help einbinden, um alle Optionen anzuzeigen:

sudo iotedge check

Das Problembehandlungstool führt viele Überprüfungen durch, die in folgende drei Kategorien eingeteilt werden:

• Konfigurationsüberprüfungen untersuchen Details, die möglicherweise verhindern, dass IoT Edge-Geräte eine Verbindung mit der Cloud herstellen, einschließlich Problemen bei der Konfigurationsdatei und der Container-Engine.
• Verbindungsüberprüfungen – Überprüft, ob IoT Edge Runtime Zugriff auf Ports am Hostgerät hat und ob alle IoT Edge-Komponenten eine Verbindung mit dem IoT Hub herstellen können. Diese Gruppe von Überprüfungen gibt Fehler zurück, wenn sich das IoT Edge-Gerät hinter einem Proxy befindet.
• Überprüfungen auf die Produktionsbereitschaft – Sucht nach empfohlenen Best Practices für die Produktion, z. B. nach Zertifikaten der Zertifizierungsstelle (Certificate Authority, CA) für den Gerätestatus und nach der Konfiguration der Modulprotokolldatei.

Das Prüftool für IoT Edge verwendet einen Container, um die Diagnosen durchzuführen. Das Containerimage (mcr.microsoft.com/azureiotedge-diagnostics:latest) steht über Microsoft Container Registry zur Verfügung. Wenn Sie eine Überprüfung auf einem Gerät ohne Direktzugriff auf das Internet ausführen möchten, benötigen die Geräte Zugriff auf das Containerimage.

In einem Szenario mit geschachtelten IoT Edge Geräten können Sie Zugriff auf das Diagnoseimage auf nachgeschalteten Geräten erhalten, indem Sie die Imageübertragung über die übergeordneten Geräte weiterleiten.

sudo iotedge check --diagnostics-image-name <parent_device_fqdn_or_ip>:<port_for_api_proxy_module>/azureiotedge-diagnostics:1.2

Informationen zu den einzelnen Diagnoseprüfungen, die von diesem Tool durchgeführt werden – einschließlich der Vorgehensweise beim Auftreten eines Fehlers oder einer Warnung – finden Sie unter IoT Edge-Problembehandlung bei Überprüfungen.

Sammeln von Debuginformationen mit dem Befehl „support-bundle“

Wenn Sie Protokolle von einem IoT Edge-Gerät sammeln müssen, verwenden Sie dazu am einfachsten den Befehl support-bundle. Dieser Befehl sammelt standardmäßig Protokolle von Modulen, IoT Edge Security Manager und Container-Engine, die JSON-Ausgabe iotedge check und weitere nützliche Debuginformationen. Er komprimiert sie zur einfachen Freigabe in einer einzigen Datei. Der Befehl support-bundle steht ab Release 1.0.9 zur Verfügung.

Führen Sie den Befehl support-bundle mit dem Flag --since aus, um anzugeben, wie alt die Protokolle sein sollen, die Sie abrufen möchten. So werden beispielsweise mit 6h die Protokolle der letzten sechs Stunden, mit 6d die der letzten Tage und mit 6m die der letzten sechs Minuten usw. abgerufen. Beziehen Sie das Flag --help mit ein, damit eine vollständige Liste der Optionen angezeigt wird.

sudo iotedge support-bundle --since 6h

Standardmäßig erstellt der Befehl support-bundle in dem Verzeichnis, in dem er aufgerufen wird, die ZIP-Datei support_bundle.zip. Wenn Sie einen anderen Pfad oder Dateinamen für die Ausgabe angeben möchten, verwenden Sie das Flag --output.

Weitere Informationen zum Befehl können Sie in den zugehörigen Hilfeinformationen anzeigen.

iotedge support-bundle --help

Sie können auch die Ausgabe des Befehls „support-bundle“ mithilfe des integrierten direkten Methodenaufrufs UploadSupportBundle in Azure Blob Storage hochladen.

Warnung

Die Ausgabe des Befehls support-bundle kann Host-, Geräte- und Modulnamen, von ihren Modulen protokollierte Informationen usw. enthalten. Beachten Sie dies bitte, wenn Sie die Ausgabe in einem öffentlichen Forum freigeben.

Überprüfen der von der Runtime gesammelten Metriken

Die IoT Edge-Runtimemodule erzeugen Metriken, mit deren Hilfe Sie die Integrität Ihrer IoT Edge-Geräte überwachen und verstehen können. Fügen Sie Ihren Bereitstellungen das Modul Metrikensammler hinzu, um diese Metriken zu erfassen und zur einfacheren Überwachung an die Cloud zu senden.

Weitere Informationen finden Sie unter Sammeln und Transportieren von Metriken.

Überprüfen Sie Ihre IoT Edge-Version

Wenn Sie eine ältere Version von IoT Edge ausführen, löst ein Upgrade möglicherweise Ihr Problem. Das Tool iotedge check überprüft, ob der IoT Edge-Sicherheitsdaemon die neueste Version ist, überprüft aber nicht die Versionen der IoT Edge Hub- und Agentmodule. Wenn Sie die Version der Runtimemodule auf Ihrem Gerät überprüfen möchten, verwenden Sie die Befehle iotedge logs edgeAgent und iotedge logs edgeHub. Die Versionsnummer wird in den Protokollen beim Starten des Moduls deklariert.

Anleitungen zum Aktualisieren Ihres Geräts finden Sie unter Aktualisieren des IoT Edge-Sicherheitsdaemons und der Runtime.

Überprüfen der Installation von IoT Edge auf Ihren Geräten

Sie können die Installation von IoT Edge auf Ihren Geräten überprüfen, indem Sie den edgeAgent-Modulzwilling überwachen.

Führen Sie den folgenden Befehl in Azure Cloud Shell aus, um den neuesten edgeAgent-Modulzwilling abzurufen:

az iot hub module-twin show --device-id <edge_device_id> --module-id '$edgeAgent' --hub-name <iot_hub_name>

Mit diesem Befehl werden alle gemeldeten edgeAgent-Eigenschaften ausgegeben. Hier einige nützliche Eigenschaften zum Überwachen des Gerätestatus:

• runtime status
• runtime start time
• runtime last exit time
• runtime restart count

Überprüfen Sie den Status des IoT Edge-Sicherheits-Managers und seiner Protokolle

IoT Edge Security Manager ist für Vorgänge wie das Initialisieren des IoT Edge-Systems beim Starten und Bereitstellen von Geräten verantwortlich. Wenn IoT Edge nicht gestartet wird, können die Security Manager-Protokolle nützliche Informationen enthalten.

• Zeigen Sie den Status der IoT Edge-Systemdienste an:

  sudo iotedge system status
  

• Zeigen Sie die Protokolle der IoT Edge-Systemdienste an:

  sudo iotedge system logs -- -f
  

• Aktivieren Sie Protokolle auf Debugebene, um ausführlichere Protokolle der IoT Edge-Systemdienste anzuzeigen:

  1. Aktivieren Sie Protokolle auf Debugebene.

     sudo iotedge system set-log-level debug
     sudo iotedge system restart
     

  2. Wechseln Sie nach dem Debuggen zu den Standardprotokollen auf Infoebene zurück.

     sudo iotedge system set-log-level info
     sudo iotedge system restart
     

Überprüfen von Containerprotokollen auf Probleme

Sobald der IoT Edge-Sicherheits-Daemon ausgeführt wird, sehen Sie sich die Protokolle der Container an, um Probleme zu erkennen. Beginnen Sie mit den bereitgestellten Containern, und sehen Sie sich dann die Container der IoT Edge-Runtime an: „edgeAgent“ und „edgeHub“. Die IoT Edge-Agent-Protokolle bieten in der Regel Informationen zum Lebenszyklus der einzelnen Container. Die IoT Edge-Hub-Protokolle bieten Informationen zu Messaging und Routing.

Sie können die Containerprotokolle von mehreren Stellen abrufen:

• Führen Sie auf dem IoT Edge-Gerät den folgenden Befehl zum Anzeigen von Protokollen aus:

  iotedge logs <container name>
  

• Verwenden Sie im Azure-Portal das integrierte Problembehandlungstool. Überwachen und Beheben von Problemen bei IoT Edge-Geräten über das Azure-Portal

• Sie können die Protokolle eines Moduls in Azure Blob Storage mithilfe der direkten Methode „UploadModuleLogs“ in Azure Blob Storage hochladen.

Bereinigen von Containerprotokollen

Standardmäßig legt die Moby-Containerengine keine Grenzwerte für die Größe des Containerprotokolls fest. Im Laufe der Zeit können umfangreiche Protokolle dazu führen, dass das Gerät mit Protokollen überfüllt wird und nicht genügend Speicherplatz auf dem Datenträger zur Verfügung steht. Wenn sich große Containerprotokolle auf die Leistung Ihres IoT Edge-Geräts auswirken, können Sie mit dem folgenden Befehl das Entfernen des Containers zusammen mit den zugehörigen Protokollen erzwingen.

Wenn Sie noch die Problembehandlung durchführen, warten Sie, bis Sie die Containerprotokolle überprüft haben, bevor Sie diesen Schritt ausführen.

Warnung

Wenn Sie erzwingen, dass der edgeHub-Container entfernt wird, während er ein nicht zugestelltes Nachrichtenbacklog enthält und kein Hostspeicher eingerichtet wurde, gehen die nicht zugestellten Nachrichten verloren.

docker rm --force <container name>

Richten Sie bei laufenden Protokollwartungs- und Produktionsszenarien den Standardprotokollierungstreiber ein, wie hier beschrieben.

Zeigen Sie die Nachrichten an, die den IoT Edge-Hub durchlaufen

Sie können die Nachrichten anzeigen, die den IoT Edge-Hub durchlaufen, und aus den ausführlichen Protokollen der Runtimecontainer Erkenntnisse gewinnen. Wenn Sie für diese Container ausführliche Protokolle aktivieren möchten, legen Sie im Bereitstellungsmanifest die Umgebungsvariable RuntimeLogLevel fest.

Zum Anzeigen von Nachrichten, die den IoT Edge-Hub durchlaufen, legen Sie die RuntimeLogLevel Umgebungsvariable debug für das edgeHub-Modul fest.

Die Module edgeHub und edgeAgent enthalten diese Laufzeitprotokoll-Umgebungsvariable, bei der der Standardwert auf info festgelegt wurde. Diese Umgebungsvariable kann die folgenden Werte haben:

• fatal
• error
• Warnung laden
• info
• Debuggen
• Ausführlich

Sie können auch die Nachrichten überprüfen, die zwischen IoT Hub und den IoT-Geräten gesendet werden. Zeigen Sie diese Nachrichten mithilfe der Azure IoT Hub-Erweiterung für Visual Studio Code an. Weitere Informationen finden Sie unter Praktisches Tool bei der Entwicklung mit Azure IoT.

Führen Sie einen Neustart der Container aus

Nachdem Sie die Protokolle und Nachrichten auf Informationen untersucht haben, können Sie einen Neustart der Container versuchen.

Verwenden Sie auf dem IoT Edge-Gerät die folgenden Befehle zum Neustart von Modulen:

iotedge restart <container name>

Starten Sie die IoT Edge-Runtime-Container neu:

iotedge restart edgeAgent && iotedge restart edgeHub

Sie können Module auch remote über das Azure-Portal neu starten. Weitere Informationen finden Sie unter Überwachen und Beheben von Problemen bei IoT Edge-Geräten über das Azure-Portal.

Überprüfen Sie Ihre Konfigurationsregeln für Firewall und Ports

Azure IoT Edge ermöglicht die Kommunikation von einem lokalen Server mit der Azure-Cloud über unterstützte IoT Hub-Protokolle. Weitere Informationen finden Sie unter Auswählen eines Gerätekommunikationsprotokolls. Aus Sicherheitsgründen sind Kommunikationskanäle zwischen Azure IoT Edge und Azure IoT Hub immer als „Ausgehend“ konfiguriert. Diese Konfiguration basiert auf dem von Diensten unterstützten Kommunikationsmuster, das die Angriffsfläche für böswillige Entitäten minimiert, die das System durchsuchen. Die eingehende Kommunikation ist nur für bestimmte Szenarien erforderlich, in denen Azure IoT Hub Nachrichten mithilfe von Push an das Azure IoT Edge-Gerät übertragen muss. Cloud-zu-Gerät-Nachrichten werden mithilfe von sicheren TLS-Kanälen geschützt und können mithilfe von X. 509-Zertifikaten und TPM-Gerätemodulen weiter gesichert werden. Der Azure IoT Edge-Sicherheits-Manager steuert, wie diese Kommunikation zustande kommt (siehe Azure IoT Edge-Sicherheits-Manager).

IoT Edge bietet zwar erweiterte Konfigurationsmöglichkeiten zum Schutz der Azure IoT Edge-Runtime und der bereitgestellten Module, hängt aber dennoch von der zugrunde liegenden Computer- und Netzwerkkonfiguration ab. Daher müssen für eine sichere Kommunikation zwischen Edge und Cloud unbedingt geeignete Netzwerk- und Firewallregeln vorhanden sein. Beim Konfigurieren von Firewallregeln für die zugrunde liegenden Server, auf denen die Azure IoT Edge-Runtime gehostet wird, können Sie sich an folgender Tabelle orientieren:

Protocol	Port	Eingehend	Ausgehend	Leitfaden
MQTT	8883	BLOCKIERT (Standard)	BLOCKIERT (Standard)	Konfigurieren Sie ausgehende Verbindungen als Offen, wenn Sie MQTT als Kommunikationsprotokoll verwenden. „1883 für MQTT“ wird von IoT Edge nicht unterstützt. Eingehende Verbindungen sollten blockiert werden.
AMQP	5671	BLOCKIERT (Standard)	OFFEN (Standard)	Standardkommunikationsprotokoll für IoT Edge. Muss als Offen konfiguriert werden, wenn Azure IoT Edge für andere unterstützte Protokolle nicht konfiguriert wird oder AMQP das gewünschte Kommunikationsprotokoll ist. „5672 für AMQP“ wird von IoT Edge nicht unterstützt. Blockieren Sie diesen Port, wenn Azure IoT Edge ein anderes von IoT Hub unterstütztes Protokoll verwendet. Eingehende Verbindungen sollten blockiert werden.
HTTPS	443	BLOCKIERT (Standard)	OFFEN (Standard)	Konfigurieren Sie ausgehende Verbindungen als „Offen“ (Port 443) für die IoT Edge-Bereitstellung. Diese Konfiguration ist bei Verwendung manueller Skripts oder des Azure IoT Device Provisioning-Diensts (Device Provisioning Service, DPS) erforderlich. Die eingehende Verbindung sollte nur für bestimmte Szenarien geöffnet werden: Wenn Sie ein transparentes Gateway mit nachgeschalteten Geräten haben, die möglicherweise Methodenanforderungen senden. In diesem Fall muss der Port 443 nicht für externe Netzwerke geöffnet werden, um eine Verbindung mit IoT Hub herzustellen oder IoT Hub-Dienste über Azure IoT Edge bereitzustellen. Die Eingangsregel könnte somit darauf eingeschränkt werden, nur eingehende Verbindungen aus dem internen Netzwerk zu öffnen. In C2D-Szenarien. „80 für HTTP“ wird von IoT Edge nicht unterstützt. Falls im Unternehmen Nicht-HTTP-Protokolle (z. B. AMQP oder MQTT) nicht konfiguriert werden können, können die Nachrichten über WebSockets gesendet werden. In diesem Fall wird der Port 443 für die WebSocket-Kommunikation verwendet.

Letzte Möglichkeit: Beenden und erneutes Erstellen aller Container

Manchmal erfordert ein System möglicherweise erhebliche besondere Änderungen, um mit bestehenden Netzwerk- oder Betriebssystemeinschränkungen arbeiten zu können. Beispielsweise könnte ein System eine andere Datenträgereinbindung und Proxyeinstellungen erfordern. Wenn Sie alle vorherigen Schritte ausprobiert haben und Ihnen weiterhin Containerfehler angezeigt werden, ist es möglich, dass die Docker-Systemcaches oder die beibehaltenen Netzwerkeinstellungen nicht auf dem neuesten Stand der Neukonfiguration sind. In diesem Fall besteht Ihre letzte Option darin, mithilfe von docker prune einen sauberen Start von Grund auf durchzuführen.

Der folgende Befehl stoppt das IoT Edge-System (und damit alle Container) und verwendet für docker prune die Option „all“ und „volume“, um alle Container und Volumes zu entfernen. Überprüfen Sie die vom Befehl ausgegebene Warnung und bestätigen Sie mit y, wenn Sie bereit sind.

sudo iotedge system stop
docker system prune --all --volumes

WARNING! This will remove:
  - all stopped containers
  - all networks not used by at least one container
  - all volumes not used by at least one container
  - all images without at least one container associated to them
  - all build cache

Are you sure you want to continue? [y/N]

Starten Sie das System erneut. Wenden Sie sicherheitshalber jede beliebige möglicherweise verbleibende Konfiguration an, und starten Sie das System mit einem einzigen Befehl.

sudo iotedge config apply

Warten Sie ein paar Minuten, und überprüfen Sie es erneut.

sudo iotedge list

Nächste Schritte

Sind Sie der Meinung, dass Sie in der IoT Edge-Plattform einen Fehler gefunden haben? Melden Sie ein Problem, damit wir die Plattform weiter verbessern können.

Wenn Sie weitere Fragen haben, erstellen Sie eine Supportanfrage, um Hilfe zu erhalten.