Coletar remotamente logs de diagnóstico de dispositivos usando a Atualização de Dispositivo para o Hub IoT

Saiba como iniciar uma operação de log da Atualização de Dispositivo para o Hub IoT e como visualizar os logs coletados no armazenamento de blobs do Azure.

Pré-requisitos

Acesso a um IoT Hub com Atualização de Dispositivo para IoT Hub habilitada.
Um dispositivo IoT (ou simulador) preparado para Atualização de Dispositivo no Hub IoT, implementando a Interface de Diagnóstico.
Uma conta de armazenamento de Blobs do Azure sob a mesma assinatura da sua conta de Atualização de Dispositivo para o Hub IoT.

Observação

No momento, o recurso de coleta de log remoto é compatível apenas com dispositivos que implementam a Interface de Diagnóstico e são capazes de carregar arquivos no Armazenamento de Blobs do Azure. A implementação do agente de referência também espera que o dispositivo escreva arquivos de log em um caminho de arquivo especificado pelo usuário no dispositivo.

Portal do Azure
Azure CLI

Navegadores com suporte:

Microsoft Edge
Google Chrome

Um ambiente da CLI do Azure:

Utilize o ambiente Bash no Azure Cloud Shell.
Em alternativa, se preferir executar os comandos de referência da CLI localmente, instale a CLI do Azure
- Entre na CLI do Azure usando o comando az login.
- Execute o comando az version para localizar a versão e as bibliotecas dependentes que estão instaladas. Para atualizar para a versão mais recente, execute az upgrade.
- Quando solicitado, instale as extensões da CLI do Azure no primeiro uso. Os comandos neste artigo usam a extensão azure-iot. Execute az extension update --name azure-iot para verificar se está usando a versão mais recente da extensão.

Dica

Os comandos da CLI do Azure neste artigo usam o caractere de barra invertida \ para continuação de linha para que os argumentos de comando sejam mais fáceis de ler. Essa sintaxe funciona em ambientes Bash. Se você estiver executando esses comandos no PowerShell, substitua cada barra invertida por um acento grave ``` ou remova-as inteiramente.

Vincular sua conta de Armazenamento de Blobs do Azure à instância de Atualização de Dispositivo

Para usar o recurso de coleta de log remoto, primeiro você deve vincular uma conta de armazenamento de Blobs do Azure à sua instância de Atualização de Dispositivo. Essa conta de armazenamento de blobs do Azure é onde seus dispositivos enviarão os logs de diagnóstico.

Portal do Azure
Azure CLI

No portal do Azure, navegue até sua conta de Atualização de Dispositivo para Hub IoT.
Selecione Instâncias na seção Gerenciamento de Instâncias do painel de navegação.
Selecione sua instância de Atualização de Dispositivo na lista e, em seguida, configure o Diagnóstico.
Selecione a guia Diagnóstico do Cliente e selecione a Conta de Armazenamento do Azure.
Escolha sua conta de armazenamento desejada na lista e selecione Salvar.
Depois de voltar à lista de instâncias, selecione Atualizar periodicamente até que o estado de provisionamento da instância mostre "Bem-sucedido". Esse processo geralmente leva de 2 a 3 minutos.

Use o comando az iot du instance create para configurar o diagnóstico para sua instância de Atualização de Dispositivo.

Dica

Você pode usar o az iot du instance create comando em instâncias de Atualização de Dispositivo existentes e ele configurará a instância com os parâmetros atualizados.

Substitua os seguintes marcadores de posição pelas suas próprias informações:

< >account_name: o nome da sua conta de Atualização de Dispositivo.
< >instance_name: o nome da instância de Atualização de Dispositivo.
< >storage_id: a ID do recurso da conta de armazenamento em que os logs de diagnóstico serão armazenados. Você pode recuperar a ID do recurso usando o comando az storage show e consultando o valor da ID: az storage account show -n <storage_name> --query id.

az iot du instance update --account <account_name> --instance <instance_name> --set enableDiagnostics=true diagnosticStorageProperties.resourceId=<storage_id>

Configurar a coleção de logs

O agente de atualização do dispositivo refere-se a um arquivo de configuração no dispositivo, localizado em /etc/adu/du-diagnostics-config.json no agente de referência.

Caminhos de arquivos para coleta de logs

O agente de Atualização de Dispositivo em um dispositivo coletará arquivos de caminhos específicos de arquivo no dispositivo quando receber um sinal de início de upload de log do serviço de Atualização de Dispositivo. Esses caminhos de arquivo são definidos no arquivo de configuração de diagnóstico.

Dentro do arquivo de configuração, cada arquivo de log a ser coletado e carregado é representado como um logComponent objeto com propriedades componentName e logPath. Essa configuração pode ser modificada conforme desejado.

Tamanho máximo do arquivo de log

O agente de Atualização de Dispositivo coletará apenas arquivos de log em um determinado tamanho de arquivo. Esse tamanho máximo do arquivo é definido no arquivo de configuração de diagnóstico.

O parâmetro relevante "maxKilobytesToUploadPerLogPath" será aplicado a cada objeto logComponent e poderá ser modificado conforme desejado.

Criar uma operação de registro

As operações de log são uma ação orientada por serviço que você pode instruir seus dispositivos IoT a executar por meio do serviço de atualização de dispositivos. Para obter uma explicação mais detalhada de como as operações de log funcionam, consulte o diagnóstico de atualização do dispositivo.

Portal do Azure
Azure CLI

Navegue até o Hub IoT e selecione a guia Atualizações na seção Gerenciamento de Dispositivos do painel de navegação.
Selecione a guia Diagnóstico na interface do usuário. Se você não vir uma guia Diagnóstico, verifique se está usando a versão mais recente da interface do usuário da Atualização de Dispositivo para Hub IoT. Se você vir "O diagnóstico deve estar habilitado para esta instância de Atualização de Dispositivo", verifique se você vinculou uma conta de armazenamento de Blobs do Azure à instância de Atualização de Dispositivo.
Selecione Adicionar operação de upload de log para acessar a página de criação da operação de log.
Insira um nome (ID) e uma descrição para sua nova operação de log e, em seguida, selecione Adicionar dispositivos para selecionar de quais dispositivos IoT você deseja coletar logs de diagnóstico.
Selecione Adicionar.
Depois de voltar à guia Diagnóstico, selecione Atualizar até ver sua operação de log listada na Tabela de Operações.
Depois que o status da operação for Bem-sucedido ou falhar, selecione o nome da operação para exibir seus detalhes. Uma operação será marcada como "Bem-sucedida" somente se todos os dispositivos de destino tiverem concluído o upload de log com êxito. Se alguns dispositivos de destino tiverem sido bem-sucedidos e alguns falharem, a operação de log será marcada como "Falha". Você pode usar a página de detalhes da operação de log para ver quais dispositivos foram bem-sucedidos e quais falharam.
Nos detalhes da operação de log, você pode exibir o status específico do dispositivo e ver o caminho do local do log. Esse caminho corresponde ao caminho do diretório virtual em sua conta de armazenamento de Blobs do Azure em que os logs de diagnóstico foram carregados.

Use o comando az iot du device log collect para configurar uma operação de coleta de logs de diagnóstico.

O comando device log collect usa os seguintes argumentos:

--account: o nome da conta de atualização de dispositivo.
--instance: o nome da instância de Atualização do Dispositivo.
--log-collection-id: um nome para a operação de coleta de logs.
--agent-id: pares chave=valor que identificam um agente de atualização de dispositivo de destino para essa operação de coleta de log. Use deviceId=<device name> se o agente tiver uma identidade de dispositivo. Use deviceId=<device name> moduleId=<module name> se o agente tiver uma identidade de módulo. Você pode usar o --agent-id parâmetro várias vezes para direcionar vários dispositivos.

Por exemplo:

az iot du device log collect \
    --account <Device Update account name> \
    --instance <Device Update instance name> \
    --log-collection-id <log collection name} \
    --agent-id deviceId=<device name> \
    --agent-id deviceId=<device name> moduleId=<module name>

Use az iot du device log show para exibir os detalhes de uma operação de coleta de log de diagnóstico específica.

az iot du device log show \
    --account <Device Update account name> \
    --instance <Device Update instance name> \
    --log-collection-id <log collection name>

Exibir e exportar logs de diagnóstico coletados

Depois que a operação de log tiver sido bem-sucedida, vá para sua conta de armazenamento de blobs do Azure.
Selecione Contêineres na seção Armazenamento de Dados do painel de navegação.
Selecione o contêiner com o mesmo nome que sua instância de Atualização de Dispositivo.
Use o caminho do local do log dos detalhes da operação de registro para navegar até o diretório correto que contém os logs. Por padrão, o recurso de coleta de log remoto instrui os dispositivos de destino a carregar logs de diagnóstico usando o seguinte modelo de caminho de diretório: contêiner de armazenamento de blobs/ID do dispositivo de destino/ID da operação de log/Caminho de log no dispositivo
Se você não modificou o componente de diagnóstico do agente de Atualização de Dispositivo, o dispositivo responderá a qualquer operação de log tentando carregar dois arquivos de log de texto não criptografado: o log de diagnóstico do agente de Atualização de Dispositivo ("aduc.log") e o log de diagnóstico do agente DO ("do-agent.log"). Para saber mais sobre quais arquivos de log o agente de referência de Atualização de Dispositivo coleta, leia a página de conceito para Diagnóstico de Atualização de Dispositivo.
Você pode exibir o conteúdo do arquivo de log selecionando o nome do arquivo, selecionando o elemento de menu (reticências) e clicando em Exibir/editar. Você também pode baixar ou excluir o arquivo de log selecionando as opções rotuladas respectivamente.

Próximas etapas

Para saber mais sobre os recursos de diagnóstico do Device Update, confira a visão geral do recurso de diagnóstico de atualização de dispositivo

Comentários

Esta página foi útil?

Last updated on 2025-06-05