Recuperare i log dalle distribuzioni IoT Edge
Si applica a:
IoT Edge 1.5 IoT Edge 1.4
Importante
IoT Edge 1.5 LTS e IoT Edge 1.4 LTS sono versioni supportate. IoT Edge 1.4 LTS è di fine vita il 12 novembre 2024. Se si usa una versione precedente, vedere Aggiornare IoT Edge.
Recuperare i log dalle distribuzioni di IoT Edge senza dover accedere fisicamente o SSH al dispositivo usando i metodi diretti inclusi nel modulo agente IoT Edge. I metodi diretti vengono implementati nel dispositivo e quindi possono essere richiamati dal cloud. L'agente IoT Edge include metodi diretti che consentono di monitorare e gestire i dispositivi IoT Edge in remoto. I metodi diretti descritti in questo articolo sono disponibili a livello generale con la versione 1.0.10.
Per altre informazioni sui metodi diretti, su come usarli e su come implementarli nei propri moduli, vedere Comprendere e richiamare metodi diretti da hub IoT.
I nomi di questi metodi diretti vengono gestiti con distinzione tra maiuscole e minuscole.
Formato di registrazione consigliato
Anche se non è necessario, per garantire la migliore compatibilità con questa funzionalità, il formato di registrazione consigliato è:
<{Log Level}> {Timestamp} {Message Text}
{Timestamp} deve essere formattato come yyyy-MM-dd HH:mm:ss.fff zzze {Log Level} deve usare la tabella seguente, che deriva i livelli di gravità dal codice Gravità nello standard Syslog.
| Valore | Gravità |
|---|---|
| 0 | Emergenza |
| 1 | Avviso |
| 2 | Critico |
| 3 | Errore |
| 4 | Avviso |
| 5 | Preavviso |
| 6 | Informazioni |
| 7 | Debug |
La classe Logger in IoT Edge funge da implementazione canonica.
Recuperare i log dei moduli
Usare il metodo diretto GetModuleLogs per recuperare i log di un modulo IoT Edge.
Suggerimento
Usare le since opzioni di filtro e until per limitare l'intervallo di log recuperati. La chiamata a questo metodo diretto senza limiti recupera tutti i log che possono richiedere molto tempo o costoso.
La pagina di risoluzione dei problemi di IoT Edge nella portale di Azure offre un'esperienza semplificata per la visualizzazione dei log dei moduli. Per altre informazioni, vedere Monitorare e risolvere i problemi dei dispositivi IoT Edge dal portale di Azure.
Questo metodo accetta un payload JSON con lo schema seguente:
{
"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"
}
| Nome | Tipo | Descrizione |
|---|---|---|
| schemaVersion | string | Impostare su 1.0 |
| articoli | Matrice JSON | Matrice con id tuple e filter . |
| id | string | Espressione regolare che fornisce il nome del modulo. Può corrispondere a più moduli in un dispositivo perimetrale. È previsto il formato delle espressioni regolari .NET. Nel caso in cui vi siano più elementi il cui ID corrisponde allo stesso modulo, solo le opzioni di filtro del primo ID corrispondente vengono applicate a tale modulo. |
| filter | Sezione JSON | Filtri di log da applicare ai moduli corrispondenti all'espressione id regolare nella tupla. |
| coda | integer | Numero di righe di log nel passato da recuperare a partire dall'ultima versione. FACOLTATIVO |
| since | string | Restituisce solo i log da questa volta, come timestamp rfc3339, timestamp UNIX o durata (giorni (d) ore (h) (m)). Ad esempio, una durata per un giorno, 12 ore e 30 minuti può essere specificata come 1 giorno 12 ore 30 minuti o 1d 12h 30m. Se vengono specificati e tail since , i log vengono recuperati usando prima il since valore . tail Il valore viene quindi applicato al risultato e viene restituito il risultato finale. FACOLTATIVO |
| until | string | Restituisce solo i log prima dell'ora specificata, come timestamp rfc3339, timestamp UNIX o durata (giorni (d) ore (h) (m)). Ad esempio, una durata di 90 minuti può essere specificata come 90 minuti o 90 minuti. Se vengono specificati e tail since , i log vengono recuperati usando prima il since valore . tail Il valore viene quindi applicato al risultato e viene restituito il risultato finale. FACOLTATIVO |
| loglevel | integer | Filtrare le righe di log uguali al livello di log specificato. Le righe di log devono seguire il formato di registrazione consigliato e usare lo standard di livello di gravità syslog. Se è necessario filtrare in base a più valori di gravità del livello di log, quindi basarsi sulla corrispondenza regex, purché il modulo segua un formato coerente quando si registrano livelli di gravità diversi. FACOLTATIVO |
| regex | string | Filtrare le righe di log con contenuto che corrispondono all'espressione regolare specificata usando il formato espressioni regolari .NET. FACOLTATIVO |
| codifica | string | gzip o none. Il valore predefinito è none. |
| contentType | string | json o text. Il valore predefinito è text. |
Nota
Se il contenuto dei log supera il limite di dimensioni della risposta dei metodi diretti, attualmente pari a 128 KB, la risposta restituisce un errore.
Un recupero riuscito dei log restituisce uno "stato": 200 seguito da un payload contenente i log recuperati dal modulo, filtrati in base alle impostazioni specificate nella richiesta.
Ad esempio:
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"
}
'
Nella portale di Azure richiamare il metodo con il nome GetModuleLogs del metodo e il payload JSON seguente:
{
"schemaVersion": "1.0",
"items": [
{
"id": "edgeAgent",
"filter": {
"tail": 10
}
}
],
"encoding": "none",
"contentType": "text"
}
È anche possibile inviare tramite pipe l'output dell'interfaccia della riga di comando alle utilità Linux, ad esempio gzip, per elaborare una risposta compressa. Ad esempio:
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
Caricare i log dei moduli
Usare il metodo diretto UploadModuleLogs per inviare i log richiesti a un contenitore di Archiviazione BLOB di Azure specificato.
Nota
Usare le since opzioni di filtro e until per limitare l'intervallo di log recuperati. La chiamata a questo metodo diretto senza limiti recupera tutti i log che possono richiedere molto tempo o costoso.
Se si desidera caricare i log da un dispositivo dietro un dispositivo gateway, è necessario che i moduli di proxy API e archiviazione BLOB siano configurati nel dispositivo di livello superiore. Questi moduli instradano i log dal dispositivo di livello inferiore attraverso il dispositivo gateway all'archiviazione nel cloud.
Questo metodo accetta un payload JSON simile a GetModuleLogs, con l'aggiunta della chiave "sasUrl":
{
"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"
}
| Nome | Tipo | Descrizione |
|---|---|---|
| sasURL | string (URI) | URL della firma di accesso condiviso con accesso in scrittura al contenitore Archiviazione BLOB di Azure. |
Una richiesta di caricamento dei log con esito positivo restituisce uno "stato": 200 seguito da un payload con lo schema seguente:
{
"status": "string",
"message": "string",
"correlationId": "GUID"
}
| Nome | Tipo | Descrizione |
|---|---|---|
| stato | string | Uno di NotStarted, RunningCompleted, Failed, o Unknown. |
| messaggio | string | Messaggio se si verifica un errore, stringa vuota in caso contrario. |
| correlationId | string | ID per eseguire una query sullo stato della richiesta di caricamento. |
Ad esempio:
La chiamata seguente carica le ultime 100 righe di log da tutti i moduli, in formato JSON compresso:
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"
}
'
La chiamata seguente carica le ultime 100 righe di log da edgeAgent e edgeHub con le ultime 1000 righe di log del modulo tempSensor in formato testo non compresso:
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"
}
'
Nella portale di Azure richiamare il metodo con il nome UploadModuleLogs del metodo e il payload JSON seguente dopo aver popolato sasURL con le informazioni:
{
"schemaVersion": "1.0",
"sasUrl": "<sasUrl>",
"items": [
{
"id": "edgeAgent",
"filter": {
"tail": 10
}
}
],
"encoding": "none",
"contentType": "text"
}
Caricare la diagnostica del bundle di supporto
Usare il metodo diretto UploadSupportBundle per aggregare e caricare un file ZIP dei log del modulo IoT Edge in un contenitore Archiviazione BLOB di Azure disponibile. Questo metodo diretto esegue il iotedge support-bundle comando nel dispositivo IoT Edge per ottenere i log.
Nota
Se si desidera caricare i log da un dispositivo dietro un dispositivo gateway, è necessario che i moduli di proxy API e archiviazione BLOB siano configurati nel dispositivo di livello superiore. Questi moduli instradano i log dal dispositivo di livello inferiore attraverso il dispositivo gateway all'archiviazione nel cloud.
Questo metodo accetta un payload JSON con lo schema seguente:
{
"schemaVersion": "1.0",
"sasUrl": "Full path to SAS url",
"since": "2d",
"until": "1d",
"edgeRuntimeOnly": false
}
| Nome | Tipo | Descrizione |
|---|---|---|
| schemaVersion | string | Impostare su 1.0 |
| sasURL | string (URI) | URL della firma di accesso condiviso con accesso in scrittura al contenitore Archiviazione BLOB di Azure |
| since | string | Restituisce solo i log da questa volta, come timestamp rfc3339, timestamp UNIX o durata (giorni (d) ore (h) (m)). Ad esempio, una durata per un giorno, 12 ore e 30 minuti può essere specificata come 1 giorno 12 ore 30 minuti o 1d 12h 30m. FACOLTATIVO |
| until | string | Restituisce solo i log prima dell'ora specificata, come timestamp rfc3339, timestamp UNIX o durata (giorni (d) ore (h) (m)). Ad esempio, una durata di 90 minuti può essere specificata come 90 minuti o 90 minuti. FACOLTATIVO |
| edgeRuntimeOnly | boolean | Se true, restituisce solo i log dall'agente Edge, dall'hub edge e dal daemon di sicurezza edge. Valore predefinito: false. FACOLTATIVO |
Importante
Il bundle di supporto di IoT Edge può contenere informazioni personali.
Una richiesta di caricamento dei log ha esito positivo restituisce uno "stato": 200 seguito da un payload con lo stesso schema della risposta UploadModuleLogs :
{
"status": "string",
"message": "string",
"correlationId": "GUID"
}
| Nome | Tipo | Descrizione |
|---|---|---|
| stato | string | Uno di NotStarted, RunningCompleted, Failed, o Unknown. |
| messaggio | string | Messaggio se si verifica un errore, stringa vuota in caso contrario. |
| correlationId | string | ID per eseguire una query sullo stato della richiesta di caricamento. |
Ad esempio:
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
}
'
Nella portale di Azure richiamare il metodo con il nome UploadSupportBundle del metodo e il payload JSON seguente dopo aver popolato sasURL con le informazioni:
{
"schemaVersion": "1.0",
"sasUrl": "Full path to SAS url",
"since": "2d",
"until": "1d",
"edgeRuntimeOnly": false
}
Ottenere lo stato della richiesta di caricamento
Usare il metodo diretto GetTaskStatus per eseguire una query sullo stato di una richiesta di caricamento dei log. Il payload della richiesta GetTaskStatus usa l'oggetto correlationId della richiesta di caricamento dei log per ottenere lo stato dell'attività. Viene correlationId restituito in risposta alla chiamata al metodo diretto UploadModuleLogs .
Questo metodo accetta un payload JSON con lo schema seguente:
{
"schemaVersion": "1.0",
"correlationId": "<GUID>"
}
Una richiesta di caricamento dei log ha esito positivo restituisce uno "stato": 200 seguito da un payload con lo stesso schema della risposta UploadModuleLogs :
{
"status": "string",
"message": "string",
"correlationId": "GUID"
}
| Nome | Tipo | Descrizione |
|---|---|---|
| stato | string | Uno di NotStarted, RunningCompleted, Failed'Cancelled', o Unknown. |
| messaggio | string | Messaggio se si verifica un errore, stringa vuota in caso contrario. |
| correlationId | string | ID per eseguire una query sullo stato della richiesta di caricamento. |
Ad esempio:
az iot hub invoke-module-method --method-name 'GetTaskStatus' -n <hub name> -d <device id> -m '$edgeAgent' --method-payload \
'
{
"schemaVersion": "1.0",
"correlationId": "<GUID>"
}
'
Nella portale di Azure richiamare il metodo con il nome GetTaskStatus del metodo e il payload JSON seguente dopo aver popolato il GUID con le informazioni:
{
"schemaVersion": "1.0",
"correlationId": "<GUID>"
}
Passaggi successivi
Proprietà del modulo gemello dell'agente IoT Edge e dell'hub IoT Edge