Teilen über

Abrufen von Protokollen aus IoT Edge-Bereitstellungen

  • Artikel

Gilt für:Häkchen für IoT Edge 1.5 IoT Edge 1.5 IoT Edge 1.4 Häkchen 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.

Rufen Sie Protokolle aus Ihren IoT Edge-Bereitstellungen ab, ohne dass Sie physischen oder SSH-Zugriff auf das Gerät benötigen, indem Sie die direkten Methoden verwenden, die im IoT Edge-Agent-Modul enthalten sind. Direkte Methoden werden auf dem Gerät implementiert und können dann über die Cloud aufgerufen werden. Der IoT Edge-Agent umfasst direkte Methoden, mit denen Sie Ihre IoT Edge-Geräte remote überwachen und verwalten können. Die in diesem Artikel erläuterten direkten Methoden sind mit der Version 1.0.10 allgemein verfügbar.

Weitere Informationen zu direkten Methoden sowie zu ihrer Verwendung und Implementierung in Ihren eigenen Modulen finden Sie unter Verstehen und Aufrufen direkter Methoden von IoT Hub.

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

Es ist zwar nicht erforderlich, für die bestmögliche Kompatibilität mit diesem Feature wird jedoch folgendes Protokollformat empfohlen:

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

{Timestamp} muss als yyyy-MM-dd HH:mm:ss.fff zzz formatiert werden, und {Log Level} sollte die nachfolgende Tabelle verwenden, die die Schweregrade von dem Schweregradcode im Syslog-Standard ableitet.

Wert Severity
0 Notfall
1 Warnung
2 Kritisch
3 Fehler
4 Warnung
5 Benachrichtigen
6 Informational
7 Debug

Die Protokollierungsklasse in IoT Edge fungiert als kanonische Implementierung.

Abrufen von Modulprotokollen

Verwenden Sie die direkte Methode GetModuleLogs, 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, werden alle Protokolle abgerufen, die groß und somit zeitaufwendig oder kostspielig sein können.

Die IoT Edge-Problembehandlungsseite im Azure-Portal bietet eine vereinfachte Benutzeroberfläche zum Anzeigen von Modulprotokollen. 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 bereitstellt. Er kann mehreren Modulen auf einem Edgegerät entsprechen. Das Format Reguläre Ausdrücke von .NET wird erwartet. Wenn es mehrere Elemente gibt, deren ID mit demselben Modul übereinstimmt, werden nur die Filteroptionen der ersten übereinstimmenden ID auf dieses Modul angewendet.
filter JSON-Abschnitt Protokollfilter, die auf die Module angewendet werden, die mit dem regulären Ausdruck id im Tupel übereinstimmen
tail integer Die Anzahl der abzurufenden Protokollzeilen in der Vergangenheit, beginnend mit der neuesten OPTIONAL.
since Zeichenfolge Gibt nur Protokolle ab diesem Zeitpunkt in Form eines rfc3339-Zeitstempels, eines UNIX-Zeitstempels oder einer 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 sowohl tail als auch since angegeben werden, werden die Protokolle zuerst mit dem Wert since abgerufen. Anschließend wird der Wert tail auf das Ergebnis angewendet, und das Endergebnis wird zurückgegeben. OPTIONAL.
bis Zeichenfolge Gibt nur Protokolle vor dem angegebenen Zeitpunkt in Form eines rfc3339-Zeitstempels, eines UNIX-Zeitstempels oder einer Dauer (Tage [d] Stunden [h] Minuten [m]) zurück. Beispiel: Eine Dauer von neunzig Minuten kann als 90 Minuten oder 90m angegeben werden. Wenn sowohl tail als auch since angegeben werden, werden die Protokolle zuerst mit dem Wert since abgerufen. Anschließend wird der Wert tail auf das Ergebnis angewendet, und das Endergebnis wird zurückgegeben. OPTIONAL.
loglevel integer Filtert Protokollzeilen, die gleich der angegebenen Protokollebene sind. Protokollzeilen sollten dem empfohlenen Protokollierungsformat entsprechen und den Syslog-Schweregradstandard verwenden. Wenn Sie nach mehreren Schweregradwerten auf Protokollebene filtern müssen, verwenden Sie „regex“-Übereinstimmung, sofern das Modul ein einheitliches Format hat, wenn unterschiedliche Schweregrade protokolliert werden. OPTIONAL.
regex Zeichenfolge Filtert Protokollzeilen mithilfe des Formats Reguläre Ausdrücke von .NET mit Inhalten, die dem angegebenen regulären Ausdruck entsprechen. OPTIONAL.
encoding Zeichenfolge Entweder gzip oder none. Der Standardwert ist none.
contentType Zeichenfolge Entweder json oder text. Der Standardwert ist text.

