Risolvere i problemi del dispositivo IoT Edge

Si applica a: IoT Edge 1.1

Se si verificano problemi durante l'esecuzione di Azure IoT Edge nell'ambiente in uso, usare questo articolo come guida per la risoluzione dei problemi e la diagnostica.

Eseguire il comando 'check'

Il primo passaggio per la risoluzione dei problemi di IoT Edge consiste nell'usare il check comando , che esegue una raccolta di test di configurazione e connettività per problemi comuni. Il check comando è disponibile nella versione 1.0.7 e successive.

È possibile eseguire il check comando come indicato di seguito o includere il --help flag per visualizzare un elenco completo di opzioni:

In Linux:

sudo iotedge check

In Windows:

iotedge check

Lo strumento di risoluzione dei problemi esegue molti controlli ordinati in queste tre categorie:

• I controlli di configurazione esaminano i dettagli che potrebbero impedire ai dispositivi IoT Edge di connettersi al cloud, inclusi i problemi relativi al file di configurazione e al motore del contenitore.
• I controlli di connessione verificano che il runtime di IoT Edge possa accedere alle porte nel dispositivo host e che tutti i componenti di IoT Edge possano connettersi alla hub IoT. Questo set di controlli restituisce errori se il dispositivo IoT Edge si trova dietro un proxy.
• I controlli di conformità della produzione cercano le procedure consigliate per la produzione, ad esempio lo stato dei certificati dell'autorità di certificazione (CA) del dispositivo e la configurazione del file di log del modulo.

Lo strumento di controllo di IoT Edge usa un contenitore per eseguire la diagnostica. L'immagine del contenitore, mcr.microsoft.com/azureiotedge-diagnostics:latest, è disponibile tramite registro Contenitori Microsoft. Se è necessario eseguire un controllo su un dispositivo senza accesso diretto a Internet, i dispositivi dovranno accedere all'immagine del contenitore.

Per informazioni su ognuno dei controlli di diagnostica eseguiti da questo strumento, incluse le operazioni da eseguire se viene visualizzato un errore o un avviso, vedere Controlli di risoluzione dei problemi di IoT Edge.

Raccogliere informazioni di debug con il comando "support-bundle"

Quando è necessario raccogliere i log da un dispositivo IoT Edge, il modo più pratico consiste nell'usare il support-bundle comando . Per impostazione predefinita, questo comando raccoglie il modulo, lo strumento di gestione della sicurezza di IoT Edge e i log del motore di contenitori, l'output iotedge check JSON e altre informazioni di debug utili. Li comprime in un singolo file per semplificare la condivisione. Il support-bundle comando è disponibile nella versione 1.0.9 e successive.

Eseguire il support-bundle comando con il --since flag per specificare per quanto tempo dal passato si vogliono ottenere i log. Ad esempio 6h , si otterranno i log dalle ultime sei ore, 6d dagli ultimi sei giorni, 6m dagli ultimi sei minuti e così via. Includere il --help flag per visualizzare un elenco completo di opzioni.

In Linux:

sudo iotedge support-bundle --since 6h

In Windows:

iotedge support-bundle --since 6h

Per impostazione predefinita, il support-bundle comando crea un file ZIP denominato support_bundle.zip nella directory in cui viene chiamato il comando. Usare il flag --output per specificare un percorso o un nome di file diverso per l'output.

Per altre informazioni sul comando, visualizzarne le informazioni della Guida.

iotedge support-bundle --help

È anche possibile usare il metodo diretto predefinito UploadSupportBundle per caricare l'output del comando support-bundle in Archiviazione BLOB di Azure.

Esaminare le metriche raccolte dal runtime

I moduli di runtime di IoT Edge producono metriche che consentono di monitorare e comprendere l'integrità dei dispositivi IoT Edge. Aggiungere il modulo metrics-collector alle distribuzioni per gestire la raccolta di queste metriche e l'invio al cloud per semplificare il monitoraggio.

Per altre informazioni, vedere Raccogliere e trasportare le metriche.

Controllare la versione di IoT Edge

Se si sta eseguendo una versione precedente di IoT Edge, l'aggiornamento può risolvere il problema. Lo iotedge check strumento verifica che il daemon di sicurezza di IoT Edge sia la versione più recente, ma non controlla le versioni dei moduli dell'hub di IoT Edge e dell'agente. Per controllare la versione dei moduli di runtime nel dispositivo, usare i iotedge logs edgeAgent comandi e iotedge logs edgeHub. Il numero di versione è dichiarato nei log all'avvio del modulo.

Per istruzioni su come aggiornare il dispositivo, vedere Aggiornare il daemon di sicurezza e il runtime di IoT Edge.

Verificare l'installazione di IoT Edge nei dispositivi

