Risolvere i problemi del dispositivo 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.
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:
sudo 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.
In uno scenario che usa dispositivi IoT Edge annidati, è possibile accedere all'immagine di diagnostica nei dispositivi downstream eseguendo il pull dell'immagine nei dispositivi padre.
sudo iotedge check --diagnostics-image-name <parent_device_fqdn_or_ip>:<port_for_api_proxy_module>/azureiotedge-diagnostics:1.2
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 , ottiene 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.
sudo 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.
Avviso
L'output del support-bundle comando può contenere nomi host, dispositivi e moduli, informazioni registrate dai moduli e così via. Tenere presente questo problema 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 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 restituisce tutte le proprietà segnalate da 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.
Visualizzare lo stato dei servizi di sistema IoT Edge:
sudo iotedge system statusVisualizzare i log dei servizi di sistema IoT Edge:
sudo iotedge system logs -- -fAbilitare i log a livello di debug per visualizzare log più dettagliati dei servizi di sistema IoT Edge:
Abilitare i log a livello di debug.
sudo iotedge system set-log-level debug sudo iotedge system restartTornare ai log predefiniti a livello di informazioni dopo il debug.
sudo iotedge system set-log-level info sudo iotedge system restart
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 i limiti delle dimensioni del log dei contenitori. Nel corso del tempo, i log estesi possono 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.
Avviso
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 dettagliati dai contenitori di runtime. Per attivare i log dettagliati in questi contenitori, impostare la RuntimeLogLevel variabile di ambiente nel manifesto della distribuzione.
Per visualizzare i messaggi che passano attraverso l'hub IoT Edge, impostare la RuntimeLogLevel variabile di ambiente su debug per il modulo edgeHub.
Entrambi i moduli edgeHub e edgeAgent hanno questa variabile di ambiente del log di runtime, con il valore predefinito impostato su info. Questa variabile di ambiente può accettare i valori seguenti:
- fatal
- Errore
- warning
- info
- debug
- verbose
È 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. Per altre informazioni, 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 siano configurate regole di rete e firewall appropriate per la comunicazione tra dispositivi perimetrali sicuri e 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:
| Protocollo | Port | In ingresso | In uscita | Indicazioni |
|---|---|---|---|---|
| MQTT | 8883 | BLOCCATO (impostazione predefinita) | BLOCCATO (impostazione predefinita) |
|
| AMQP | 5671 | BLOCCATO (impostazione predefinita) | APERTO (impostazione predefinita) |
|
| HTTPS | 443 | BLOCCATO (impostazione predefinita) | APERTO (impostazione predefinita) |
|
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 del contenitore, le cache di sistema Docker o le impostazioni di rete persistenti potrebbero non essere 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 seguente 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.