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

  • Artigo

Use o Azure Monitor para coletar métricas e logs do seu hub IoT para monitorar a operação de sua solução e solucionar problemas quando eles ocorrerem. Neste tutorial, você aprenderá como criar gráficos com base em métricas, como criar alertas que disparam em métricas, como enviar operações e erros do Hub IoT para os 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 para o hub IoT. Você sempre pode usar um dispositivo ou outro exemplo para enviar mensagens, mas talvez seja necessário modificar algumas etapas de acordo.

Alguma familiaridade com os conceitos do Azure Monitor pode ser útil antes de começar este tutorial. Para saber mais, consulte Monitorar o Hub IoT. Para saber mais sobre as métricas e os logs de recursos emitidos pelo Hub IoT, consulte Referência de dados de monitoramento.

Neste tutorial, vai realizar as seguintes tarefas:

  • Use a CLI do Azure para criar um hub IoT, registrar um dispositivo simulado e criar um espaço de trabalho do Log Analytics.
  • Envie conexões do Hub IoT e logs de recursos de telemetria de dispositivo para os Logs do Azure Monitor no espaço de trabalho do Log Analytics.
  • Use o explorador de métricas para criar um gráfico com base nas métricas selecionadas e fixá-lo ao seu painel.
  • Crie alertas métricos para que você possa ser notificado por e-mail quando condições importantes ocorrerem.
  • Baixe e execute um aplicativo que simula um dispositivo IoT enviando mensagens para o hub IoT.
  • Veja os alertas quando as suas condições ocorrerem.
  • Veja o gráfico de métricas no seu painel.
  • Exiba erros e operações do Hub IoT nos Logs do Azure Monitor.

Pré-requisitos

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

  • .NET Core SDK 2.1 ou superior em sua máquina de desenvolvimento. Pode transferir o SDK de .NET Core para múltiplas plataformas em .NET.

    Pode verificar qual a versão atual do C# no seu computador de desenvolvimento através do seguinte comando:

    dotnet --version

  • Uma conta de e-mail capaz de receber e-mails.

  • Verifique se a porta 8883 está aberta no firewall. O exemplo de dispositivo neste tutorial usa o protocolo MQTT, que se comunica pela porta 8883. Essa porta pode estar bloqueada em alguns ambientes de rede corporativa e educacional. Para obter mais informações e maneiras de contornar esse problema, consulte Conectando-se ao Hub IoT (MQTT).

  • Use o ambiente Bash no Azure Cloud Shell. Para obter mais informações, consulte Guia de início rápido para Bash no Azure Cloud Shell.

  • Se preferir executar comandos de referência da CLI localmente, instale a CLI do Azure. Se estiver a utilizar o Windows ou macOS, considere executar a CLI do Azure num contentor Docker. Para obter mais informações, consulte Como executar a CLI do Azure em um contêiner do Docker.

    • Se estiver a utilizar uma instalação local, inicie sessão no CLI do Azure ao utilizar o comando az login. Para concluir o processo de autenticação, siga os passos apresentados no seu terminal. Para outras opções de entrada, consulte Entrar com a CLI do Azure.

    • Quando solicitado, instale a extensão da CLI do Azure na primeira utilização. Para obter mais informações sobre as extensões, veja Utilizar extensões com o CLI do Azure.

    • Execute o comando az version para localizar a versão e as bibliotecas dependentes instaladas. Para atualizar para a versão mais recente, execute o comando az upgrade.

Configurar recursos

Para este tutorial, você precisa de um hub IoT, um espaço de trabalho 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. Utilize o mesmo grupo de recursos e a mesma localização para todos os recursos. Em seguida, quando terminar o tutorial, você pode remover tudo em uma etapa excluindo o grupo de recursos.

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

  1. Crie um grupo de recursos.

  2. Crie um hub IoT.

  3. Criar uma área de trabalho do Log Analytics.

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

Configurar recursos usando a CLI do Azure

