Abrufen von Protokollen aus IoT Edge-Bereitstellungen
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.
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.
Empfohlenes Protokollformat
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"
}
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"
}
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
}
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>"
}
Nächste Schritte
Eigenschaften der Modulzwillinge von IoT Edge-Agent und IoT Edge-Hub
Feedback
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Issues stufenweise als Feedbackmechanismus für Inhalte abbauen und durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unter https://aka.ms/ContentUserFeedback.
Feedback senden und anzeigen für