Remotesammlung von Diagnoseprotokollen von Geräten mithilfe von Device Update for IoT Hub

Erfahren Sie, wie Sie einen Protokollvorgang in Device Update for IoT Hub initiieren und gesammelte Protokolle in Azure Blob Storage anzeigen.

Voraussetzungen

• Zugriff auf einen IoT Hub mit aktiviertem Device Update for IoT Hub.
• Ein IoT-Gerät (oder ein Simulator), das in IoT Hub für Device Update bereitgestellt wurde und die Diagnoseschnittstelle implementiert
• Ein Azure Blob Storage-Konto unter demselben Abonnement wie Ihr Device Update for IoT Hub-Konto

Hinweis

Das Feature für die Remoteprotokollsammlung ist derzeit nur mit Geräten kompatibel, die die Diagnoseschnittstelle implementieren und Dateien in Azure Blob Storage hochladen können. Die Implementierung des Verweis-Agents erwartet außerdem, dass das Gerät Protokolldateien in einen vom Benutzer angegebenen Dateipfad auf dem Gerät schreibt.

Azure portal

Unterstützte Browser:

• Microsoft Edge
• Google Chrome

Azure-Befehlszeilenschnittstelle

Eine Azure CLI-Umgebung:

• Verwenden Sie die Bash-Umgebung in Azure Cloud Shell.

  

• Wenn Sie CLI-Referenzbefehle lieber lokal ausführen, installieren Sie die Azure CLI

  • Melden Sie sich mit dem Befehl az login bei der Azure CLI an.
  • Führen Sie az version aus, um die installierte Version und die abhängigen Bibliotheken zu ermitteln. Führen Sie az upgrade aus, um das Upgrade auf die aktuelle Version durchzuführen.
  • Installieren Sie die Azure CLI-Erweiterungen bei der ersten Verwendung, wenn Sie dazu aufgefordert werden. Die Befehle in diesem Artikel verwenden die azure-iot-Erweiterung . Führen Sie az extension update --name azure-iot aus, um sicherzustellen, dass Sie die neueste Version der Erweiterung verwenden.

Tipp