Copie e cole os seguintes comandos no Cloud Shell ou em uma instância de linha de comando local que tenha a CLI do Azure instalada. Alguns dos comandos podem levar algum tempo 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 e armazena-o $RANDOM em uma variável. Para esses recursos, o script acrescenta esse valor aleatório a um nome 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 devem ser exclusivos. Estes nomes têm um número aleatório concatenado até ao fim.

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

Crie o 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 subscrição só pode ter um Hub IoT gratuito. Se você já tiver um hub gratuito, altere o --sku valor 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 espaço de trabalho 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 testes.

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

Recupere a cadeia de conexão principal 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ção. 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 espaço de trabalho do Log Analytics. Os logs de recursos do Hub IoT são agrupados em diferentes categorias. Você pode selecionar quais categorias deseja enviar para os Logs do Azure Monitor na configuração de diagnóstico. Neste artigo, coletaremos logs de operações e erros relacionados a conexões e telemetria de dispositivos. Para obter uma lista completa das categorias suportadas para o Hub IoT, consulte Logs de recursos do Hub IoT.

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

  1. No Portal do Azure, navegue para o seu hub IoT. Se você usou os comandos da CLI para criar seus recursos, seu 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.

    Captura de ecrã que realça Definições de diagnóstico na secção Monitorização.

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

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

    Captura de tela mostrando as configurações finais do log de diagnóstico.

  4. Selecione Guardar para guardar as definições. Feche o painel de configurações Diagnóstico. Você pode ver sua nova configuração na lista de configurações de diagnóstico.

Configurar métricas

Agora vamos usar o explorador de métricas para criar um gráfico que exibe as métricas que você deseja acompanhar. Você fixará esse gráfico em seu painel padrão no portal do Azure.

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

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

    Captura de tela mostrando as configurações de tempo de métricas.

  3. No gráfico, há uma configuração de métrica parcial exibida com escopo para seu hub IoT. Deixe os valores Scope e Metric Namespace 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á automaticamente definida como Soma. Observe que o título do gráfico também muda.

    Captura de tela que mostra a adição de mensagens de telemetria enviadas métrica ao gráfico.

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

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

    Captura de tela que mostra a adição da métrica Número total de mensagens usadas ao gráfico.

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

    Captura de tela que destaca o botão Salvar no painel.

  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 seu gráfico em um painel, suas configurações não serão mantidas quando você sair do explorador de métricas.

    Captura de tela que mostra as configurações de Fixar no painel.

Configurar alertas de métricas

Agora vamos configurar alertas para disparar em duas métricas: mensagens de telemetria enviadas e número total de mensagens usadas.

As mensagens de telemetria enviadas são uma boa métrica para controlar a taxa de transferência de mensagens e evitar serem limitadas. Para um hub IoT na camada gratuita, o limite de limitação é de 100 mensagens/seg. Com um único dispositivo, não conseguiremos atingir esse tipo de taxa de transferência, então, em vez disso, configuraremos o alerta para disparar se o número de mensagens exceder 1000 em um período de 5 minutos. Na produção, você pode definir o sinal para um valor mais significativo com base na camada, edição e número de unidades do seu hub IoT.

O número total de mensagens usadas rastreia o número diário de mensagens usadas. Esta métrica é reiniciada todos os dias às 00:00 UTC. Se você exceder sua cota diária além de um determinado limite, seu Hub IoT não aceitará mais mensagens. Para um hub IoT na camada gratuita, a cota diária de mensagens é 8000. Vamos configurar o alerta para disparar se o número total de mensagens exceder 4000, 50% da quota. Na prática, você provavelmente definiria essa porcentagem para um valor mais alto. O valor da cota diária depende da camada, edição e número de unidades do seu hub IoT.

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

