Condividi tramite


Recuperare i log dalle distribuzioni IoT Edge

Si applica a:Segno di spunta IoT Edge 1.5 IoT Edge 1.5 Segno di spunta IoT Edge 1.4 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.

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"
    }

Screenshot di come richiamare il metodo diretto GetModuleLogs nella portale di Azure.

È 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"
    }

Screenshot di come richiamare il metodo diretto UploadModuleLogs nel portale di Azure.

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
    }

Screenshot che mostra come richiamare il metodo diretto UploadSupportBundle nel portale di Azure.

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>"
    }

Screenshot che mostra come richiamare il metodo diretto GetTaskStatus in portale di Azure.

Passaggi successivi

Proprietà del modulo gemello dell'agente IoT Edge e dell'hub IoT Edge