Übersicht über die Diagnose bei Device Update for IoT Hub

  • Artikel

Device Update for IoT Hub enthält mehrere Features, die Ihnen bei der Diagnose und Problembehandlung von Fehlern auf Geräten helfen. Mit dem Release des Agents von v0.9.0 stehen drei Diagnosefeatures zur Verfügung:

  • Bereitstellungsfehlercodes können direkt auf der Benutzeroberfläche von Device Update angezeigt werden.

  • Die Remoteprotokollsammlung ermöglicht die Erstellung von Protokollvorgängen, die Zielgeräte anweisen, Diagnoseprotokolle auf dem Gerät in ein verknüpftes Azure Blob Storage-Konto hochzuladen.

  • Agent Check führt Validierungsüberprüfungen auf Geräten aus, die bei Ihrer Device Update-Instanz registriert sind, um Geräte zu ermitteln, die in der verbundenen IoT Hub-Instanz registriert sind, jedoch nicht in Device Update angezeigt werden.

Fehlercodes zu Bereitstellungsfehlern auf der Benutzeroberfläche

Wenn ein Gerät einen Bereitstellungsfehler an den Device Update-Dienst meldet, werden auf der Benutzeroberfläche von Device Update der vom Gerät gemeldete resultCode und extendedResultCode angezeigt. Führen Sie die folgenden Schritte aus, um diese Codes anzuzeigen:

  1. Navigieren Sie im Azure-Portal zu Ihrem IoT Hub.

  2. Wählen Sie Updates aus, und navigieren Sie zur Registerkarte Gruppen und Bereitstellungen.

  3. Wählen Sie den Namen einer Gruppe mit einer aktiven Bereitstellung aus, damit die Seite Gruppendetails angezeigt wird.

  4. Wählen Sie in der Geräteliste einen beliebigen Gerätenamen aus, um den Bereich mit den Gerätedetails zu öffnen. Hier wird der vom Gerät gemeldete Ergebniscode angezeigt.

  5. Der Verweis-Agent von Device Update folgt im Feld „Ergebniscode“ den Standardkonventionen für HTTP-Statuscodes (beispielsweise steht „200“ für eine erfolgreiche Aktion). Weitere Informationen zum Analysieren von Ergebniscodes finden Sie unter Clientfehlercodes in Device Update.

    Hinweis

    Wenn Sie Ihren Device Update-Agent so geändert haben, dass er angepasste Ergebniscodes meldet, werden die numerischen Codes weiterhin an die Benutzeroberfläche von Device Update übergeben. Nutzen Sie dann Ihre Dokumentation, um diese numerischen Codes zu analysieren.

Remoteprotokollsammlung

Wenn weitere Informationen vom Gerät erforderlich sind, um einen Fehler zu diagnostizieren und zu beheben, können Sie das Protokollsammlungsfeature verwenden, um die Zielgeräte anzuweisen, Diagnoseprotokolle vom Gerät in ein verknüpftes Azure Blob Storage-Konto hochzuladen. Sie können mit der Verwendung dieses Features beginnen, indem Sie den Anleitungen in Remotesammlung von Diagnoseprotokollen von Geräten folgen.

Die Remoteprotokollsammlung von Device Update ist ein dienstgesteuertes, vorgangsbasiertes Feature. Um die Protokollsammlung nutzen zu können, muss ein Gerät nur die Diagnoseschnittstelle und die Konfigurationsdatei implementieren und Dateien über das SDK in Azure Blob Storage hochladen können.

