Resolver problemas com o dispositivo IoT Edge
Aplica-se a:
IoT Edge 1.5 IoT Edge 1.4
Importante
IoT Edge 1.5 LTS e IoT Edge 1.4 LTS são versões suportadas. O IoT Edge 1.4 LTS termina a vida útil em 12 de novembro de 2024. Se tiver uma versão anterior, consulte Atualizar IoT Edge.
Se você tiver problemas ao executar o Azure IoT Edge em seu ambiente, use este artigo como um guia para solução de problemas e diagnósticos.
Execute o comando 'check'
Sua primeira etapa ao solucionar problemas do IoT Edge deve ser usar o check comando, que executa uma coleção de testes de configuração e conectividade para problemas comuns. O check comando está disponível na versão 1.0.7 e posterior.
Nota
A ferramenta de solução de problemas não pode executar verificações de conectividade se o dispositivo IoT Edge estiver atrás de um servidor proxy.
Você pode executar o check comando da seguinte maneira ou incluir o --help sinalizador para ver uma lista completa de opções:
sudo iotedge check
A ferramenta de solução de problemas executa muitas verificações que são classificadas nestas três categorias:
- As verificações de configuração examinam detalhes que podem impedir que dispositivos IoT Edge se conectem à nuvem, incluindo problemas com o arquivo de configuração e o mecanismo de contêiner.
- As verificações de conexão verificam se o tempo de execução do IoT Edge pode acessar portas no dispositivo host e se todos os componentes do IoT Edge podem se conectar ao Hub IoT. Esse conjunto de verificações retornará erros se o dispositivo IoT Edge estiver atrás de um proxy.
- As verificações de preparação para produção procuram as práticas recomendadas de produção, como o estado dos certificados da autoridade de certificação (CA) do dispositivo e a configuração do arquivo de log do módulo.
A ferramenta de verificação do IoT Edge usa um contêiner para executar seus diagnósticos. A imagem de contêiner, mcr.microsoft.com/azureiotedge-diagnostics:latest, está disponível através do Microsoft Container Registry. Se você precisar executar uma verificação em um dispositivo sem acesso direto à internet, seus dispositivos precisarão acessar a imagem do contêiner.
Em um cenário usando dispositivos IoT Edge aninhados, você pode obter acesso à imagem de diagnóstico em dispositivos downstream roteando o pull de imagem pelos dispositivos pai.
sudo iotedge check --diagnostics-image-name <parent_device_fqdn_or_ip>:<port_for_api_proxy_module>/azureiotedge-diagnostics:1.2
Para obter informações sobre cada uma das verificações de diagnóstico executadas por essa ferramenta, incluindo o que fazer se você receber um erro ou aviso, consulte Verificações de solução de problemas do IoT Edge.
Reúna informações de depuração com o comando 'support-bundle'
Quando você precisa coletar logs de um dispositivo IoT Edge, a maneira mais conveniente é usar o support-bundle comando. Por padrão, esse comando coleta o módulo, o gerenciador de segurança do IoT Edge e os logs do mecanismo de contêiner, iotedge check a saída JSON e outras informações úteis de depuração. Ele os compacta em um único arquivo para facilitar o compartilhamento. O support-bundle comando está disponível na versão 1.0.9 e posterior.
Execute o support-bundle comando com o --since sinalizador para especificar quanto tempo do passado você deseja obter logs. Por exemplo 6h , obterá logs desde as últimas seis horas, 6d desde os últimos seis dias, 6m desde os últimos seis minutos e assim por diante. Inclua o --help sinalizador para ver uma lista completa de opções.
sudo iotedge support-bundle --since 6h
Por padrão, o support-bundle comando cria um arquivo zip chamado support_bundle.zip no diretório onde o comando é chamado. Use o sinalizador --output para especificar um caminho ou nome de arquivo diferente para a saída.
Para obter mais informações sobre o comando, consulte suas informações de ajuda.
iotedge support-bundle --help
Você também pode usar a chamada de método direto interna UploadSupportBundle para carregar a saída do comando support-bundle no Armazenamento de Blobs do Azure.
Aviso
A saída do comando pode conter nomes de support-bundle host, dispositivo e módulo, informações registradas por seus módulos, etc. Por favor, esteja ciente disso se compartilhar a saída em um fórum público.
Revisar métricas coletadas do tempo de execução
Os módulos de tempo de execução do IoT Edge produzem métricas para ajudá-lo a monitorar e entender a integridade de seus dispositivos IoT Edge. Adicione o módulo coletor de métricas às suas implantações para lidar com a coleta dessas métricas e enviá-las para a nuvem para facilitar o monitoramento.
Para obter mais informações, consulte Coletar e transportar métricas.
Verifique sua versão do IoT Edge
Se estiver a executar uma versão mais antiga do IoT Edge, uma atualização poderá resolver o problema. A iotedge check ferramenta verifica se o daemon de segurança do IoT Edge é a versão mais recente, mas não verifica as versões do hub do IoT Edge e dos módulos do agente. Para verificar a versão dos módulos de tempo de execução no seu dispositivo, use os comandos iotedge logs edgeAgent e iotedge logs edgeHub. O número da versão é declarado nos registos quando o módulo é iniciado.
Para obter instruções sobre como atualizar seu dispositivo, consulte Atualizar o daemon de segurança e o tempo de execução do IoT Edge.
Verificar a instalação do IoT Edge em seus dispositivos
Você pode verificar a instalação do IoT Edge em seus dispositivos monitorando o módulo gêmeo edgeAgent.
Para obter o módulo gêmeo edgeAgent mais recente, execute o seguinte comando do Azure Cloud Shell:
az iot hub module-twin show --device-id <edge_device_id> --module-id '$edgeAgent' --hub-name <iot_hub_name>
Esse comando produzirá todas as propriedades relatadas do edgeAgent. Aqui estão alguns úteis monitorar o status do dispositivo:
- status do tempo de execução
- tempo de início do tempo de execução
- tempo de execução da última saída
- contagem de reinicialização em tempo de execução
Verificar o status do gerenciador de segurança do IoT Edge e seus logs
O gerenciador de segurança do IoT Edge é responsável por operações como a inicialização do sistema IoT Edge na inicialização e no provisionamento de dispositivos. Se o IoT Edge não estiver iniciando, os logs do gerenciador de segurança podem fornecer informações úteis.
Veja o status dos serviços do sistema IoT Edge:
sudo iotedge system statusVeja os logs dos serviços do sistema IoT Edge:
sudo iotedge system logs -- -fHabilite os logs no nível de depuração para exibir logs mais detalhados dos serviços do sistema IoT Edge:
Habilite logs no nível de depuração.
sudo iotedge system set-log-level debug sudo iotedge system restartVolte para os logs de nível de informações padrão após a depuração.
sudo iotedge system set-log-level info sudo iotedge system restart
Verifique se há problemas nos logs de contêiner
Quando o daemon de segurança do IoT Edge estiver em execução, examine os logs dos contêineres para detetar problemas. Comece com seus contêineres implantados e, em seguida, examine os contêineres que compõem o tempo de execução do IoT Edge: edgeAgent e edgeHub. Os logs do agente do IoT Edge normalmente fornecem informações sobre o ciclo de vida de cada contêiner. Os logs do hub IoT Edge fornecem informações sobre mensagens e roteamento.
Você pode recuperar os logs de contêiner de vários lugares:
No dispositivo IoT Edge, execute o seguinte comando para exibir logs:
iotedge logs <container name>No portal do Azure, use a ferramenta interna de solução de problemas. Monitorar e solucionar problemas de dispositivos IoT Edge a partir do portal do Azure
Use o método direto UploadModuleLogs para carregar os logs de um módulo no Armazenamento de Blobs do Azure.
Limpar logs de contêiner
Por padrão, o mecanismo de contêiner Moby não define limites de tamanho de log de contêiner. Com o tempo, logs extensos podem levar o dispositivo a se encher de logs e ficar sem espaço em disco. Se grandes logs de contêiner estiverem afetando o desempenho do dispositivo IoT Edge, use o comando a seguir para forçar a remoção do contêiner junto com seus logs relacionados.
Se você ainda estiver solucionando problemas, aguarde até depois de inspecionar os logs de contêiner para executar esta etapa.
Aviso
Se você forçar a remoção do contêiner edgeHub enquanto ele tiver uma lista de pendências de mensagens não entregues e nenhum armazenamento de host configurado, as mensagens não entregues serão perdidas.
docker rm --force <container name>
Para cenários de manutenção e produção de logs contínuos, configure o driver de log padrão.
Exibir as mensagens que passam pelo hub IoT Edge
Você pode visualizar as mensagens que passam pelo hub do IoT Edge e coletar informações de logs detalhados dos contêineres de tempo de execução. Para ativar logs detalhados nesses contêineres, defina a RuntimeLogLevel variável de ambiente no manifesto de implantação.
Para exibir mensagens que passam pelo hub IoT Edge, defina a RuntimeLogLevel variável de ambiente como debug para o módulo edgeHub.
Os módulos edgeHub e edgeAgent têm essa variável de ambiente de log de tempo de execução, com o valor padrão definido como info. Esta variável de ambiente pode ter os seguintes valores:
- Fatal
- error
- aviso
- informação
- depurar
- verbose
Você também pode verificar as mensagens que estão sendo enviadas entre o Hub IoT e dispositivos IoT. Exiba essas mensagens usando a extensão do Hub IoT do Azure para Visual Studio Code. Para obter mais informações, consulte Ferramenta útil ao desenvolver com o Azure IoT.
Reiniciar contêineres
Depois de investigar os logs e mensagens para obter informações, você pode tentar reiniciar contêineres.
No dispositivo IoT Edge, use os seguintes comandos para reiniciar módulos:
iotedge restart <container name>
Reinicie os contêineres de tempo de execução do IoT Edge:
iotedge restart edgeAgent && iotedge restart edgeHub
Você também pode reiniciar módulos remotamente a partir do portal do Azure. Para obter mais informações, consulte Monitorar e solucionar problemas de dispositivos IoT Edge no portal do Azure.
Verifique as regras de configuração do firewall e da porta
O Azure IoT Edge permite a comunicação de um servidor local com a nuvem do Azure usando protocolos de Hub IoT suportados, consulte escolhendo um protocolo de comunicação. Para maior segurança, os canais de comunicação entre o Azure IoT Edge e o Hub IoT do Azure são sempre configurados para serem de saída. Essa configuração é baseada no padrão de Comunicação Assistida por Serviços, que minimiza a superfície de ataque para uma entidade mal-intencionada explorar. A comunicação de entrada só é necessária para cenários específicos em que o Hub IoT do Azure precisa enviar mensagens por push para o dispositivo Azure IoT Edge. As mensagens da nuvem para o dispositivo são protegidas usando canais TLS seguros e podem ser protegidas usando certificados X.509 e módulos de dispositivo TPM. O Azure IoT Edge Security Manager controla como essa comunicação pode ser estabelecida, consulte IoT Edge Security Manager.
Embora o IoT Edge forneça configuração aprimorada para proteger o tempo de execução e os módulos implantados do Azure IoT Edge, ele ainda depende da máquina subjacente e da configuração de rede. Portanto, é imperativo garantir que as regras adequadas de rede e firewall sejam configuradas para uma comunicação segura de borda para nuvem. A tabela a seguir pode ser usada como uma diretriz ao configurar regras de firewall para os servidores subjacentes onde o tempo de execução do Azure IoT Edge está hospedado:
| Protocolo | Porta | Entrada | Saída | Orientação |
|---|---|---|---|---|
| MQTT | 8883 | BLOQUEADO (padrão) | BLOQUEADO (padrão) |
|
| AMQP | 5671 | BLOQUEADO (padrão) | OPEN (padrão) |
|
| HTTPS | 443 | BLOQUEADO (padrão) | OPEN (padrão) |
|
Último recurso: parar e recriar todos os contentores
Às vezes, um sistema pode exigir modificações especiais significativas para trabalhar com restrições de rede ou sistema operacional existentes. Por exemplo, um sistema pode exigir uma montagem de disco de dados diferente e configurações de proxy. Se você tentou todas as etapas anteriores e ainda obtém falhas de contêiner, os caches do sistema docker ou as configurações de rede persistentes podem não estar atualizados com a reconfiguração mais recente. Neste caso, a opção de último recurso é usar docker prune um começo limpo do zero.
O comando a seguir interrompe o sistema IoT Edge (e, portanto, todos os contêineres), usa a opção "all" e "volume" para docker prune remover todos os contêineres e volumes. Revise o aviso que o comando emite e confirme quando y estiver 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]
Inicie o sistema novamente. Para estar seguro, aplique qualquer configuração potencialmente restante e inicie o sistema com um comando.
sudo iotedge config apply
Aguarde alguns minutos e verifique novamente.
sudo iotedge list
Próximos passos
Encontrou um erro na plataforma do IoT Edge? Envie uma questão para que possamos continuar a melhorar.
Se você tiver mais perguntas, crie uma solicitação de suporte para obter ajuda.