Hinweis

Wenn der Inhalt der Protokolle die Antwortgrößenbeschränkung direkter Methoden überschreitet, die derzeit 128 KB beträgt, gibt die Antwort einen Fehler zurück.

Ein erfolgreicher Abruf von Protokollen gibt „status“: 200 zurück, gefolgt von einer Nutzlast, die die Protokolle enthält, die aus dem Modul abgerufen wurden, 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 mit dem Namen GetModuleLogs und der folgenden 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 Methode UploadModuleLogs, um die angeforderten Protokolle an einen angegebenen Azure Blob Storage-Container zu senden.

Hinweis

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

Wenn Sie Protokolle von einem Gerät hinter einem Gatewaygerät hochladen möchten, müssen Sie die API-Proxy- und Blobspeichermodule auf dem Gerät der obersten Ebene konfiguriert haben. Diese Module leiten die Protokolle vom Gerät der niedrigeren Ebene über das Gatewaygerät an den Speicher in der Cloud weiter.

Diese Methode akzeptiert eine JSON-Nutzlast, die GetModuleLogs ähnelt, wobei der Schlüssel sasUrl hinzugefügt wird:

    {
       "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
message Zeichenfolge Meldung bei einem Fehler, andernfalls leere Zeichenfolge
correlationId Zeichenfolge ID zum Abfragen des Status der Uploadanforderung

Zum Beispiel:

Der folgende Aufruf lädt 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 mit den letzten 1000 Protokollzeilen des tempSensor-Moduls in unkomprimiertem 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 Namen UploadModuleLogs und der folgenden JSON-Nutzlast auf, nachdem Sie die sasURL mit Ihren Informationen aufgefüllt haben:

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

Screenshot zum Aufrufen der direkten Methode „UploadModuleLogs“ 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

Wenn Sie Protokolle von einem Gerät hinter einem Gatewaygerät hochladen möchten, müssen Sie die API-Proxy- und Blobspeichermodule auf dem Gerät der obersten Ebene konfiguriert haben. Diese Module leiten die Protokolle vom Gerät der niedrigeren Ebene über das Gatewaygerät an den 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 Legen Sie den Wert 1.0
sasURL Zeichenfolge (URI) Shared Access Signature-URL mit Schreibzugriff auf den Azure Blob Storage-Container
since Zeichenfolge Gibt nur Protokolle ab diesem Zeitpunkt in Form eines rfc3339-Zeitstempels, eines UNIX-Zeitstempels oder einer 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. OPTIONAL.
bis Zeichenfolge Gibt nur Protokolle vor dem angegebenen Zeitpunkt in Form eines rfc3339-Zeitstempels, eines UNIX-Zeitstempels oder einer Dauer (Tage [d] Stunden [h] Minuten [m]) zurück. Beispiel: Eine Dauer von neunzig Minuten kann als 90 Minuten oder 90m angegeben werden. OPTIONAL.
edgeRuntimeOnly boolean Bei „true“ werden nur Protokolle von Edge Agent, Edge Hub und dem Edge-Sicherheitsdaemon zurückgegeben. Standardwert: false. OPTIONAL.

Wichtig

Ein IoT Edge-Supportbundle enthält unter Umständen personenbezogene Informationen.

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 NotStarted, Running, Completed, Failed oder Unknown
message 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 '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 Namen UploadSupportBundle und der folgenden JSON-Nutzlast auf, nachdem Sie die sasURL mit Ihren Informationen aufgefüllt haben:

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

Screenshot, der zeigt, wie die direkte Methode „UploadSupportBundle“ im Azure-Portal aufgerufen wird.

Abrufen des Status der Uploadanforderung

Verwenden Sie die direkte Methode GetTaskStatus, um den Status einer Anforderung zum Hochladen von Protokollen abzufragen. Die Anforderungsnutzlast GetTaskStatus verwendet die correlationId der Anforderung zum Hochladen von Protokollen, um den Status der Aufgabe abzurufen. Die correlationId wird als Antwort auf den Aufruf der direkten Methode UploadModuleLogs zurückgegeben.

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 NotStarted, Running, Completed, Failed, „Cancelled“ oder Unknown
message 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 Namen GetTaskStatus und der folgenden JSON-Nutzlast auf, nachdem Sie die GUID mit Ihren Informationen aufgefüllt haben:

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

Screenshot, der zeigt, wie die direkte Methode „GetTaskStatus“ im Azure-Portal aufgerufen wird.

Nächste Schritte

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