Condividi tramite

Risolvi i problemi del tuo dispositivo IoT Edge

Si applica a:icona di conferma IoT Edge 1.1

Importante

IoT Edge 1.1 data di fine del supporto è stata il 13 dicembre 2022. Controlla il ciclo di vita dei prodotti Microsoft per ottenere informazioni sul modo in cui viene supportato questo prodotto, servizio, tecnologia o API. Per altre informazioni sull'aggiornamento alla versione più recente di IoT Edge, vedere Aggiornare IoT Edge.

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.

Nota

Lo strumento di risoluzione dei problemi non può eseguire controlli di connettività se il dispositivo IoT Edge si trova dietro un server proxy.

È 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 il Registro di Contenitori di 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 comando support-bundle con l'opzione --since per specificare per quanto tempo dal passato si desidera ottenere i log. Ad esempio, 6h otterrà i log dalle ultime sei ore, 6d dagli ultimi sei giorni, 6m dopo gli 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 ulteriori informazioni sul comando, visualizzare le informazioni di aiuto.

iotedge support-bundle --help

È anche possibile usare il metodo predefinito UploadSupportBundle per caricare l'output del comando support-bundle in Azure Blob Storage.

Avvertimento

L'output del comando support-bundle può contenere nomi di host, dispositivi e moduli, informazioni registrate dai tuoi moduli, ecc. È importante tenerne conto se si condivide l'output in un forum pubblico.

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 strumento iotedge check 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 da edgeAgent. Ecco alcuni strumenti utili per monitorare lo stato del dispositivo.

  • stato di runtime
  • ora di inizio del runtime
  • Ultima ora di uscita del runtime
  • conteggio dei 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:

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.

Avvertimento

Se si forza la rimozione del contenitore edgeHub mentre è presente un backlog dei messaggi non recapitati e nessuna risorsa di archiviazione host configurata, i messaggi non recapitati andranno persi.

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 verbosi dei container di runtime. Per attivare i log dettagliati in 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 sarà 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

Avvertimento

I file YAML non possono contenere tabulazioni per l'indentazione. Usare invece 2 spazi. Gli elementi di primo livello non possono avere spazi vuoti iniziali.

Salvare il file e riavviare il gestore della sicurezza di 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 i protocolli dell'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.

Anche se IoT Edge offre una configurazione avanzata per la protezione del runtime di Azure IoT Edge e dei moduli distribuiti, dipende comunque dalla configurazione di rete e del computer sottostante. 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 si configurano le regole del firewall per i server sottostanti dove è ospitato il runtime di Azure IoT Edge.

Protocollo Porto In arrivo In uscita Indicazioni
MQTT 8883 BLOCCATO (impostazione predefinita) BLOCCATO (impostazione predefinita)
  • Configurare l'uscita (Outbound) affinché sia Aperta quando si usa MQTT come protocollo di comunicazione.
  • 1883 per MQTT non è supportato da IoT Edge.
  • Le connessioni in ingresso devono essere bloccate.
AMQP 5671 BLOCCATO (impostazione predefinita) APERTO (impostazione predefinita)
  • Protocollo di comunicazione predefinito per IoT Edge.
  • Deve essere configurato per essere Aperto se Azure IoT Edge non è configurato per altri protocolli supportati o AMQP è il protocollo di comunicazione desiderato.
  • 5672 per AMQP non è supportato da IoT Edge.
  • Bloccare questa porta quando Azure IoT Edge usa un protocollo supportato dall'hub IoT diverso.
  • Le connessioni in ingresso devono essere bloccate.
HTTPS 443 BLOCCATO (impostazione predefinita) APERTO (impostazione predefinita)
  • Configurare l'uscita in modo che sia aperta sulla porta 443 per il provisioning di IoT Edge. Questa configurazione è necessaria quando si usano script manuali o il servizio Device Provisioning di Azure IoT.
  • La connessione in ingresso deve essere aperta solo per scenari specifici:
    • Se si dispone di un gateway trasparente con dispositivi downstream che possono inviare richieste di metodo. In questo caso, la porta 443 non deve essere aperta alle reti esterne per connettersi a IoTHub o fornire servizi IoTHub tramite Azure IoT Edge. Pertanto, la regola in ingresso potrebbe essere limitata per consentire solo il traffico in entrata dalla rete interna.
    • Per scenari da cliente a dispositivo (C2D).
  • 80 per HTTP non è supportato da IoT Edge.
  • Se non è possibile configurare protocolli non HTTP (ad esempio, AMQP o MQTT) nell'organizzazione; i messaggi possono essere inviati tramite WebSocket. In tal caso, la porta 443 verrà usata per la comunicazione WebSocket.

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 per ripartire da zero.

Il comando seguente arresta il sistema IoT Edge (e quindi tutti i contenitori), utilizzando per docker prune le opzioni "all" e "volume" per 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

Pensi di aver trovato un bug nella piattaforma IoT Edge? Inviare un problema in modo da poter migliorare l'esperienza.

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

  • Last updated on