È possibile verificare l'installazione di IoT Edge nei dispositivi monitorando il modulo gemello edgeAgent.

Per ottenere il modulo gemello edgeAgent più recente, eseguire il comando seguente da Azure Cloud Shell:

az iot hub module-twin show --device-id <edge_device_id> --module-id '$edgeAgent' --hub-name <iot_hub_name>

Questo comando restituirà tutte le proprietà segnalate di edgeAgent. Ecco alcuni utili che monitorano lo stato del dispositivo:

• stato di runtime
• ora di inizio del runtime
• Ora dell'ultima uscita del runtime
• numero di riavvii di runtime

Controllare lo stato del gestore della sicurezza di IoT Edge e dei relativi log

Il responsabile della sicurezza di IoT Edge è responsabile di operazioni come l'inizializzazione del sistema IoT Edge all'avvio e al provisioning dei dispositivi. Se IoT Edge non viene avviato, i log di Gestione sicurezza possono fornire informazioni utili.

In Linux:

• Visualizzare lo stato del gestore della sicurezza di IoT Edge:

  sudo systemctl status iotedge
  

• Visualizzare i log del gestore della sicurezza di IoT Edge:

  sudo journalctl -u iotedge -f
  

• Visualizzare log più dettagliati del gestore della sicurezza di IoT Edge:

  1. Modificare le impostazioni del daemon IoT Edge:

     sudo systemctl edit iotedge.service
     

  2. Aggiornare le righe seguenti:

     [Service]
     Environment=IOTEDGE_LOG=debug
     

  3. Riavviare il daemon di sicurezza di IoT Edge:

     sudo systemctl cat iotedge.service
     sudo systemctl daemon-reload
     sudo systemctl restart iotedge
     

In Windows:

• Visualizzare lo stato del gestore della sicurezza di IoT Edge:

  Get-Service iotedge
  

• Visualizzare i log del gestore della sicurezza di IoT Edge:

  . {Invoke-WebRequest -useb aka.ms/iotedge-win} | Invoke-Expression; Get-IoTEdgeLog
  

• Visualizzare solo gli ultimi 5 minuti dei log di Gestione sicurezza di IoT Edge:

  . {Invoke-WebRequest -useb aka.ms/iotedge-win} | Invoke-Expression; Get-IoTEdgeLog -StartTime ([datetime]::Now.AddMinutes(-5))
  

• Visualizzare log più dettagliati del gestore della sicurezza di IoT Edge:

  1. Aggiungere una variabile di ambiente a livello di sistema:

     [Environment]::SetEnvironmentVariable("IOTEDGE_LOG", "debug", [EnvironmentVariableTarget]::Machine)
     

  2. Riavviare il daemon di sicurezza di IoT Edge:

     Restart-Service iotedge
     

Controllare i log dei contenitori per eventuali problemi

Quando il daemon di sicurezza di IoT Edge è in esecuzione, esaminare i log dei contenitori per rilevare i problemi. Iniziare con i contenitori distribuiti, quindi esaminare i contenitori che costituiscono il runtime di IoT Edge: edgeAgent e edgeHub. I log dell'agente IoT Edge in genere forniscono informazioni sul ciclo di vita di ogni contenitore. I log dell'hub IoT Edge forniscono informazioni sulla messaggistica e sul routing.

È possibile recuperare i log dei contenitori da diverse posizioni:

• Nel dispositivo IoT Edge eseguire il comando seguente per visualizzare i log:

  iotedge logs <container name>
  

• Nella portale di Azure usare lo strumento di risoluzione dei problemi predefinito. Monitorare e risolvere i problemi dei dispositivi IoT Edge dal portale di Azure

• Usare il metodo diretto UploadModuleLogs per caricare i log di un modulo in Archiviazione BLOB di Azure.

Pulire i log dei contenitori

Per impostazione predefinita, il motore del contenitore Moby non imposta limiti di dimensioni per i log dei contenitori. Nel corso del tempo questo può causare il riempimento del dispositivo con i log e l'esaurimento dello spazio su disco. Se i log dei contenitori di grandi dimensioni influiscono sulle prestazioni del dispositivo IoT Edge, usare il comando seguente per forzare la rimozione del contenitore insieme ai log correlati.

Se si sta ancora eseguendo la risoluzione dei problemi, attendere fino a quando non sono stati esaminati i log del contenitore per eseguire questo passaggio.

docker rm --force <container name>

Per gli scenari di manutenzione e produzione dei log in corso, configurare il driver di registrazione predefinito.

Visualizzare i messaggi che passano attraverso l'hub IoT Edge

È possibile visualizzare i messaggi che passano attraverso l'hub IoT Edge e raccogliere informazioni dettagliate dai log dettagliati dai contenitori di runtime. Per attivare i log dettagliati su questi contenitori, impostare RuntimeLogLevel nel file di configurazione yaml. Per aprire il file:

