Freigeben über

Abrufen von Protokollen aus IoT Edge-Bereitstellungen

Gilt für:Häkchen für IoT Edge 1.5 IoT Edge 1.5

Wichtig

IoT Edge 1.5 LTS ist das unterstützte Release. IoT Edge 1.4 LTS wurde am 12. November 2024 eingestellt. Wenn Sie ein früheres Release verwenden, finden Sie weitere Informationen unter Aktualisieren von IoT Edge.

Rufen Sie Protokolle von Ihren IoT Edge-Bereitstellungen ohne physischen oder SSH-Zugriff ab, indem Sie direkte Methoden im IoT Edge-Agent-Modul verwenden. Direkte Methoden werden auf dem Gerät ausgeführt, und Sie können sie aus der Cloud aufrufen. Der IoT Edge-Agent verfügt über direkte Methoden, mit denen Sie Ihre IoT Edge-Geräte remote überwachen und verwalten können. Die direkten Methoden in diesem Artikel sind ab Version 1.0.10 verfügbar.

Weitere Informationen zu direkten Methoden, deren Verwendung und zum Hinzufügen zu Ihren eigenen Modulen finden Sie unter Grundlegendes und Aufrufen direkter Methoden aus IoT Hub.

Bei den Namen dieser direkten Methoden wird die Groß-/Kleinschreibung beachtet.

Verwenden Sie für optimale Kompatibilität mit diesem Feature das folgende Protokollierungsformat:

<{Log Level}> {Timestamp} {Message Text}

Formatieren Sie {Timestamp} als yyyy-MM-dd HH:mm:ss.fff zzz. Verwenden Sie {Log Level} Werte aus der folgenden Tabelle, basierend auf dem Schweregradcode im Syslog-Standard.

Wert Schweregrad
0 Notfall
1 Warnung
2 Kritisch
3 Fehler
4 Warnung
5 Benachrichtigen
6 Informativ
7 Fehlersuche

Die Logger-Klasse in IoT Edge ist eine kanonische Implementierung.

Abrufen von Modulprotokollen

Verwenden Sie die direkte GetModuleLogs-Methode , um die Protokolle eines IoT Edge-Moduls abzurufen.

Tipp

Verwenden Sie die since- und until-Filteroptionen um den abgerufenen Protokollbereich einzuschränken. Wenn Sie diese direkte Methode ohne Grenzen aufrufen, ruft sie alle Protokolle ab, die groß, zeitaufwendig oder kostspielig sein können.

Die Seite "Problembehandlung bei IoT Edge" im Azure-Portal bietet Ihnen eine einfachere Möglichkeit, Modulprotokolle anzuzeigen. Weitere Informationen finden Sie unter Überwachen und Beheben von Problemen bei IoT Edge-Geräten über das Azure-Portal.

Diese Methode akzeptiert eine JSON-Nutzlast mit dem folgenden Schema:

    {
       "schemaVersion": "1.0",
       "items": [
          {
             "id": "regex string",
             "filter": {
                "tail": "int",
                "since": "string",
                "until": "string",
                "loglevel": "int",
                "regex": "regex string"
             }
          }
       ],
       "encoding": "gzip/none",
       "contentType": "json/text" 
    }