Grundsätzlich funktioniert das Protokollsammlungsfeature wie folgt:

  1. Ein Benutzer erstellt über die Benutzeroberfläche von Device Update oder APIs einen neuen Protokollvorgang für bis zu 100 Geräte, auf denen die Diagnoseschnittstelle implementiert ist.

  2. Der Device Update-Dienst sendet über die Diagnoseschnittstelle eine Startmeldung für die Protokollsammlung an die Zielgeräte. Diese Startmeldung enthält die Protokollvorgangs-ID und ein SAS-Token für das Hochladen in das Azure Storage-Konto.

  3. Nach dem Empfang der Startmeldung versucht der Device Update-Agent des Zielgeräts, die Dateien zu sammeln und in die vordefinierten Dateipfade hochzuladen, die in der Agent-Konfigurationsdatei auf dem Gerät angegeben wurden. Der Verweis-Agent von Device Update ist so konfiguriert, dass er standardmäßig das Device Update-Agent-Diagnoseprotokoll (aduc.log) und das DO-Agent-Diagnoseprotokoll („do-agent.log“) hochlädt.

  4. Der Device Update-Agent meldet dann den Status des Vorgangs (Erfolgreich oder Fehlerhaft) mit der Protokollvorgangs-ID, einem „ResultCode“ und einem „ExtendedResultCode“ an den Dienst zurück. Wenn der Protokollvorgang im Device Update-Agent zu einem Fehler führt, versucht der Agent automatisch, den Vorgang dreimal zu wiederholen, meldet aber nur den abschließenden Status an den Dienst zurück.

  5. Nachdem alle Zielgeräte ihren Terminalstatus an den Device Update-Dienst zurückgemeldet haben, kennzeichnet dieser Dienst den Protokollvorgang als Erfolgreich oder Fehlerhaft. Ein erfolgreicher Protokollvorgang gibt an, dass ihn alle Zielgeräte erfolgreich abgeschlossen haben. Ein fehlerhafter Protokollvorgang gibt an, dass er bei mindestens einem Zielgerät zu einem Fehler geführt hat.

    Hinweis

    Da der Protokollvorgang parallel zu den Zielgeräten ausgeführt wird, ist es möglich, dass einige Zielgeräte Protokolle erfolgreich hochgeladen haben, der gesamte Vorgang aber als fehlerhaft gekennzeichnet wird. Sie können sehen, welche Geräte erfolgreich waren und bei welchen ein Fehler aufgetreten ist, indem Sie die Details zum Protokollvorgang über die Benutzeroberfläche oder APIs anzeigen.

Agent Check

Wenn Ihr Gerät bei der IoT Hub-Instanz registriert ist, aber nicht in Ihrer Device Update-Instanz angezeigt wird, können Sie Agent Check verwenden, um vorgefertigte Validierungsüberprüfungen auszuführen, um das zugrunde liegende Problem zu ermitteln. Beginnen Sie mit dem Verwenden dieses Features, indem Sie diese Anweisungen zu Agent Check befolgen.

Grundsätzlich funktioniert das Feature für Agent Check wie folgt:

  • Benutzer*innen registrieren ein Gerät bei IoT Hub. Wenn das Gerät eine Modell-ID meldet, die mit denen übereinstimmt, die mit Device Update for IoT Hub kompatibel sind, registriert die verbundene Device Update-Instanz der Benutzer*innen das Gerät automatisch bei Device Update.

  • Damit ein Gerät ordnungsgemäß von Device Update verwaltet werden kann, muss es bestimmte Kriterien erfüllen, die mithilfe der vordefinierten Validierungsüberprüfungen von Agent Check überprüft werden können. Weitere Informationen zu diesen Kriterien finden Sie hier.

  • Wenn ein Gerät nicht alle diese Kriterien erfüllt, kann es von Device Update nicht ordnungsgemäß verwaltet werden und wird nicht in der Device Update-Schnittstelle oder in den API-Antworten angezeigt. Benutzer*innen können mit Agent Check dieses Gerät finden und ermitteln, welche Kriterien nicht erfüllt werden.

  • Nachdem die Benutzer*innen ermittelt haben, welche Kriterien nicht erfüllt sind, können sie das Problem beheben. Das Gerät sollte dann ordnungsgemäß in der Device Update-Schnittstelle angezeigt werden.

Nächste Schritte

Hier erfahren Sie, wie Sie die Features von Device Update zur Remoteprotokollsammlung und für Agent Check verwenden: