Tutorial: Configurar e usar métricas e logs com um hub IoT

Você pode usar o Azure Monitor para coletar métricas e logs do hub IoT para a monitorar a operação de sua solução e resolver problemas quando eles ocorrerem. Neste tutorial, você verá como criar gráficos com base em métricas, como criar alertas que sejam disparados de acordo com métricas, como enviar operações e erros do Hub IoT para Logs do Azure Monitor e como verificar se há erros nos logs.

Este tutorial usa o exemplo do Azure do Início rápido de telemetria de envio do .NET para enviar mensagens ao hub IoT. Você sempre pode usar um dispositivo ou outro exemplo para enviar mensagens, mas terá que modificar algumas etapas para se adequar.

Alguma familiaridade com os conceitos do Azure Monitor poderá ser útil para iniciar este tutorial. Para saber mais, confira Monitorar o Hub IoT. Para saber mais sobre as métricas e os logs de recursos emitidos pelo Hub IoT, consulte a referência de dados de monitoramento.

Neste tutorial, você executa as seguintes tarefas:

• Usar a CLI do Azure para criar um hub IoT, registrar um dispositivo simulado e criar um workspace do Log Analytics.
• Enviar conexões do Hub IoT e logs de recursos de telemetria do dispositivo para Logs do Azure Monitor no workspace do Log Analytics.
• Usar o gerenciador de métricas para criar um gráfico com base em métricas selecionadas e fixá-lo em seu painel.
• Criar alertas de métricas para ser notificado por email quando condições importantes ocorrerem.
• Baixar e executar um aplicativo que simule um dispositivo IoT que envia mensagens para o hub IoT.
• Exibir os alertas quando as condições ocorrerem.
• Exibir o gráfico de métricas em seu painel.
• Exibir erros e operações do Hub IoT em Logs do Azure Monitor.

Pré-requisitos

• Uma assinatura do Azure. Se você não tiver uma assinatura do Azure, crie uma conta gratuita antes de começar.

• SDK do .NET Core 2.1 ou mais recente no computador de desenvolvimento. Você pode fazer o download do SDK do .NET Core para várias plataformas a partir do .NET.

  Verifique a versão atual do C# no computador de desenvolvimento usando o seguinte comando:

  dotnet --version
  

• Uma conta de email que possa receber emails.

• Verifique se a porta 8883 está aberta no firewall. A amostra de dispositivo deste tutorial usa o protocolo MQTT, que se comunica pela porta 8883. Essa porta poderá ser bloqueada em alguns ambientes de rede corporativos e educacionais. Para obter mais informações e maneiras de resolver esse problema, confira Como se conectar ao Hub IoT (MQTT).

• Use o ambiente Bash no Azure Cloud Shell. Para obter mais informações, confira Início Rápido para Bash no Azure Cloud Shell.

  

• Se preferir executar os comandos de referência da CLI localmente, instale a CLI do Azure. Para execuções no Windows ou no macOS, considere executar a CLI do Azure em um contêiner do Docker. Para obter mais informações, confira Como executar a CLI do Azure em um contêiner do Docker.

  • Se estiver usando uma instalação local, entre com a CLI do Azure usando o comando az login. Para concluir o processo de autenticação, siga as etapas exibidas no terminal. Para ver outras opções de entrada, confira Conectar-se com a CLI do Azure.

  • Quando solicitado, instale a extensão da CLI do Azure no primeiro uso. Para obter mais informações sobre extensões, confira Usar extensões com a CLI do Azure.

  • Execute az version para localizar a versão e as bibliotecas dependentes que estão instaladas. Para fazer a atualização para a versão mais recente, execute az upgrade.

Configurar recursos

Para este tutorial, você precisará de um hub IoT, um workspace do Log Analytics e um dispositivo IoT simulado. Esses recursos podem ser criados usando o portal do Azure, a CLI do Azure ou o PowerShell. Use o mesmo grupo de recursos e o local para todos os recursos. Em seguida, ao concluir o tutorial, você poderá remover tudo em uma única etapa, excluindo o grupo de recursos.

Para este tutorial, fornecemos um script da CLI que executa as seguintes etapas:

1. Crie um grupo de recursos.

2. Crie um Hub IoT.

3. Criar um espaço de trabalho do Log Analytics.

4. Registre uma identidade do dispositivo para o dispositivo simulado que envia mensagens para o hub IoT. Salve a cadeia de conexão do dispositivo para usar para configurar o dispositivo simulado.

Importante

Este artigo inclui etapas para conectar um dispositivo usando uma assinatura de acesso compartilhado, também chamada de autenticação de chave simétrica. Esse método de autenticação é conveniente para teste e avaliação, mas a autenticação em um dispositivo que usa certificados X.509 é uma abordagem mais segura. Para saber mais, consulte Práticas recomendadas de segurança > Segurança de conexão.

Configurar recursos usando a CLI do Azure

Copie e cole os comandos a seguir no Cloud Shell ou em uma instância de linha de comando local que tenha a CLI do Azure instalada. Alguns dos comandos podem demorar um pouco para serem executados. Os novos recursos são criados no grupo de recursos ContosoResources.

O nome de alguns recursos deve ser exclusivo no Azure. O script gera um valor aleatório com a função $RANDOM e o armazena em uma variável. Para esses recursos, o script acrescenta esse valor aleatório a um nome de base para o recurso, tornando o nome do recurso exclusivo.

Defina os valores para os nomes de recursos que não precisam ser globalmente exclusivos.

location=westus
resourceGroup=ContosoResources
iotDeviceName=Contoso-Test-Device

Defina os valores para os nomes de recursos que precisam ser exclusivos. Esses nomes têm um número aleatório concatenado até o final.

randomValue=$RANDOM
iotHubName=ContosoTestHub$randomValue
echo "IoT hub name = " $iotHubName
workspaceName=contoso-la-workspace$randomValue
echo "Log Analytics workspace name = " $workspaceName

Crie um grupo de recursos a ser usado para todos os recursos deste tutorial.

az group create --name $resourceGroup --location $location

Crie o hub IoT na camada gratuita. Cada assinatura pode ter somente um hub IoT gratuito. Se você já tiver um hub gratuito, altere o valor --sku para B1 (básico) ou S1 (padrão).

az iot hub create --name $iotHubName --resource-group $resourceGroup --partition-count 2 --sku F1 --location $location

Criar o workspace do Log Analytics

az monitor log-analytics workspace create --resource-group $resourceGroup --workspace-name $workspaceName --location $location

Crie a identidade do dispositivo IoT a ser usada para teste.

az iot hub device-identity create --device-id $iotDeviceName --hub-name $iotHubName

Recupere a cadeia de conexão primária para a identidade do dispositivo e copie-a localmente. Você precisa dessa cadeia de conexão para executar a simulação do dispositivo durante a fase de teste.

az iot hub device-identity connection-string show --device-id $iotDeviceName --hub-name $iotHubName

Coletar logs para conexões e telemetria de dispositivo

O Hub IoT emite logs de recursos para várias categorias de operações. Para exibir esses logs, você deve criar uma configuração de diagnóstico para enviá-los a um destino. Um desses destinos são os Logs do Azure Monitor, que são coletados em um workspace do Log Analytics. Os logs de recursos do Hub IoT são agrupados em categorias diferentes. Você pode selecionar quais categorias deseja enviar para os Logs do Azure Monitor na configuração de diagnóstico. Neste artigo, coletaremos logs para operações e erros que tenham relação com conexões e telemetria de dispositivo. Para obter uma lista completa das categorias com suporte para o Hub IoT, confira logs de recursos do Hub IoT.

Para criar uma configuração de diagnóstico para enviar logs de recursos do Hub IoT para logs do Azure Monitor, siga estas etapas:

1. No portal do Azure, navegue para o hub IoT. Se você usou os comandos da CLI para criar seus recursos, o hub IoT estará no grupo de recursos ContosoResources.

2. Selecione Configurações de diagnóstico, na seção Monitoramento do menu de navegação. Em seguida, selecione Adicionar configuração de diagnóstico.

   

3. Na página Configuração de diagnóstico, forneça os seguintes detalhes:

   Parâmetro	Valor
   Nome da configuração de diagnóstico	Dê um nome descritivo à configuração, como "Enviar conexões e telemetria para logs".
   Logs	Selecione Conexões e Telemetria de Dispositivo na lista Categorias.
   Detalhes do destino	Selecione Enviar para o workspace do Log Analytics. Em seguida, use o seletor do workspace do Log Analytics para selecionar o workspace que você anotou anteriormente.

   

4. Clique em Salvar para salvar as configurações. Feche o painel Configuração de diagnóstico. Veja sua nova configuração na lista de configurações de diagnóstico.

Configurar métricas

Agora, usaremos o gerenciador de métricas para criar um gráfico que exiba as métricas que você deseja controlar. Você fixará esse gráfico ao painel padrão na portal do Azure.

1. No menu do hub IoT, selecione Métricas na seção Monitoramento.

2. Na parte superior da tela, clique em Últimas 24 horas (Automático) . Na lista suspensa exibida, selecione Últimas 4 horas para Intervalo de Tempo e defina Granularidade de Tempo como 1 minuto. Depois, selecione Local em Mostrar hora como. Selecione Aplicar para salvar essas configurações. A configuração agora deve dizer Hora local: Últimas 4 horas (1 minuto) .

   

3. No gráfico, há uma configuração de métrica parcial exibida no escopo do seu hub IoT. Deixe os valores de Escopo e Namespace de Métrica em seus padrões. Selecione a configuração Métrica e digite "Telemetria" e, em seguida, selecione Mensagens de telemetria enviadas na lista suspensa. A agregação será definida automaticamente como Soma. Observe que o título do gráfico também é alterado.

   

4. Agora selecione Adicionar métrica para adicionar outra métrica ao gráfico. Em Métrica, selecione Número total de mensagens usadas. Para Agregação, selecione Média. Observe novamente que o título do gráfico foi alterado para incluir essa métrica.

   Agora a tela mostra a métrica minimizada para Mensagens de telemetria enviadas, além da nova métrica para Número total de mensagens usadas.

   

5. No canto superior direito do gráfico, selecione Salvar no painel e escolha Fixar no painel na lista suspensa.

   

6. No painel Fixar no painel, selecione a guia Existente. Selecione Privado e, em seguida, selecione Painel na lista suspensa Painel. Por fim, selecione Fixar para fixar o gráfico ao seu painel padrão no portal do Azure. Se você não fixar o gráfico em um painel, as configurações não serão mantidas quando você sair do gerenciador de métricas.

   

Configurar alertas de métricas

Agora, configuraremos alertas para disparar com base em duas métricas: Mensagens de telemetria enviadas e Número total de mensagens usadas.

A métrica Mensagens de telemetria enviadas é uma boa métrica para rastrear a taxa de transferência de mensagens e evitar a limitação. Para um hub IoT na camada gratuita, o limite é de 100 mensagens por segundo. Com um único dispositivo, não será possível atingir esse tipo de taxa de transferência. Portanto, em vez disso, configuraremos o alerta para ser acionado se o número de mensagens exceder 1.000 em um período de cinco minutos. Em produção, você pode definir o sinal como um valor mais significativo com base na camada, na edição e no número de unidades do hub IoT.

O Número total de mensagens usadas controla o número diário de mensagens usadas. Essa métrica é redefinida todos os dias às 00:00 UTC. Se você exceder a cota diária após um determinado limite, o Hub IoT não aceitará mais mensagens. Para um hub IoT na camada gratuita, a cota diária de mensagens é de 8000. Vamos configurar o alerta para disparar se o número total de mensagens exceder 4 mil, 50% da cota. Na prática, você provavelmente definiria esse percentual com um valor mais alto. O valor da cota diária depende da camada, da edição e do número de unidades do seu hub IoT.

Para obter mais informações sobre limites de cota e limitações com o Hub IoT, confira Cotas e limitação.

Para configurar alertas de métrica:

1. No menu do hub IoT, selecione Alertas na seção Monitoramento.

2. Selecione Criar regra de alerta.

   No painel Criar regra de alerta, há quatro seções:

   • O Escopo já está definido para o seu hub IoT, portanto, deixaremos esta seção como está.
   • A Condição define o sinal e as condições que vão disparar o alerta.
   • A seção Ações configura o que acontece quando o alerta é disparado.
   • Detalhes permite que você defina um nome e uma descrição para o alerta.

3. Primeiro, configure a condição em que o alerta será disparado.

   1. A guia Condição é aberta com o painel Selecionar um sinal aberto. Digite "telemetria" na caixa de pesquisa do nome do sinal e selecione Mensagens de telemetria enviadas.

      

   2. No painel Configurar lógica de sinal, defina ou confirme os seguintes campos em Lógica de alerta (você pode ignorar o gráfico):

      Parâmetro	Valor
      Limite	Estático
      Operador	Maior que
      Tipo de agregação	Total
      Valor limite	1000
      Unidade	Count
      Granularidade de agregação (período)	5 minutos
      Frequência de avaliação	A cada minuto

      

      Essas configurações definem o sinal para totalizar o número de mensagens em um período de cinco minutos. Esse total será avaliado a cada minuto e, se o total dos cinco minutos anteriores exceder mil mensagens, o alerta será disparado.

      Selecione Concluído para salvar a lógica do sinal.

4. Selecione Avançar: Ações para configurar a ação para o alerta.

   1. Selecione Criar grupo de ações.

   2. Na guia Básico no painel Criar grupo de ações, atribua um nome e um nome de exibição ao grupo de ações.

      

   3. Selecione a guia Notificações. Em Tipo de notificação, selecione Email/mensagem SMS/Push/Voz na lista suspensa. O painel Email/mensagem SMS/Push/Voz de voz é aberto.

   4. No painel Email/mensagem SMS/Push/Voz, selecione email e insira seu endereço de email e, em seguida, selecione OK.

      

   5. De volta ao painel Notificações, insira um nome para a notificação.

      

   6. (Opcional) Na guia Ações do grupo de ações, o menu suspenso Tipo de ação lista os tipos de ações que podem ser disparados com um alerta. Neste artigo usaremos apenas notificações, portanto ignore as configurações nessa guia.

      

   7. Selecione a guia Examinar e Criar, verifique as configurações e selecione Criar.

   8. De volta à guia Ações da regra de alerta, observe que o novo grupo de ações foi adicionado às ações do alerta.

5. Selecione Avançar: Detalhes para configurar os detalhes da regra de alerta e salvar a regra de alerta.

   1. Na guia Detalhes, forneça um nome e uma descrição para o alerta. Por exemplo, "Alertar se houver mais de mil mensagens em cinco minutos".

6. Selecione Examinar + criar para examinar os detalhes da regra de alerta. Se tudo parecer correto, selecione Criar para salvar sua nova regra.

7. Agora configure outro alerta para o Número total de mensagens usadas. Essa métrica é útil se você deseja enviar um alerta quando o número de mensagens usadas se aproximar da cota diária do hub IoT, momento em que o hub IoT começará a rejeitar mensagens. Siga as etapas que você fez antes, com as diferenças a seguir.

   • Para o sinal no painel Configurar lógica de sinal, selecione Número total de mensagens usadas.

   • No painel Configurar lógica de sinal, defina ou confirme os seguintes campos (você pode ignorar o gráfico):

     Parâmetro	Valor
     Limite	Estático
     Operador	Maior que
     Tipo de agregação	Total
     Valor limite	4000
     Unidade	Count
     Granularidade de agregação (período)	1 minuto
     Frequência de avaliação	A cada minuto

     Essas configurações definem o sinal para ser disparado quando o número de mensagens alcançar 4 mil. A métrica é avaliada a cada minuto.

   • Ao especificar a ação para a regra de alerta, selecione o grupo de ações que você criou para a regra anterior.

   • Para os detalhes do alerta, escolha um nome e uma descrição diferentes do que foi feito anteriormente.

8. Selecione Alertas, em Monitoramento no painel esquerdo do hub IoT. Agora, selecione Regras de alerta no menu na parte superior do painel Alertas. O painel Regras de alerta é aberto. Agora você deverá ver seus dois alertas:

   

9. Feche o painel Regras de alerta.

Com essas configurações, um alerta será disparado e você receberá uma notificação por email quando mais de mil mensagens forem enviadas em um período de cinco minutos e também quando o número total de mensagens usadas exceder 4 mil (50% da cota diária de um hub IoT na camada gratuita).

Executar um aplicativo de dispositivo simulado

Na seção Configurar recursos, você registrou uma identidade do dispositivo para usar para simular o uso de um dispositivo IoT. Nesta seção, baixe um aplicativo de console .NET que simula um dispositivo que envia mensagens de dispositivo para nuvem para um hub IoT, configure-o para enviar essas mensagens para o seu hub IoT e, em seguida, execute-o.

Importante

Os alertas podem levar até 10 minutos para serem totalmente configurados e habilitados pelo Hub IoT. Aguarde pelo menos 10 minutos entre o momento em que você configura o último alerta e a execução do aplicativo de dispositivo simulado.

Baixe ou clone a solução para o repositório do SDK de IoT do Azure para C# do GitHub. Esse repositório contém vários aplicativos de exemplo. Para este tutorial, usaremos iothub/device/samples/getting started/SimulatedDevice/.

1. Em uma janela de terminal local, navegue até a pasta raiz da solução. Em seguida, procure a pasta iothub\device\samples\getting started\SimulatedDevice.

2. Abra o arquivo SimulatedDevice.cs em seu editor de texto preferido.

   1. Substitua o valor da variável s_connectionString pela cadeia de conexão do dispositivo que você anotou quando executou o script para configurar os recursos.

   2. No método SendDeviceToCloudMessagesAsync, altere o Task.Delay de 1000 para 1, o que reduzirá o tempo entre o envio de mensagens de 1 para 0,001 segundo. A redução desse atraso aumenta o número de mensagens enviadas. (Provavelmente você não obterá uma taxa de 100 mensagens por segundo).

      await Task.Delay(1);
      

   3. Salve as alterações no SimulatedDevice.cs.

3. Na janela de terminal local, execute o seguinte comando para instalar os pacotes necessários para o aplicativo de dispositivo simulado:

   dotnet restore
   

4. Na janela de terminal local, execute os seguintes comandos para compilar e executar o aplicativo de dispositivo simulado:

   dotnet run
   

   A captura de tela a seguir mostra o resultado à medida que o aplicativo de dispositivo simulado envia telemetria para o seu hub IoT:

   

Deixe o aplicativo ser executado por pelo menos 10 a 15 minutos. O ideal é que ele seja executado até que pare de enviar mensagens (cerca de 20 a 30 minutos). Isso ocorrerá ao exceder a cota de mensagens diária para o hub IoT e parar de aceitar mais mensagens.

Observação

Se você deixar o aplicativo de dispositivo em execução por um período estendido depois que ele parar de enviar mensagens, você poderá se deparar com uma exceção. Você pode ignorar essa exceção com segurança e fechar a janela do aplicativo.

Exibir o gráfico de métricas no seu painel

1. No canto superior esquerdo do portal do Azure, abra o menu do portal e, em seguida, selecione Painel.

   

