Solucionar problemas em dispositivos IoT Edge

Aplica-se a: IoT Edge 1.5 IoT Edge 1.4

Importante

O IoT Edge 1.5 LTS e o IoT Edge 1.4 LTS são versões com suporte. O IoT Edge 1.4 LTS chegará ao fim da vida útil em 12 de novembro de 2024. Se você estiver em uma versão anterior, confira 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:

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 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.

Em um cenário usando dispositivos IoT Edge aninhados, você pode acessar a imagem de diagnóstico em dispositivos downstream roteando o pull da imagem por meio dos 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 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 obtém logs desde as últimas seis horas, 6d desde os últimos seis dias, 6m desde os últimos seis minutos e assim por diante. Inclua o sinalizador --help para ver uma lista completa de opções.

sudo 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 gera todas as propriedades relatadas por 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.

• Para ver o status dos serviços do sistema IoT Edge:

  sudo iotedge system status
  

• Para ver o status dos serviços do sistema IoT Edge:

  sudo iotedge system logs -- -f
  

• Habilite logs de nível de depuração para exibir logs mais detalhados dos serviços do sistema IoT Edge:

  1. Habilitar logs de nível de depuração.

     sudo iotedge system set-log-level debug
     sudo iotedge system restart
     

  2. Volte 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 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, logs extensos podem fazer com que o dispositivo fique cheio de logs e fique 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 logs detalhados sobre esses contêineres, defina a variável de ambiente RuntimeLogLevel no manifesto de implantação.

Para exibir mensagens que passam pelo hub do 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 runtime, com o valor padrão definido como info. Essa variável de ambiente pode usar os seguintes valores:

• fatal
• error
• geral
• informações
• depurar
• verbose

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 para a nuvem do Azure usando protocolos de Hub IoT com suporte. Para obter mais informações, consulte como escolher 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)	Configure a Saída como Aberta ao usar o MQTT como o protocolo de comunicação. Não há suporte para o 1883 para MQTT no IoT Edge. As conexões de Entrada devem ser bloqueadas.
AMQP	5671	BLOQUEADO (padrão)	ABERTO (padrão)	Protocolo de comunicação padrão do IoT Edge. Precisa ser configurado como Aberto, quando o Azure IoT Edge não está configurado para outros protocolos com suporte ou quando o AMQP é o protocolo de comunicação desejado. Não há suporte para o 5672 para AMQP no IoT Edge. Bloqueie essa porta quando o Azure IoT Edge usar outro protocolo do Hub IoT com suporte. As conexões de Entrada devem ser bloqueadas.
HTTPS	443	BLOQUEADO (padrão)	ABERTO (padrão)	Configure a Saída para ficar aberta na porta 443 para provisionamento do IoT Edge. Essa configuração é necessária ao usar scripts manuais ou o DPS (serviço de provisionamento de dispositivos) do Azure IoT. A conexão de entrada só deve ser aberta para cenários específicos: Se você tiver um gateway transparente com dispositivos de downstream que podem enviar solicitações de método. Nesse caso, a Porta 443 não precisa estar aberta para redes externas para conectar-se ao Hub IoT ou fornecer serviços do Hub IoT por meio do Azure IoT Edge. Assim, a regra de entrada pode ser restrita para abrir somente a Entrada da rede interna. Para cenários de cliente para dispositivo (C2D). Não há suporte ao 80 para HTTP no IoT Edge. Se os protocolos que não são HTTP (por exemplo, AMQP ou MQTT) não puderem ser configurados na empresa, as mensagens poderão ser enviadas por meio de WebSockets. A porta 443 é usada para comunicação WebSocket nesse caso.

Ú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 anteriores e ainda obtém falhas de contêiner, é possível que o sistema Docker esteja armazenando em cache ou que as configurações de rede persistidas não estejam atualizadas com a última reconfiguração. Nesse caso, a última opção de recurso é usar docker prune para começar do zero.

O comando a seguir interrompe o sistema IoT Edge (e, portanto, todos os contêineres), usa a opção "todos" e "volume" para docker prune para 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.