Solucionar problemas em dispositivos IoT Edge
Aplica-se a: 
IoT Edge 1.1
Importante
IoT Edge 1.1 a data de término do suporte foi 13 de dezembro de 2022. Confira o Ciclo de Vida do Produto da Microsoft para obter informações sobre o suporte deste produto, serviço, tecnologia ou API. Para obter mais informações sobre como atualizar para a versão mais recente do IoT Edge, consulte Atualizar o IoT Edge.
Se você tiver problemas com o Azure IoT Edge no seu ambiente, use este artigo como um guia para resolver esses problemas.
Executar o comando 'check'
Sua primeira etapa ao solucionar problemas do IoT Edge deve ser usar o comando check, que executa uma coleção de testes de configuração e conectividade para problemas comuns. O comando check está disponível na versão 1.0.7 e posterior.
Observação
A ferramenta de solução de problemas não pode executar verificações de conectividade se o dispositivo de IoT Edge estiver protegido por um servidor proxy.
Você pode executar o comando check da seguinte maneira ou incluir o --help sinalizador para ver uma lista completa de opções:
No Linux:
sudo iotedge check
No Windows:
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 os detalhes que podem impedir que os dispositivos do IoT Edge se conectem à nuvem, incluindo problemas com o arquivo de configuração e o mecanismo de contêiner.
- Verificações de conexão Verifique se o tempo de execução do IoT Edge permite acessar portas no dispositivo de host e se todos os componentes de IoT Edge podem se conectar ao Hub IoT. Esse conjunto de verificações retornará erros se o dispositivo IoT Edge estiver protegido por um proxy.
- As verificações de preparação de produção procuram boas práticas de produção recomendadas, como o estado de certificados de autoridade de certificação de dispositivo (CA) e configuração de arquivo de log de módulo.
A ferramenta de verificação de IoT Edge usa um contêiner para executar seu diagnóstico. A imagem de contêiner, mcr.microsoft.com/azureiotedge-diagnostics:latest, está disponível por meio 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 de contêiner.
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 solucionar problemas de verificações do IoT Edge.
Coletar informações de depuração com o comando 'support-bundle'
Quando você precisar coletar logs de um dispositivo do IoT Edge, a maneira mais fácil é usar o comandosupport-bundle. Por padrão, esse comando coleta o módulo, Gerenciador de Segurança do IoT Edge e logs do mecanismo de contêiner, iotedge check saída JSON e outras informações de depuração úteis. Ele os compacta em um único arquivo para facilitar o compartilhamento. O comando support-bundle está disponível na versão 1.0.9 e posterior.
Execute o comando support-bundlecom o sinalizador --since para especificar por quanto tempo do passado você deseja obter logs. Por exemplo, 6h obterá logs durante as últimas seis horas, 6d durante os últimos seis dias, 6m durante os últimos seis minutos e assim por diante. Inclua o sinalizador --help para ver uma lista completa de opções.
No Linux:
sudo iotedge support-bundle --since 6h
No Windows:
iotedge support-bundle --since 6h
Por padrão, o comando support-bundle cria um arquivo zip chamado support_bundle.zip no diretório em que 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, veja as informações de ajuda dele.
iotedge support-bundle --help
Você também pode usar uma chamada de método direto interna UploadSupportBundle para carregar a saída do comando support-bundle para o Armazenamento de Blobs do Azure.
Aviso
A saída do comando support-bundle pode conter nomes de host, dispositivo e módulo, informações registradas por seus módulos etc. Lembre-se disso se estiver compartilhando a saída em um fórum público.
Examinar as métricas coletadas do runtime
Os módulos de runtime do IoT Edge produzem métricas que ajudam a monitorar e entender a integridade dos dispositivos do IoT Edge. Adicione o módulo coletor de métricas às implantações para processar a coleta dessas métricas e enviá-las à nuvem a fim de facilitar o monitoramento.
Para obter mais informações, confira Coletar e transportar métricas.
Verifique a versão do IoT Edge
A atualização poderá resolver o problema se você estiver executando uma versão mais antiga do IoT Edge. A ferramenta iotedge check 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 os módulos de agente. Para verificar a versão dos módulos de runtime do dispositivo, use os comandos iotedge logs edgeAgent e iotedge logs edgeHub. O número de versão é informado nos logs na inicialização do módulo.
Para obter instruções sobre como atualizar seu dispositivo, consulte Atualizar o daemon de segurança do IoT Edge e o runtime.
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 no Azure Cloud Shell:
az iot hub module-twin show --device-id <edge_device_id> --module-id '$edgeAgent' --hub-name <iot_hub_name>
Esse comando vai gerar como saída todas as propriedades relatadas do edgeAgent. Aqui estão alguns comandos úteis que monitoram o status do dispositivo:
- runtime status
- runtime start time
- runtime last exit time
- runtime restart count
Verifique 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 inicializar o 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 poderão fornecer informações úteis.
No Linux:
Para ver o status do Gerenciador de Segurança do IoT Edge:
sudo systemctl status iotedgePara ver os logs do Gerenciador de Segurança do IoT Edge:
sudo journalctl -u iotedge -fPara ver mais detalhadamente os logs do Gerenciador de Segurança do IoT Edge:
Edite as configurações de daemon do IoT Edge:
sudo systemctl edit iotedge.serviceAtualize as seguintes linhas:
[Service] Environment=IOTEDGE_LOG=debugReinicie o daemon de segurança do IoT Edge:
sudo systemctl cat iotedge.service sudo systemctl daemon-reload sudo systemctl restart iotedge
No Windows:
Para ver o status do Gerenciador de Segurança do IoT Edge:
Get-Service iotedgePara ver os logs do Gerenciador de Segurança do IoT Edge:
. {Invoke-WebRequest -useb aka.ms/iotedge-win} | Invoke-Expression; Get-IoTEdgeLogPara ver somente os últimos 5 minutos dos logs do Gerenciador de Segurança do IoT Edge:
. {Invoke-WebRequest -useb aka.ms/iotedge-win} | Invoke-Expression; Get-IoTEdgeLog -StartTime ([datetime]::Now.AddMinutes(-5))Para ver mais detalhadamente os logs do Gerenciador de Segurança do IoT Edge:
Registrar uma variável de ambiente do sistema:
[Environment]::SetEnvironmentVariable("IOTEDGE_LOG", "debug", [EnvironmentVariableTarget]::Machine)Reinicie o daemon de segurança do IoT Edge:
Restart-Service iotedge
Verifique os logs de contêiner de problemas
Depois que o daemon de segurança de IoT Edge está em execução, examine os logs de contêineres para detectar problemas. Comece com os contêineres implantados, examine os contêineres que compõem o runtime do IoT Edge: Agente do Edge e Hub do Edge. Os logs de agente do IoT Edge normalmente fornecem informações sobre o ciclo de vida de cada contêiner. Os logs do hub do IoT Edge fornecem informações sobre mensagens e roteamento.
Você pode recuperar os logs de contêiner de vários locais:
No dispositivo IoT Edge, execute o seguinte comando para ver os logs:
iotedge logs <container name>No portal do Azure, use a ferramenta de solução de problemas interna. Monitorar e solucionar problemas de dispositivos do IoT Edge usando o 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, isso pode levar ao dispositivo que está se enchendo com os logs e ficando sem espaço em disco. Se logs de contêiner grandes estão afetando o desempenho do dispositivo IoT Edge, use o comando a seguir para forçar a remoção do contêiner e seus logs relacionados.
Se você ainda estiver solucionando problemas, espere e inspecione os logs de contêiner antes de realizar esta etapa.
Aviso
Se forçar a remoção do contêiner edgeHub enquanto ele tiver uma lista de pendências de mensagem não entregue e nenhum armazenamento de host definido, 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.
Consulte as mensagens enviadas por meio do hub do IoT Edge
É possível exibir as mensagens que passam pelo hub do IoT Edge e obter insights de logs detalhados dos contêineres de runtime. Para ativar os logs detalhados nesses contêineres, defina RuntimeLogLevel em seu arquivo de configuração yaml. Para abrir o arquivo:
No Linux:
sudo nano /etc/iotedge/config.yaml
No Windows:
notepad C:\ProgramData\iotedge\config.yaml
Por padrão, o elemento agent será parecido com o seguinte exemplo:
agent:
name: edgeAgent
type: docker
env: {}
config:
image: mcr.microsoft.com/azureiotedge-agent:1.1
auth: {}
Substitua env: {} por:
env:
RuntimeLogLevel: debug
Aviso
Arquivos YAML não podem conter guias como recuo. Use 2 espaços no lugar. Os itens de nível superior não podem ter um espaço em branco à esquerda.
Salve o arquivo e reinicie o gerenciador de segurança do IoT Edge.
Você também pode verificar as mensagens que estão sendo enviadas entre os dispositivos do Hub IoT e do IoT Edge. Veja essas mensagens usando a extensão do Hub IoT do Azure do Visual Studio Code. Para obter mais informações, confira Handy tool when you develop with Azure IoT (Ferramenta útil ao desenvolver com o Azure IoT).
Reinicie os contêineres
Depois de investigar os logs e as mensagens para obter informações, você pode tentar reiniciar os contêineres.
No dispositivo IoT Edge, use os seguintes comandos para reiniciar os módulos:
iotedge restart <container name>
Reiniciar contêineres de runtime do IoT Edge:
iotedge restart edgeAgent && iotedge restart edgeHub
Você também pode reiniciar os módulos remotamente usando o portal do Azure. Para saber mais, 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 os protocolos do Hub IoT com suporte. Confira 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 sempre são configurados para ser de Saída. Essa configuração se baseia no padrão de comunicação assistida por serviços, que minimiza a superfície de ataque a ser explorada por entidades mal-intencionadas. 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. Mensagens da nuvem para dispositivo são protegidas usando canais TLS seguros e podem ser ainda mais protegidas usando certificados X.509 e módulos de dispositivo do TPM. O Gerenciador de Segurança do Azure IoT Edge rege como essa comunicação pode ser estabelecida. Confira Gerenciador de Segurança do IoT Edge.
Embora o IoT Edge forneça configuração avançada para proteger o runtime do Azure IoT Edge e os módulos implantados, ele ainda depende da configuração do computador e da rede subjacente. Portanto, é fundamental garantir que regras de firewall e de rede apropriadas sejam definidas para obter uma comunicação segura da borda para a nuvem. Os seguinte pode ser usado como uma diretriz para configurar regras de firewall para os servidores subjacentes em que o runtime do Azure IoT Edge está hospedado:
| Protocolo | Porta | Entrada | Saída | Diretrizes |
|---|---|---|---|---|
| MQTT | 8883 | BLOQUEADO (padrão) | BLOQUEADO (padrão) |
|
| AMQP | 5671 | BLOQUEADO (padrão) | ABERTO (padrão) |
|
| HTTPS | 443 | BLOQUEADO (padrão) | ABERTO (padrão) |
|
Último recurso: parar e recriar todos os contêineres
À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 acima e ainda tiver falhas de contêiner, é possível que, em algum lugar, os caches do sistema do Docker ou as configurações de rede persistentes não estejam atualizados com a reconfiguração mais recente. Nesse caso, a última opção de recurso é usar docker prune para começar do zero.
O comando a seguir interrompe o sistema de IoT Edge (e, portanto, todos os contêineres), usa a opção "todos" e "volume" para docker prune remover todos os contêineres e volumes. Examine o aviso de que o comando está com problemas 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 maior segurança, 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óximas etapas
Você acha que encontrou um bug na plataforma IoT Edge? Envie um problema para que possamos continuar melhorando.
Se você tiver mais dúvidas, crie uma Solicitação de suporte para obter ajuda.