Name Typ Beschreibung
schemaVersion Zeichenfolge Legen Sie den Wert 1.0
Elemente JSON-Array Ein Array mit den Tupeln id und filter
id Zeichenfolge Ein regulärer Ausdruck, der den Modulnamen angibt. Er kann mehreren Modulen auf einem Edgegerät entsprechen. Das Format Reguläre Ausdrücke von .NET wird erwartet. Wenn mehrere Elemente über eine ID verfügen, die demselben Modul entspricht, gelten nur die Filteroptionen der ersten übereinstimmenden ID für dieses Modul.
Filter JSON-Abschnitt Protokollfilter, die auf die Module angewendet werden, die mit dem regulären Ausdruck id im Tupel übereinstimmen
Schwanz Integer Anzahl der Protokollzeilen in der Vergangenheit, die abgerufen werden sollen, beginnend mit der neuesten. Optional.
seit Zeichenfolge Gibt seit dieser Zeit nur Protokolle als rfc3339-Zeitstempel, UNIX-Zeitstempel oder eine Dauer (Tage (d), Stunden (h), Minuten (m)) zurück. Beispiel: Eine Dauer von einem Tag, zwölf Stunden und dreißig Minuten kann als 1 Tag 12 Stunden 30 Minuten oder 1d 12h 30m angegeben werden. Wenn beide tail und since angegeben werden, werden die Protokolle zuerst mithilfe des since Werts gefiltert, dann wird der tail Wert auf das Ergebnis angewendet. Optional.
bis Zeichenfolge Gibt nur Protokolle vor der angegebenen Uhrzeit als rfc3339-Zeitstempel, UNIX-Zeitstempel oder Dauer (Tage (d), Stunden (h), Minuten (m)) zurück. Beispielsweise kann eine Dauer von 90 Minuten als 90 Minuten oder 90m angegeben werden. Wenn beide tail und since angegeben werden, werden die Protokolle zuerst mithilfe des since Werts gefiltert, dann wird der tail Wert auf das Ergebnis angewendet. Optional.
Loglevel Integer Filtern Sie Protokolllinien, die der angegebenen Protokollebene entsprechen. Protokollzeilen sollten dem empfohlenen Protokollierungsformat entsprechen und den Syslog-Schweregradstandard verwenden. Wenn Sie nach mehreren Schweregradwerten auf Protokollebene filtern müssen, verwenden Sie regex-Abgleich, vorausgesetzt, das Modul verwendet ein konsistentes Format für unterschiedliche Schweregrade. Optional.
Regex Zeichenfolge Protokollzeilen filtern, die mit dem angegebenen regulären Ausdruck im Format .NET Regular Expressions übereinstimmen. Optional.
Kodierung Zeichenfolge Entweder gzip oder none. Der Standardwert ist none.
Inhaltstyp Zeichenfolge Entweder json oder text. Der Standardwert ist text.

Hinweis

Wenn der Protokollinhalt den Grenzwert für die Antwortgröße für direkte Methoden überschreitet, was derzeit 128 KB beträgt, gibt die Antwort einen Fehler zurück.

Ein erfolgreicher Protokollabruf gibt einen "Status" zurück: 200 gefolgt von einer Nutzlast mit den Protokollen aus dem Modul, gefiltert nach den Einstellungen, die Sie in Ihrer Anforderung angeben.

Zum Beispiel:

az iot hub invoke-module-method --method-name 'GetModuleLogs' -n <hub name> -d <device id> -m '$edgeAgent' --method-payload \
'
    {
       "schemaVersion": "1.0",
       "items": [
          {
             "id": "edgeAgent",
             "filter": {
                "tail": 10
             }
          }
       ],
       "encoding": "none",
       "contentType": "text"
    }
'

Rufen Sie im Azure-Portal die Methode GetModuleLogs und die folgende JSON-Nutzlast auf:

    {
       "schemaVersion": "1.0",
       "items": [
          {
             "id": "edgeAgent",
             "filter": {
                "tail": 10
             }
          }
       ],
       "encoding": "none",
       "contentType": "text"
    }

Screenshot zum Aufrufen der direkten Methode „GetModuleLogs“ im Azure-Portal.

Sie können die CLI-Ausgabe auch an Linux-Hilfsprogramme wie gzip umleiten, um eine komprimierte Antwort zu verarbeiten. Zum Beispiel:

az iot hub invoke-module-method \
  --method-name 'GetModuleLogs' \
  -n <hub name> \
  -d <device id> \
  -m '$edgeAgent' \
  --method-payload '{"contentType": "text","schemaVersion": "1.0","encoding": "gzip","items": [{"id": "edgeHub","filter": {"since": "2d","tail": 1000}}],}' \
  -o tsv --query 'payload[0].payloadBytes' \
  | base64 --decode \
  | gzip -d

Hochladen von Modulprotokollen

Verwenden Sie die direkte UploadModuleLogs-Methode , um die angeforderten Protokolle an einen bestimmten Azure Blob Storage-Container zu senden.

Hinweis

Verwenden Sie die since- und until-Filteroptionen um den abgerufenen Protokollbereich einzuschränken. Das Aufrufen dieser direkten Methode ohne Grenzen ruft alle Protokolle ab, die groß, zeitaufwändig oder kostspielig sein können.

Um Protokolle von einem Gerät hinter einem Gatewaygerät hochzuladen, stellen Sie sicher, dass die API-Proxy- und BLOB-Speichermodule auf dem Gerät auf oberster Ebene konfiguriert sind. Diese Module leiten Protokolle von Ihrem Gerät mit niedrigerer Ebene über Ihr Gatewaygerät an Ihren Speicher in der Cloud weiter.