Die Azure CLI-Befehle in diesem Artikel verwenden den umgekehrten Schrägstrich (\) für die Zeilenfortsetzung, damit die Befehlsargumente einfacher lesbar sind. Diese Syntax funktioniert in Bash-Umgebungen. Wenn Sie diese Befehle in PowerShell ausführen, ersetzen Sie jeden umgekehrten Schrägstrich durch ein Graviszeichen („`“), oder entfernen Sie die umgekehrten Schrägstriche vollständig.

Verknüpfen Ihres Azure Blob Storage-Kontos mit Ihrer Device Update-Instanz

Um das Feature für die Remoteprotokollsammlung verwenden zu können, müssen Sie zunächst ein Azure Blob Storage-Konto mit Ihrer Device Update-Instanz verknüpfen. In dieses Azure Blob Storage-Konto laden Ihre Geräte die Diagnoseprotokolle hoch.

Azure portal

1. Navigieren Sie im Azure-Portal zu Ihrem Geräteupdate für IoT Hub-Konto.

2. Wählen Sie Instanzen im Abschnitt Instanz-Verwaltung des Navigationsbereichs aus.

3. Wählen Sie in der Liste Ihre Device Update-Instanz und dann Diagnose konfigurieren aus.

4. Wählen Sie die Registerkarte Kundendiagnoseund dann Azure Storage-Konto auswählenaus.

5. Wählen Sie in der Liste das gewünschte Speicherkonto und dannSpeicherns aus.

6. Wenn Sie wieder in der Instanzliste sind, wählen Sie Regelmäßig aktualisieren aus, bis der Bereitstellungsstatus der Instanz „Erfolgreich“ anzeigt. Dieser Vorgang dauert normalerweise 2-3 Minuten.

Azure-Befehlszeilenschnittstelle

Verwenden Sie den Befehl az iot du instance create, um die Diagnose für Ihre Geräteupdateinstanz zu konfigurieren.

Tipp

Sie können den az iot du instance create-Befehl für eine vorhandene Geräteaktualisierungsinstanz verwenden und die Instanz wird mit den aktualisierten Parametern konfiguriert.

Ersetzen Sie die folgenden Platzhalter durch Ihre eigenen Informationen:

• <account_name>: Der Name Ihres Geräteaktualisierungskontos.
• <instance_name>: Der Name Ihrer Geräteaktualisierungsinstanz.
• <storage_id>: Die Ressourcen-ID des Speicherkontos, in dem die Diagnoseprotokolle gespeichert werden. Sie können die Ressourcen-ID abrufen, indem Sie den Befehl az storage showverwenden und den ID-Wert abfragen: az storage account show -n <storage_name> --query id.

az iot du instance update --account <account_name> --instance <instance_name> --set enableDiagnostics=true diagnosticStorageProperties.resourceId=<storage_id>

Konfigurieren Sie die Protokollsammlung

Der Geräteaktualisierungs-Agent verweist auf eine Konfigurationsdatei auf dem Gerät, die sich im Referenz-Agent unter /etc/adu/du-diagnostics-config.json befindet.

Pfade der Protokollsammlungsdatei

Der Device Update-Agent auf einem Gerät sammelt Dateien aus bestimmten Dateipfaden auf dem Gerät, wenn er ein Startsignal für den Protokollupload vom Device Update-Dienst empfängt. Diese Dateipfade werden in der Diagnose-Konfigurationsdatei definiert.

Innerhalb der Konfigurationsdatei wird jede zu erfassende und hochzuladende Protokolldatei als logComponent-Objekt mit den Eigenschaften componentName und logPath dargestellt. Diese Konfiguration kann nach Wunsch modifiziert werden.

Maximale Protokolldateigröße

Der Device Update-Agent sammelt Protokolldateien nur bis zu einer bestimmten Dateigröße. Diese maximale Dateigröße wird in der Diagnose-Konfigurationsdatei definiert.

Der relevante maxKilobytesToUploadPerLogPath-Parameter gilt für jedes logComponent-Objekt und kann nach Bedarf geändert werden.

Einen Protokolloperatioh erstellen

Protokollvorgänge sind eine dienstgesteuerte Aktion, die Sie Ihren IoT-Geräten über den Geräteaktualisierungsdienst zuweisen können. Eine ausführlichere Erläuterung der Funktionsweise von Protokollvorgängen finden Sie unter Diagnose für Geräteaktualisierungen.

Azure portal

1. Navigieren Sie zu Ihrem IoT-Hub, und wählen Sie im Navigationsbereich im Abschnitt Geräteverwaltung die Registerkarte Updates aus.

2. Wählen Sie die Registerkarte Diagnose auf der Benutzeroberfläche aus. Wenn die Registerkarte „Diagnose“ nicht angezeigt wird, stellen Sie sicher, dass Sie die neueste Version der Benutzeroberfläche von Device Update for IoT Hub verwenden. Wenn angezeigt wird, dass die Diagnose für diese Device Update-Instanz aktiviert werden muss, stellen Sie sicher, dass Sie ein Azure Blob Storage-Konto mit Ihrer Device Update-Instanz verknüpft haben.

3. Wählen Sie Add log upload operation (Protokolluploadvorgang hinzufügen) aus, um zur Seite für das Erstellen des Protokollvorgang zu navigieren.

4. Geben Sie einen Namen (ID) und eine Beschreibung für den neuen Protokollvorgang ein, und wählen Sie dann Geräte hinzufügen aus, um auszuwählen, von welchen IoT-Geräten Sie Diagnoseprotokolle sammeln möchten.

5. Wählen Sie Hinzufügen.

6. Wählen Sie zurück auf der Registerkarte „Diagnose“ die Option Aktualisieren aus, bis Ihr Protokollvorgang in der Vorgangstabelle aufgeführt wird.

7. Sobald der Vorgangsstatus Erfolgreich oder Fehlerhaft lautet, wählen Sie den Vorgangsnamen aus, um die zugehörigen Details anzuzeigen. Ein Vorgang wird nur dann als „Erfolgreich“ gekennzeichnet, wenn alle Zielgeräte den Protokollupload erfolgreich abgeschlossen haben. Wenn einige Zielgeräte erfolgreich waren und andere fehlgeschlagen sind, wird der Protokollvorgang als „Fehlgeschlagen“ gekennzeichnet. Sie können die Detailseite des Protokollvorgangs verwenden, um zu sehen, welche Geräte erfolgreich waren und welche fehlgeschlagen sind.

8. In den Protokollvorgangsdetails können Sie auch den gerätespezifischen Status und den Pfad des Protokollspeicherorts anzeigen. Dieser Pfad entspricht dem Pfad des virtuellen Verzeichnisses in Ihrem Azure Blob Storage-Konto, in das die Diagnoseprotokolle hochgeladen wurden.

Azure-Befehlszeilenschnittstelle

Verwenden Sie den Befehl az iot du device log collect, um einen Diagnoseprotokoll-Sammlungsvorgang zu konfigurieren.

Der Befehl device log collect akzeptiert folgende Argumente:

• --account: Der Device Update-Kontoname.
• --instance: Der Device Update-Instanzname.
• --log-collection-id: Ein Name für den Protokollsammlungsvorgang.
• --agent-id: Schlüssel=Wert-Paare, die einen Geräteupdate-Ziel-Agent für diesen Protokollsammlungsvorgang identifizieren. Verwenden Sie deviceId=<device name>, wenn der Agent über eine Geräteidentität verfügt. Verwenden Sie deviceId=<device name> moduleId=<module name>, wenn der Agent über eine Modulkennung verfügt. Sie können den --agent-id-Parameter mehrmals verwenden, um mehrere Geräte als Ziel anzugeben.

Zum Beispiel:

az iot du device log collect \
    --account <Device Update account name> \
    --instance <Device Update instance name> \
    --log-collection-id <log collection name} \
    --agent-id deviceId=<device name> \
    --agent-id deviceId=<device name> moduleId=<module name>

Verwenden Sie az iot du device log show, um die Details eines bestimmten Diagnoseprotokoll-Sammlungsvorgangs anzuzeigen.

az iot du device log show \
    --account <Device Update account name> \
    --instance <Device Update instance name> \
    --log-collection-id <log collection name>

Anzeigen und Exportieren der gesammelten Diagnoseprotokolle

1. Navigieren Sie nach einem erfolgreichen Protokollvorgang zu Ihrem Azure Blob Storage-Konto.

2. Wählen Sie im Navigationsbereich im Abschnitt Datenspeicherung die Option Container aus.

3. Wählen Sie den Container mit dem gleichen Namen wie Ihre Device Update-Instanz aus.

4. Verwenden Sie den Pfad des Protokollspeicherorts aus den Protokollvorgangsdetails, um zum richtigen Verzeichnis mit den Protokollen zu navigieren. Standardmäßig weist die Funktion zur Remoteprotokollsammlung Zielgeräte an, Diagnoseprotokolle in den folgenden Verzeichnispfad hochzuladen: Blob Storage-Container/Zielgeräte-ID/Protokollvorgangs-ID/Protokollpfad auf dem Gerät.

5. Wenn Sie die Diagnosekomponente des Geräteupdate-Agents nicht geändert haben, reagiert das Gerät auf jeden Protokollvorgang, indem es versucht, zwei Klartext-Protokolldateien hochzuladen: das Diagnoseprotokoll des Geräteupdate-Agents („aduc.log“) und das Diagnoseprotokoll des DO-Agents („do-agent.log“). Weitere Informationen zu den Protokolldateien, die vom Geräteupdate-Verweis-Agent gesammelt werden, finden Sie auf der Konzeptseite zur Geräteupdate-Diagnose.

6. Sie können den Inhalt der Protokolldatei anzeigen, indem Sie den Dateinamen und anschließend das Menüelement (Auslassungspunkte) auswählen und dann auf Ansicht/Bearbeiten klicken. Sie können die Protokolldatei auch herunterladen oder löschen, indem Sie die entsprechend bezeichneten Optionen auswählen.

   

Nächste Schritte

Weitere Informationen zu den Diagnosefunktionen von Device Update finden Sie unter Übersicht über die Diagnosefunktion von Geräteaktualisierungen