2. Localize o gráfico que você fixou anteriormente e clique em qualquer lugar no bloco fora dos dados do gráfico para expandi-lo. Ele mostra as mensagens de telemetria enviadas e o número total de mensagens usadas no gráfico. Os números mais recentes aparecem na parte inferior do gráfico. Mova o cursor no gráfico para ver os valores de métrica de horários específicos. Você também pode alterar o valor temporal e a granularidade na parte superior do gráfico para restringir ou expandir os dados para um período de interesse.

   

   Nesse cenário, a taxa de transferência de mensagens do dispositivo simulado não é grande o suficiente para fazer com que o Hub IoT limite as mensagens. Em um cenário que realmente envolva a limitação, você poderá ver que as mensagens de telemetria enviadas excedem o limite do seu hub IoT por um período limitado. Isso serve para acomodar o tráfego intermitente. Para obter detalhes, consulte traffic shaping.

Exibir os alertas

Quando o número de mensagens enviadas excede os limites definidos nas regras de alerta, você começa a receber alertas por email.

Para ver se há alertas ativos, selecione Alertas em Monitoramento no painel esquerdo do hub IoT. O painel Alertas mostra o número de alertas que foram disparados, classificados por severidade, para o intervalo de tempo especificado.

Selecione a linha da severidade Sev 3. O painel Todos os Alertas será aberto e listará os alertas Sev 3 que foram disparados.

Selecione um dos alertas para ver os respectivos detalhes.

Verifique sua caixa de entrada em busca de emails do Microsoft Azure. A linha do assunto descreverá o alerta que foi disparado. Por exemplo, Azure: Severidade Ativada: 3 Alertar se houver mais de mil mensagens em cinco minutos. O corpo será semelhante à seguinte imagem:

Exibir os Logs do Azure Monitor

Na seção Coletar logs de conexões e telemetria de dispositivo, você criou uma configuração de diagnóstico para enviar logs de recursos emitidos por seu hub IoT para operações de conexão e telemetria de dispositivo para os Logs do Azure Monitor. Nesta seção, você executará uma consulta Kusto em Logs do Azure Monitor para observar os erros que ocorreram.

1. Em Monitoramento no painel esquerdo do hub IoT no portal do Azure, selecione Logs. Feche a janela inicial de Consultas se ela for aberta.

2. No painel Nova Consulta, selecione a guia Consultas e, em seguida, expanda Hub IoT para ver a lista de consultas padrão.

   

3. Selecione a consulta Resumo de erros. A consulta aparece no painel do Editor de consultas. Selecione Executar no painel do editor e observe os resultados da consulta. Expanda uma das linhas para ver os detalhes.

   

   Observação

   Se você não vir nenhum erro, tente executar a consulta Dispositivos conectados recentemente. Isso deverá retornar uma linha para o dispositivo simulado.

Limpar os recursos

Para remover todos os recursos que você criou neste tutorial, exclua o grupo de recursos. Essa ação também exclui todos os recursos contidos no grupo. Nesse caso, ela remove o hub IoT, o workspace do Log Analytics e o próprio grupo de recursos. Se você tiver fixado gráficos de métricas no painel, precisará removê-las manualmente clicando nos três pontos no canto superior direito de cada gráfico e selecionar Remover. Salve as alterações depois de excluir os gráficos.

Para remover o grupo de recursos, use o comando excluir grupo az.

az group delete --name ContosoResources

Próximas etapas

Neste tutorial, você aprendeu a usar métricas e logs do Hub IoT executando as seguintes tarefas:

• Usar a CLI do Azure para criar um hub IoT, registrar um dispositivo simulado e criar um workspace do Log Analytics.
• Enviar conexões do Hub IoT e logs de recursos de telemetria do dispositivo para Logs do Azure Monitor no workspace do Log Analytics.
• Usar o gerenciador de métricas para criar um gráfico com base em métricas selecionadas e fixá-lo em seu painel.
• Criar alertas de métricas para ser notificado por email quando condições importantes ocorrerem.
• Baixar e executar um aplicativo que simule um dispositivo IoT que envia mensagens para o hub IoT.
• Exibir os alertas quando as condições ocorrerem.
• Exibir o gráfico de métricas em seu painel.
• Exibir erros e operações do Hub IoT em Logs do Azure Monitor.

Avance para o próximo tutorial para saber como testar os recursos de recuperação de desastre para o Hub IoT.

Executar failover manual para um Hub IoT