Diese Methode akzeptiert eine JSON-Nutzlast ähnlich wie GetModuleLogs mit dem hinzugefügten "sasUrl"-Schlüssel:

    {
       "schemaVersion": "1.0",
       "sasUrl": "Full path to SAS URL",
       "items": [
          {
             "id": "regex string",
             "filter": {
                "tail": "int",
                "since": "string",
                "until": "string",
                "loglevel": "int",
                "regex": "regex string"
             }
          }
       ],
       "encoding": "gzip/none",
       "contentType": "json/text" 
    }
Name Typ Beschreibung
sasURL Zeichenfolge (URI) Shared Access Signature-URL mit Schreibzugriff auf den Azure Blob Storage-Container

Eine erfolgreiche Anforderung zum Hochladen von Protokollen gibt „Status“: 200 zurück, gefolgt von einer Nutzlast mit dem folgenden Schema:

    {
        "status": "string",
        "message": "string",
        "correlationId": "GUID"
    }
Name Typ Beschreibung
Status Zeichenfolge NotStarted, Running, Completed, Failed oder Unknown
Nachricht Zeichenfolge Meldung, wenn ein Fehler vorliegt oder andernfalls eine leere Zeichenfolge.
correlationId Zeichenfolge ID, um den Status der Uploadanforderung zu überprüfen.

Der folgende Aufruf lädt beispielsweise die letzten 100 Protokollzeilen aus allen Modulen im komprimierten JSON-Format hoch:

az iot hub invoke-module-method --method-name UploadModuleLogs -n <hub name> -d <device id> -m '$edgeAgent' --method-payload \
'
    {
        "schemaVersion": "1.0",
        "sasUrl": "<sasUrl>",
        "items": [
            {
                "id": ".*",
                "filter": {
                    "tail": 100
                }
            }
        ],
        "encoding": "gzip",
        "contentType": "json"
    }
'

Der folgende Aufruf lädt die letzten 100 Protokollzeilen von edgeAgent und edgeHub und die letzten 1.000 Protokollzeilen aus dem tempSensor-Modul im unkomprimierten Textformat hoch:

az iot hub invoke-module-method --method-name UploadModuleLogs -n <hub name> -d <device id> -m '$edgeAgent' --method-payload \
'
    {
        "schemaVersion": "1.0",
        "sasUrl": "<sasUrl>",
        "items": [
            {
                "id": "edge",
                "filter": {
                    "tail": 100
                }
            },
            {
                "id": "tempSensor",
                "filter": {
                    "tail": 1000
                }
            }
        ],
        "encoding": "none",
        "contentType": "text"
    }
'

Rufen Sie im Azure-Portal die Methode mit dem Methodennamen UploadModuleLogs und der folgenden JSON-Nutzlast auf, nachdem Sie die sasUrl durch Ihre Informationen ersetzt haben:

    {
       "schemaVersion": "1.0",
       "sasUrl": "<sasUrl>",
       "items": [
          {
             "id": "edgeAgent",
             "filter": {
                "tail": 10
             }
          }
       ],
       "encoding": "none",
       "contentType": "text"
    }

Screenshot des Aufrufens der direkten UploadModuleLogs-Methode im Azure-Portal.

Hochladen von Supportbundlediagnosen

Verwenden Sie die direkte Methode UploadSupportBundle, und laden Sie eine ZIP-Datei mit IoT Edge-Modulprotokollen in einen verfügbaren Azure Blob Storage-Container hoch. Diese direkte Methode führt den Befehl iotedge support-bundle auf Ihrem IoT Edge-Gerät aus, um die Protokolle abzurufen.

Hinweis

Um Protokolle von einem Gerät hinter einem Gatewaygerät hochzuladen, stellen Sie sicher, dass die API-Proxy- und BLOB-Speichermodule auf dem Gerät der obersten Ebene eingerichtet sind. Diese Module leiten Protokolle von Ihrem Gerät mit niedrigerer Ebene über Ihr Gatewaygerät an Ihren Speicher in der Cloud weiter.

Diese Methode akzeptiert eine JSON-Nutzlast mit dem folgenden Schema:

    {
        "schemaVersion": "1.0",
        "sasUrl": "Full path to SAS url",
        "since": "2d",
        "until": "1d",
        "edgeRuntimeOnly": false
    }
