Partilhar via


Resolver problemas com o dispositivo IoT Edge

Aplica-se a: ícone sim IoT Edge 1.1

Importante

A data de fim do suporte do IoT Edge 1.1 foi 13 de dezembro de 2022. Consulte o Ciclo de Vida de Produtos da Microsoft para obter informações sobre como é suportado este 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 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:

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

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.

No Linux:

sudo iotedge support-bundle --since 6h

No Windows:

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.

No Linux:

  • Veja o status do gerenciador de segurança do IoT Edge:

    sudo systemctl status iotedge
    
  • Veja os logs do gerenciador de segurança do IoT Edge:

    sudo journalctl -u iotedge -f
    
  • Veja logs mais detalhados do gerenciador de segurança do IoT Edge:

    1. Edite as configurações do daemon do IoT Edge:

      sudo systemctl edit iotedge.service
      
    2. Atualize as seguintes linhas:

      [Service]
      Environment=IOTEDGE_LOG=debug
      
    3. Reinicie o daemon de segurança do IoT Edge:

      sudo systemctl cat iotedge.service
      sudo systemctl daemon-reload
      sudo systemctl restart iotedge
      

No Windows:

  • Veja o status do gerenciador de segurança do IoT Edge:

    Get-Service iotedge
    
  • Veja os logs do gerenciador de segurança do IoT Edge:

    . {Invoke-WebRequest -useb aka.ms/iotedge-win} | Invoke-Expression; Get-IoTEdgeLog
    
  • Veja apenas 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))
    
  • Veja logs mais detalhados do gerenciador de segurança do IoT Edge:

    1. Adicione uma variável de ambiente no nível do sistema:

      [Environment]::SetEnvironmentVariable("IOTEDGE_LOG", "debug", [EnvironmentVariableTarget]::Machine)
      
    2. Reinicie o IoT Edge Security Daemon:

      Restart-Service iotedge
      

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:

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 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 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 RuntimeLogLevel em seu arquivo de configuração yaml. Para abrir o ficheiro:

No Linux:

sudo nano /etc/iotedge/config.yaml

No Windows:

notepad C:\ProgramData\iotedge\config.yaml

Por padrão, o agent elemento será semelhante ao exemplo a seguir:

agent:
  name: edgeAgent
  type: docker
  env: {}
  config:
    image: mcr.microsoft.com/azureiotedge-agent:1.1
    auth: {}

Substitua env: {} por:

env:
  RuntimeLogLevel: debug

Aviso

Os arquivos YAML não podem conter guias como recuo. Em vez disso, use 2 espaços. Os itens de nível superior não podem ter 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 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)
  • Configure a saída (saída) para ser aberta ao usar MQTT como protocolo de comunicação.
  • O 1883 para MQTT não é suportado pelo IoT Edge.
  • As conexões de entrada (entrada) devem ser bloqueadas.
AMQP 5671 BLOQUEADO (padrão) OPEN (padrão)
  • Protocolo de comunicação padrão para IoT Edge.
  • Deve ser configurado para ser Aberto se o Azure IoT Edge não estiver configurado para outros protocolos com suporte ou se o AMQP for o protocolo de comunicação desejado.
  • 5672 para AMQP não é suportado pelo IoT Edge.
  • Bloqueie essa porta quando o Azure IoT Edge usar um protocolo com suporte diferente do Hub IoT.
  • As conexões de entrada (entrada) devem ser bloqueadas.
HTTPS 443 BLOQUEADO (padrão) OPEN (padrão)
  • Configure a Saída (Saída) para ser Aberta no 443 para provisionamento do IoT Edge. Essa configuração é necessária ao usar scripts manuais ou o Azure IoT Device Provisioning Service (DPS).
  • A conexão de entrada (entrada) deve ser aberta somente para cenários específicos:
    • Se você tiver um gateway transparente com dispositivos downstream que podem enviar solicitações de método. Nesse caso, a Porta 443 não precisa estar aberta a redes externas para se conectar ao IoTHub ou fornecer serviços IoTHub por meio do Azure IoT Edge. Assim, a regra de entrada poderia ser restrita apenas para abrir Incoming (Inbound) da rede interna.
    • Para cenários de cliente para dispositivo (C2D).
  • 80 para HTTP não é suportado pelo IoT Edge.
  • Se protocolos não-HTTP (por exemplo, AMQP ou MQTT) não puderem ser configurados na empresa; as mensagens podem ser enviadas através de WebSockets. A porta 443 será usada para comunicação WebSocket nesse caso.

Ú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 acima e ainda obtém falhas de contêiner, é possível que em algum lugar os caches do sistema docker ou as configurações de rede persistentes não estejam atualizadas 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 seguinte para 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.