In Linux:

sudo nano /etc/iotedge/config.yaml

In Windows:

notepad C:\ProgramData\iotedge\config.yaml

Per impostazione predefinita, l'elemento agent avrà un aspetto simile all'esempio seguente:

agent:
  name: edgeAgent
  type: docker
  env: {}
  config:
    image: mcr.microsoft.com/azureiotedge-agent:1.1
    auth: {}

Sostituire env: {} con:

env:
  RuntimeLogLevel: debug

Salvare il file e riavviare il gestore sicurezza IoT Edge.

È anche possibile controllare i messaggi inviati tra i dispositivi hub IoT e IoT. Visualizzare questi messaggi usando l'estensione hub IoT di Azure per Visual Studio Code. Per altre informazioni, vedere Handy tool when you develop with Azure IoT (Strumento utile quando si sviluppa con Azure IoT).

Riavviare i contenitori

Dopo aver esaminato i log e i messaggi per informazioni, è possibile provare a riavviare i contenitori.

Nel dispositivo IoT Edge usare i comandi seguenti per riavviare i moduli:

iotedge restart <container name>

Riavviare i contenitori di runtime di IoT Edge:

iotedge restart edgeAgent && iotedge restart edgeHub

È anche possibile riavviare i moduli in modalità remota dal portale di Azure. Per altre informazioni, vedere Monitorare e risolvere i problemi dei dispositivi IoT Edge dal portale di Azure.

Controllare le regole di configurazione del firewall e della porta

Azure IoT Edge consente la comunicazione da un server locale al cloud di Azure usando protocolli di hub IoT supportati, vedere Scelta di un protocollo di comunicazione. Per una maggiore sicurezza, i canali di comunicazione tra Azure IoT Edge e hub IoT di Azure sono sempre configurati per essere in uscita. Questa configurazione si basa sul modello di comunicazione assistita dei servizi, che consente di ridurre la superficie di attacco esplorabile da un'entità dannosa. La comunicazione in ingresso è necessaria solo per scenari specifici in cui hub IoT di Azure deve eseguire il push dei messaggi nel dispositivo Azure IoT Edge. I messaggi da cloud a dispositivo sono protetti tramite canali sicuri TLS e possono essere protetti ulteriormente tramite certificati X.509 e moduli di dispositivo TPM. Il gestore sicurezza di Azure IoT Edge stabilisce come attivare la comunicazione, vedere Gestore sicurezza di Azure IoT Edge.

Sebbene IoT Edge offra una configurazione avanzata per la protezione del runtime e dei moduli distribuiti di Azure IoT Edge, dipende comunque dal computer e dalla configurazione di rete sottostanti. Di conseguenza, è fondamentale assicurarsi che le regole di rete e firewall appropriate siano configurate per la comunicazione da rete perimetrale sicura al cloud. La tabella seguente può essere usata come linea guida quando le regole del firewall di configurazione per i server sottostanti in cui è ospitato il runtime di Azure IoT Edge:

Ultima risorsa: arrestare e ricreare tutti i contenitori

In alcuni casi, un sistema potrebbe richiedere modifiche speciali significative per funzionare con vincoli di rete o del sistema operativo esistenti. Ad esempio, un sistema potrebbe richiedere un montaggio del disco dati e impostazioni proxy diverse. Se si sono provato tutti i passaggi precedenti e si verificano ancora errori di contenitore, è possibile che in qualche posizione le cache di sistema Docker o le impostazioni di rete persistenti non siano aggiornate con la riconfigurazione più recente. In questo caso, l'ultima opzione di risorsa consiste nell'usare docker prune un inizio pulito da zero.

Il comando che segue arresta il sistema IoT Edge (e quindi tutti i contenitori), usa l'opzione "all" e "volume" per docker prune rimuovere tutti i contenitori e i volumi. Esaminare l'avviso che il comando emette e conferma con y quando è pronto.

sudo iotedge system stop
docker system prune --all --volumes

WARNING! This will remove:
  - all stopped containers
  - all networks not used by at least one container
  - all volumes not used by at least one container
  - all images without at least one container associated to them
  - all build cache

Are you sure you want to continue? [y/N]

Avviare di nuovo il sistema. Per essere sicuri, applicare qualsiasi configurazione potenzialmente rimanente e avviare il sistema con un solo comando.

sudo iotedge config apply

Attendere alcuni minuti e riprovare.

sudo iotedge list

Passaggi successivi

Se si ritiene di aver rilevato un bug nella piattaforma di IoT Edge, Inviare un problema in modo da poter migliorare l'esperienza.

In caso di altre domande, creare una Richiesta di supporto per assistenza.