Name Typ Beschreibung
schemaVersion Zeichenfolge Auf 1.0 festlegen.
sasURL Zeichenfolge (URI) Shared Access Signature-URL mit Schreibzugriff auf den Azure Blob Storage-Container
seit Zeichenfolge Gibt protokolle seit dieser Zeit als RFC 3339-Zeitstempel, UNIX-Zeitstempel oder eine Dauer (Tage (d), Stunden (h), Minuten (m)) zurück. Geben Sie beispielsweise einen Tag, 12 Stunden und 30 Minuten als 1 Tag 12 Stunden 30 Minuten oder 1d 12h 30m an. Wahlfrei.
bis Zeichenfolge Gibt Protokolle vor dieser Zeit als RFC 3339-Zeitstempel, UNIX-Zeitstempel oder Dauer (Tage (d), Stunden (h), Minuten (m)) zurück. Geben Sie beispielsweise 90 Minuten als 90 Minuten oder 90m an. Wahlfrei.
edgeRuntimeOnly Boolescher Wert Bei „true“ werden Protokolle nur von Edge Agent, Edge Hub und dem Edge-Sicherheitsdaemon zurückgegeben. Standardwert: false. Wahlfrei.

Wichtig

Das IoT Edge-Supportpaket kann personenbezogene Informationen enthalten.

Eine Anforderung für erfolgreiche Uploadprotokolle gibt einen "Status" zurück: 200 und eine Nutzlast mit demselben Schema wie die UploadModuleLogs-Antwort :

    {
        "status": "string",
        "message": "string",
        "correlationId": "GUID"
    }
Name Typ Beschreibung
Status Zeichenfolge NotStarted, Running, Completed, Failed oder Unknown
Nachricht Zeichenfolge Meldung bei einem Fehler, andernfalls leere Zeichenfolge
correlationId Zeichenfolge ID zum Abfragen des Status der Uploadanforderung

Ersetzen Sie im folgenden Beispiel den Platzhaltertext <hub name> und <device id> mit Ihren eigenen Werten.

az iot hub invoke-module-method --method-name 'UploadSupportBundle' -n <hub name> -d <device id> -m '$edgeAgent' --method-payload \
'
    {
        "schemaVersion": "1.0",
        "sasUrl": "Full path to SAS url",
        "since": "2d",
        "until": "1d",
        "edgeRuntimeOnly": false
    }
'

Rufen Sie im Azure-Portal die Methode mit dem Methodennamen UploadSupportBundle und der folgenden JSON-Nutzlast auf, nachdem Sie Ihre eigene SAS-URL neu verkettet haben:

    {
        "schemaVersion": "1.0",
        "sasUrl": "Full path to SAS url",
        "since": "2d",
        "until": "1d",
        "edgeRuntimeOnly": false
    }

Screenshot des Aufrufens der Direkten UploadSupportBundle-Methode im Azure-Portal.

Abrufen des Status der Uploadanforderung

Verwenden Sie die direkte GetTaskStatus-Methode , um den Status einer Uploadprotokollanforderung zu überprüfen. Die GetTaskStatus-Anforderungsnutzlast verwendet die correlationId Anforderung aus der Uploadprotokollanforderung, um den Aufgabenstatus abzurufen. Dies correlationId stammt aus der Antwort auf den direkten UploadModuleLogs-Methodenaufruf.

Diese Methode akzeptiert eine JSON-Nutzlast mit dem folgenden Schema:

    {
      "schemaVersion": "1.0",
      "correlationId": "<GUID>"
    }

Eine erfolgreiche Anforderung zum Hochladen von Protokollen gibt „Status“: 200 zurück, gefolgt von einer Nutzlast mit demselben Schema wie die UploadModuleLogs-Antwort:

    {
        "status": "string",
        "message": "string",
        "correlationId": "GUID"
    }
Name Typ Beschreibung
Status Zeichenfolge Einer von der folgenden Werte: NotStarted, Running, Completed, Failed, Cancelled oder Unknown.
Nachricht Zeichenfolge Meldung bei einem Fehler, andernfalls leere Zeichenfolge
correlationId Zeichenfolge ID zum Abfragen des Status der Uploadanforderung

Zum Beispiel:

az iot hub invoke-module-method --method-name 'GetTaskStatus' -n <hub name> -d <device id> -m '$edgeAgent' --method-payload \
'
    {
      "schemaVersion": "1.0",
      "correlationId": "<GUID>"
    }
'

Rufen Sie im Azure-Portal die Methode mit dem Methodennamen GetTaskStatus und der folgenden JSON-Nutzlast auf. Ersetzen Sie <GUID> durch Ihren eigenen Wert.

    {
      "schemaVersion": "1.0",
      "correlationId": "<GUID>"
    }

Screenshot des Azure-Portals, in dem gezeigt wird, wie die direkte Methode GetTaskStatus aufgerufen wird.

Nächste Schritte

Eigenschaften der Modulzwillinge von IoT Edge-Agent und IoT Edge-Hub