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:
Aktivieren Sie Protokolle auf Debugebene.
sudo iotedge system set-log-level debug sudo iotedge system restart
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) |
|
AMQP | 5671 | BLOCKIERT (Standard) | OFFEN (Standard) |
|
HTTPS | 443 | BLOCKIERT (Standard) | OFFEN (Standard) |
|
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.