Para configurar alertas métricos:

  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 seu hub IoT, então deixaremos esta seção em paz.
    • A condição define o sinal e as condições que dispararão o alerta.
    • Actions configura o que acontece quando o alerta é acionado.
    • Detalhes permite definir um nome e uma descrição para o alerta.

  3. Primeiro, configure a condição na qual o alerta será acionado.

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

      Captura de tela mostrando a seleção da métrica.

    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 Value
      Threshold Estático
      Operador Maior que
      Tipo de agregação Total
      Valor limite 1000
      Unidade Contagem
      Granularidade da agregação (Período) 5 minutos
      Frequência da avaliação A cada 1 minuto

      Captura de ecrã a mostrar as definições das condições de alerta.

      Essas configurações definem o sinal para totalizar o número de mensagens durante um período de 5 minutos. Este total será avaliado a cada minuto e, se o total dos 5 minutos anteriores exceder 1000 mensagens, o alerta será acionado.

      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 Noções básicas no painel Criar grupo de ações, dê ao grupo de ações um nome e um nome para exibição.

      Captura de ecrã a mostrar o separador Noções básicas do painel Criar grupo de ações.

    3. Selecione a guia Notificações . Para Tipo de notificação, selecione E-mail/Mensagem SMS/Push/Voz na lista suspensa. O painel Mensagem de e-mail/SMS/Push/Voz é aberto.

    4. No painel E-mail/Mensagem SMS/Push/Voz, selecione e-mail e introduza o seu endereço de e-mail e, em seguida, selecione OK.

      Captura de ecrã a mostrar a definição do endereço de e-mail.

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

      Captura de ecrã a mostrar o painel de notificações concluído.

    6. (Opcional) Na guia Ações do grupo de ações, a lista suspensa Tipo de ação lista os tipos de ações que você pode acionar com um alerta. Para este artigo, usaremos apenas notificações, para que você possa ignorar as configurações nesta guia.

      Captura de tela mostrando os tipos de ação disponíveis no painel Ações.

    7. Selecione a guia Revisar e Criar , verifique suas configurações e selecione Criar.

    8. De volta à guia Ações da regra de alerta, observe que seu 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 salvá-la.

    1. Na guia Detalhes, forneça um nome e uma descrição para o alerta, por exemplo, "Alertar se mais de 1000 mensagens em 5 minutos".

  6. Selecione Rever + criar para rever os detalhes da sua regra de alerta. Se tudo estiver correto, selecione Criar para salvar a nova regra.

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

    • 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 Value
      Threshold Estático
      Operador Maior que
      Tipo de agregação Total
      Valor limite 4000
      Unidade Contagem
      Granularidade da agregação (Período) 1 minuto
      Frequência da avaliação A cada 1 minuto

      Essas configurações definem o sinal para disparar quando o número de mensagens atinge 4000. A métrica é avaliada a cada minuto.

    • Ao especificar a ação para a regra de alerta, selecione o mesmo grupo de ações criado para a regra anterior.

    • Para os detalhes do alerta, escolha um nome e uma descrição diferentes dos anteriores.

  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. Deverá ver os seus dois alertas:

    Captura de ecrã a mostrar o painel Regras com as novas regras de alerta.

  9. Feche o painel Regras de alerta.

Com essas configurações, um alerta será acionado e você receberá uma notificação por e-mail quando mais de 1000 mensagens forem enviadas em um período de tempo de 5 minutos e também quando o número total de mensagens usadas exceder 4000 (50% da cota diária para um hub IoT no nível gratuito).

Executar o aplicativo de dispositivo simulado

Na seção Configurar recursos, você registrou uma identidade de dispositivo a ser usada para simular o uso de um dispositivo IoT. Nesta seção, você baixa um aplicativo de console .NET que simula um dispositivo que envia mensagens do dispositivo para a nuvem para um hub IoT, configura-o para enviar essas mensagens para seu hub IoT e o executa.

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 Azure IoT C# SDK do GitHub. Este 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, navegue até a pasta iothub\device\samples\getting started\SimulatedDevice .

  2. Abra o ficheiro SimulatedDevice.cs num editor de texto à sua escolha.

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

    2. SendDeviceToCloudMessagesAsync No método, altere o Task.Delay de 1000 para 1, o que reduz a quantidade de tempo entre o envio de mensagens de 1 segundo para 0,001 segundo. Encurtar esse atraso aumenta o número de mensagens enviadas. (Você provavelmente não receberá uma taxa de mensagens de 100 mensagens por segundo.)

      await Task.Delay(1);

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

  3. Na janela do 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 o seguinte comando para compilar e executar a aplicação de dispositivo simulado:

    dotnet run

    A seguinte captura de ecrã mostra a saída à medida que a aplicação de dispositivo simulado envia telemetria para o seu hub IoT:

    Captura de tela mostrando a saída simulada do dispositivo.

Deixe o aplicativo ser executado por pelo menos 10-15 minutos. O ideal é deixá-lo funcionar até parar de enviar mensagens (cerca de 20 a 30 minutos). Isso acontecerá quando você tiver excedido a cota diária de mensagens para seu hub IoT e ele parar de aceitar mais mensagens.

Nota

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

Ver gráfico de métricas no seu painel

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

    Captura de tela como selecionar seu painel.

  2. Encontre 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. Você pode mover o cursor no gráfico para ver os valores de métrica para horários específicos. Você também pode alterar o valor do tempo e a granularidade na parte superior do gráfico para restringir ou expandir os dados para um período de interesse.

    Captura de tela mostrando o gráfico de métricas.

    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 suas mensagens. Em um cenário que realmente envolve limitação, você pode ver mensagens de telemetria enviadas excederem o limite de aceleração para seu hub IoT por um tempo limitado. Isso é para acomodar o tráfego de explosão. Para obter detalhes, consulte Modelagem de tráfego.

Ver 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 gravidade para o intervalo de tempo especificado.

Captura de ecrã a mostrar o resumo dos alertas.

Selecione a linha para gravidade Sev 3. O painel Todos os Alertas é aberto e lista os alertas Sev 3 que foram acionados.

Captura de ecrã a mostrar o painel Todos os Alertas.

Selecione um dos alertas para ver os detalhes do alerta.

Captura de ecrã a mostrar detalhes do alerta.

Verifique se há e-mails do Microsoft Azure na sua caixa de entrada. A linha de assunto descreverá o alerta que foi acionado. Por exemplo, Azure: Activated Severity: 3 Alert se mais de 1000 mensagens durante 5 minutos. O corpo será semelhante à seguinte imagem:

Captura de tela do e-mail mostrando que os alertas foram disparados.

Exibir logs do Azure Monitor

Na seção Coletar logs para conexões e telemetria de dispositivo, você criou uma configuração de diagnóstico para enviar logs de recursos emitidos pelo 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 nos Logs do Azure Monitor para observar quaisquer erros que ocorreram.

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

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

    Captura de tela das consultas padrão do Hub IoT.

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

    Captura de tela dos logs retornados pela consulta Resumo de erros.

    Nota

    Se não vir erros, tente executar a consulta Dispositivos ligados recentemente. Isso deve retornar uma linha para o dispositivo simulado.

Clean up resources (Limpar recursos)

Para remover todos os recursos criados neste tutorial, exclua o grupo de recursos. Esta ação também elimina todos os recursos contidos no grupo. Nesse caso, ele remove o hub IoT, o espaço de trabalho do Log Analytics e o próprio grupo de recursos. Se você fixou gráficos de métricas no painel, terá que removê-los manualmente clicando nos três pontos no canto superior direito de cada gráfico e selecionando Remover. Certifique-se de salvar suas alterações depois de excluir os gráficos.

Para remover o grupo de recursos, utilize o comando az group delete.

az group delete --name ContosoResources

Próximos passos

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

  • Use a CLI do Azure para criar um hub IoT, registrar um dispositivo simulado e criar um espaço de trabalho do Log Analytics.
  • Envie conexões do Hub IoT e logs de recursos de telemetria de dispositivo para os Logs do Azure Monitor no espaço de trabalho do Log Analytics.
  • Use o explorador de métricas para criar um gráfico com base nas métricas selecionadas e fixá-lo ao seu painel.
  • Crie alertas métricos para que você possa ser notificado por e-mail quando condições importantes ocorrerem.
  • Baixe e execute um aplicativo que simula um dispositivo IoT enviando mensagens para o hub IoT.
  • Veja os alertas quando as suas condições ocorrerem.
  • Veja o gráfico de métricas no seu painel.
  • Exiba erros e operações do Hub IoT nos Logs do Azure Monitor.

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

Executar failover manual para um hub IoT