Tutoriel : Configurer et utiliser des métriques et des journaux avec un hub IoT

Utilisez Azure Monitor afin de collecter des métriques et des journaux pour votre hub IoT qui peuvent vous aider à superviser le fonctionnement de votre solution et à résoudre les problèmes lorsqu’ils se produisent. Dans ce tutoriel, vous allez apprendre à créer des graphiques basés sur des métriques, créer des alertes qui déclenchent des métriques, envoyer des opérations et des erreurs IoT Hub vers des journaux Azure Monitor, et consulter les erreurs dans les journaux.

Ce tutoriel utilise l’exemple Azure du guide de démarrage rapide d’envoi de données de télémétrie (.NET) pour envoyer des messages au hub IoT. Vous pouvez toujours utiliser un appareil ou un autre exemple pour envoyer des messages, mais vous devrez peut-être modifier certaines étapes en conséquence.

Nous vous conseillons de vous familiariser avec les concepts Azure Monitor avant de commencer ce tutoriel. Pour plus d’informations, consultez Surveiller IoT Hub. Pour en savoir plus sur les métriques et les journaux de ressources émis par IoT Hub, consultez les informations de référence sur la supervision des données.

Dans ce didacticiel, vous allez effectuer les tâches suivantes :

Prérequis

• Un abonnement Azure. Si vous n’avez pas d’abonnement Azure, créez un compte gratuit avant de commencer.

• SDK .NET Core 2.1 ou plus sur votre machine de développement. Vous pouvez télécharger le Kit SDK .NET Core pour plusieurs plateformes sur .NET.

  Vous pouvez vérifier la version actuelle de C# sur votre machine de développement à l’aide de la commande suivante :

  dotnet --version
  

• Un compte e-mail capable de recevoir des e-mails.

• Assurez-vous que le port 8883 est ouvert dans votre pare-feu. L'exemple d’appareil de ce tutoriel utilise le protocole MQTT qui communique sur le port 8883. Dans certains environnements réseau professionnels et scolaires, ce port peut être bloqué. Pour plus d’informations sur les différentes façons de contourner ce problème, consultez Connexion à IoT Hub (MQTT).

• Utilisez l’environnement Bash dans Azure Cloud Shell. Pour plus d’informations, consultez Démarrage rapide pour Bash dans Azure Cloud Shell.

  

• Si vous préférez exécuter les commandes de référence de l’interface de ligne de commande localement, installez l’interface Azure CLI. Si vous exécutez sur Windows ou macOS, envisagez d’exécuter Azure CLI dans un conteneur Docker. Pour plus d’informations, consultez Guide pratique pour exécuter Azure CLI dans un conteneur Docker.

  • Si vous utilisez une installation locale, connectez-vous à Azure CLI à l’aide de la commande az login. Pour finir le processus d’authentification, suivez les étapes affichées dans votre terminal. Pour connaître les autres options de connexion, consultez Se connecter avec Azure CLI.

  • Lorsque vous y êtes invité, installez l’extension Azure CLI lors de la première utilisation. Pour plus d’informations sur les extensions, consultez Utiliser des extensions avec Azure CLI.

  • Exécutez az version pour rechercher la version et les bibliothèques dépendantes installées. Pour effectuer une mise à niveau vers la dernière version, exécutez az upgrade.

Configurer des ressources

Pour ce tutoriel, vous avez besoin d’un hub IoT, d’un espace de travail Log Analytics et d’un appareil IoT simulé. Ces ressources peuvent être créées à l’aide du portail Azure, d’Azure CLI ou de PowerShell. Utilisez le même groupe de ressources et le même emplacement pour toutes les ressources. Ensuite, lorsque vous aurez terminé ce tutoriel, vous pourrez tout supprimer en une seule étape en supprimant le groupe de ressources.

Pour ce tutoriel, nous avons fourni un script CLI qui effectue les étapes suivantes :

1. Créez un groupe de ressources.

2. Créez un hub IoT.

3. Créez un espace de travail Log Analytics.

4. Inscrivez une identité d’appareil pour l’appareil simulé qui envoie des messages à votre hub IoT. Enregistrez la chaîne de connexion de l’appareil à utiliser pour configurer l’appareil simulé.

Configurer des ressources à l’aide d’Azure CLI

Copiez et collez les commandes suivantes dans Cloud Shell ou une instance de ligne de commande locale sur laquelle Azure CLI est installé. L’exécution de certaines commandes peut prendre un certain temps. Les nouvelles ressources sont créées dans le groupe de ressources ContosoResources.

Le nom de certaines ressources doit être unique dans Azure. Le script génère une valeur aléatoire avec la fonction $RANDOM, et la stocke dans une variable. Pour ces ressources, le script ajoute cette valeur aléatoire à un nom de base pour la ressource, ce qui rend le nom de la ressource unique.

Définissez les valeurs des noms de ressources qui n’ont pas besoin d’être globalement uniques.

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

Définissez les valeurs des noms de ressources qui doivent être uniques. Ces noms ont un nombre aléatoire concaténé à la fin.

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

Créez le groupe de ressources qui sera utilisé pour toutes les ressources de ce tutoriel.

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

Créez le hub IoT dans le niveau gratuit. Chaque abonnement peut avoir uniquement un IoT hub gratuit. Si vous disposez déjà d’un hub gratuit, remplacez la valeur --sku par B1 (de base) ou S1 (standard).

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

Créer l’espace de travail Log Analytics

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

Créez l’identité d’appareil IoT à utiliser pour les tests.

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

Récupérez la chaîne de connexion principale de l’identité de l’appareil, puis copiez-la localement. Vous avez besoin de cette chaîne de connexion pour exécuter la simulation d’appareil pendant la phase de test.

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

Collecter les journaux pour les connexions et la télémétrie des appareils

IoT Hub émet des journaux de ressources pour plusieurs catégories d’opérations. Pour visualiser ces journaux, vous devez créer un paramètre de diagnostic pour les envoyer à une destination. telle que les journaux Azure Monitor, qui sont collectés dans un espace de travail Log Analytics. Les journaux de ressources IoT Hub sont regroupés dans différentes catégories. Vous pouvez sélectionner celles que vous souhaitez envoyer vers les journaux Azure Monitor dans le paramètre de diagnostic. Dans cet article, nous allons recueillir les journaux des opérations et des erreurs au niveau des connexions et de la télémétrie des appareils. Pour obtenir la liste complète des catégories prises en charge pour IoT Hub, consultez Journaux de ressources IoT Hub.

Pour créer un paramètre de diagnostic pour envoyer des journaux de ressources IoT Hub vers les journaux Azure Monitor, effectuez les étapes suivantes :

1. Accédez à votre IoT Hub dans le portail Azure. Si vous avez utilisé les commandes CLI pour créer vos ressources, votre hub IoT se trouve dans le groupe de ressources ContosoResources.

2. Sélectionnez Paramètres de diagnostic dans la section Surveillance du menu de navigation. Sélectionnez ensuite Ajouter un paramètre de diagnostic.

   

3. Dans la page Paramètres de diagnostic, fournissez les détails suivants :

   Paramètre	Valeur
   Nom du paramètre de diagnostic	Donnez à votre paramètre un nom descriptif, par exemple « Envoyer des connexions et des données de télémétrie vers les journaux ».
   Journaux d’activité	Sélectionnez Connexions et Télémétrie d’appareil dans la liste Catégories.
   Détails de la destination	Sélectionnez Envoyer à un espace de travail Log Analytics, puis utilisez le sélecteur d’espace de travail Log Analytics pour sélectionner l’espace de travail noté précédemment.

   

4. Sélectionnez Enregistrer pour enregistrer les paramètres. Fermez le volet Paramètre de diagnostic. Vous pouvez voir votre nouveau paramètre dans la liste des paramètres de diagnostic.

Configurer des métriques

À présent, nous allons utiliser l’explorateur de métriques pour créer un graphique qui affiche les métriques que vous souhaitez suivre. Vous allez épingler ce graphique à votre tableau de bord par défaut dans le portail Azure.

1. Dans le menu de votre hub IoT, sélectionnez Métriques dans la section Surveillance.

2. En haut de l’écran, sélectionnez Dernières 24 heures (automatique) . Dans la liste déroulante qui s’affiche, sélectionnez 4 dernières heures comme Intervalle de temps, 1 minute comme Granularité temporelle et Local pour Afficher l’heure en tant que. Sélectionnez Appliquer pour enregistrer ces paramètres. Le paramètre doit maintenant indiquer Heure locale : 4 dernières heures (1 minute) .

   

3. Sur le graphique, un paramètre de métrique partiel est affiché, avec votre hub IoT comme étendue. Conservez les valeurs par défaut d’Étendue et d’Espace de noms de métrique. Sélectionnez le paramètre Métrique et tapez « Télémétrie », puis sélectionnez Messages de télémétrie envoyés dans la liste déroulante. L’Agrégation sera automatiquement définie sur Sum. Notez que le titre de votre graphique change également.

   

4. Sélectionnez maintenant Ajouter une métrique pour ajouter une autre métrique au graphique. Sous Métrique, sélectionnez Nombre total de messages utilisés. Sous Agrégation, sélectionnez Moy. Remarquez là encore que le titre du graphique a changé pour inclure cette métrique.

   Votre écran montre maintenant la métrique réduite pour Messages de télémétrie envoyés ainsi que la nouvelle métrique pour Nombre total de messages utilisés.

   

5. Dans le coin supérieur droit du graphique, sélectionnez Enregistrer dans le tableau de bord et choisissez Épingler au tableau de bord dans la liste déroulante.

   

6. Dans le volet Épingler au tableau de bord, sélectionnez l’onglet Existant. Sélectionnez Privé, puis Tableau de bord dans la liste déroulante Tableau de bord. Pour finir, sélectionnez Épingler pour épingler le graphique à votre tableau de bord par défaut dans le portail Azure. Si vous n’épinglez pas votre graphique à un tableau de bord, vos paramètres ne sont pas conservés lorsque vous quittez l’explorateur de métriques.

   

Configurer des alertes de métriques

À présent, nous allons configurer des alertes à déclencher sur les deux métriques : Messages de télémétrie envoyés et Nombre total de messages utilisés.

Messages de télémétrie envoyés est une bonne métrique pour suivre le débit des messages et éviter toute limitation. Pour un concentrateur IoT dans le niveau gratuit, la limite d'étranglement est de 100 messages/s. Avec un seul appareil, nous ne pourrons pas atteindre ce débit. Avec un seul appareil, nous ne pourrons pas atteindre un tel débit. Nous allons donc configurer l'alerte pour qu'elle se déclenche si le nombre de messages dépasse 1 000 sur une période de 5 minutes. En production, vous pouvez définir le signal sur une valeur plus élevée, en fonction du niveau, de l’édition et du nombre d’unités de votre hub IoT.

Nombre total de messages utilisés effectue le suivi du nombre quotidien de messages utilisés. Cette métrique est réinitialisée tous les jours à 00:00 UTC. Si votre quota quotidien dépasse un certain seuil, votre hub IoT n’acceptera plus de messages. Pour un hub IoT au niveau gratuit, le quota de messages quotidien est de 8 000. Nous allons configurer l’alerte de façon à ce qu’elle se déclenche si le nombre total de messages dépasse 4000, soit 50 % du quota. Dans la pratique, vous choisirez probablement un pourcentage supérieur. La valeur de quota quotidien dépend du niveau, de l’édition et du nombre d’unités de votre hub IoT.

Pour plus d’informations sur les limites de quota et les seuils de limitation avec IoT Hub, consultez Quotas et limitation.

Pour configurer des alertes de métriques

1. Dans le menu de votre hub IoT, sélectionnez Alertes dans la section Surveillance.

2. Sélectionnez Créer une règle d’alerte.

   Le volet Créer une règle d’alerte comporte quatre sections :

   • L’Étendue est déjà définie sur votre hub IoT. Nous allons donc laisser cette section inchangée.
   • Condition définit le signal et les conditions qui déclencheront l’alerte.
   • Actions configure ce qui se produit lorsque l’alerte se déclenche.
   • Détails vous permet de définir un nom et une description pour l’alerte.

3. Tout d’abord, configurez la condition sur laquelle l’alerte sera déclenchée.

   1. L’onglet Condition s’ouvre avec le volet Sélectionner un signal ouvert. Tapez « telemetry » dans la zone de recherche du nom du signal et sélectionnez Messages de télémétrie envoyés.

      

   2. Dans le volet Configurer la logique du signal, définissez ou confirmez les champs suivants sous Logique d’alerte (vous pouvez ignorer le graphique) :

      Paramètre	Valeur
      Seuil	Statique
      Opérateur	Supérieur à
      Type d’agrégation	Total
      Valeur du seuil	1 000
      Unité	Count
      Précision d’agrégation (période)	5 minutes
      Fréquence d’évaluation	Toutes les minutes

      

      Ces paramètres définissent le signal de façon à totaliser le nombre de messages sur une période de cinq minutes. Ce total sera évalué toutes les minutes et, si le total des cinq minutes précédentes dépasse 1000 messages, l’alerte sera déclenchée.

      Sélectionnez Terminé pour enregistrer la logique du signal.

4. Sélectionnez Suivant : Actions pour configurer l’action pour l’alerte.

   1. Sélectionnez Créer un groupe d’actions.

   2. Dans l’onglet De base du volet Créer un groupe d’actions, attribuez un nom et un nom d’affichage à votre groupe d’actions.

      

   3. Sélectionnez l’onglet Notifications. Comme Type de notification, sélectionnez E-mail/SMS/Push/Voix dans la liste déroulante. Le volet E-mail/SMS/Push/Voix s’ouvre.

   4. Dans le volet E-mail/SMS/Push/Voix, sélectionnez e-mail et entrez votre adresse e-mail, puis sélectionnez OK.

      

   5. De retour dans le volet Notifications, entrez un nom pour la notification.

      

   6. (Facultatif) Dans l’onglet Actions du groupe d’actions, la liste déroulante Type d’action répertorie les types d’actions que vous pouvez déclencher avec une alerte. Dans le cadre de cet article, nous utiliserons uniquement des notifications. Vous pouvez donc ignorer les paramètres sous cet onglet.

      

   7. Sélectionnez l’onglet Vérifier + créer, vérifiez vos paramètres, puis sélectionnez Créer.

   8. De retour dans l’onglet Actions de la règle d’alerte, vous remarquerez que votre nouveau groupe d’actions a été ajouté aux actions de l’alerte.

5. Sélectionnez Suivant : Détails pour configurer les détails de la règle d’alerte et enregistrer la règle d’alerte.

   1. Dans l’onglet Détails, donnez un nom et une description à votre alerte ; par exemple, « Alerte si plus de 1000 messages sur 5 minutes ».

6. Sélectionnez Vérifier + créer pour passer en revue les détails de votre règle d’alerte. Si tout semble correct, sélectionnez Créer pour enregistrer votre nouvelle règle.

7. Maintenant, configurez une autre alerte pour le Nombre total de messages utilisés. Cette métrique est utile si vous souhaitez envoyer une alerte quand le nombre de messages utilisés approche le quota quotidien du hub IoT, stade auquel le hub commencera à rejeter les messages. Effectuez les mêmes étapes que précédemment, mais avec les différences suivantes.

   • Pour le signal dans le volet Configurer la logique du signal, sélectionnez Nombre total de messages utilisés.

   • Dans le volet Configurer la logique du signal, définissez ou confirmez les champs suivants (vous pouvez ignorer le graphique) :

     Paramètre	Valeur
     Seuil	Statique
     Opérateur	Supérieur à
     Type d’agrégation	Total
     Valeur du seuil	4000
     Unité	Count
     Précision d’agrégation (période)	1 minute
     Fréquence d’évaluation	Toutes les minutes

     Ces paramètres définissent le signal pour qu’il se déclenche lorsque le nombre de messages atteint 4000. La métrique est évaluée toutes les minutes.

   • Lorsque vous spécifiez l’action pour votre règle d’alerte, sélectionnez le même groupe d’action que celui que vous avez créé pour la règle précédente.

   • Pour les détails de l’alerte, choisissez un nom et une description différents de ceux choisis plus tôt.

8. Sélectionnez Alertes sous Supervision dans le volet gauche de votre hub IoT. À présent, sélectionnez Règles d’alerte dans le menu en haut du volet Alertes. Le volet Règles d’alerte s’ouvre. Vous devriez voir vos deux alertes :

   

9. Fermez le volet Règles d’alerte.

Avec ces paramètres, une alerte est déclenchée et vous recevez une notification par e-mail lorsque plus de 1000 messages sont envoyés durant une période de cinq minutes et que le nombre total de messages utilisés dépasse 4000 (50 % du quota quotidien d’un hub IoT au niveau gratuit).

Exécution de l’application de périphérique simulé

Dans la section Configurer des ressources, vous avez inscrit une identité d’appareil à utiliser pour simuler l’utilisation d’un appareil IoT. Dans cette section, vous allez télécharger une application console .NET qui simule un appareil envoyant des messages appareil-à-cloud à un hub IoT, la configurer pour envoyer ces messages à votre hub IoT, puis l’exécuter.

Téléchargez ou clonez la solution pour le dépôt du SDK Azure IoT pour C# à partir de GitHub. Ce référentiel contient plusieurs exemples d’applications. Pour ce tutoriel, nous utilisons iothub/device/samples/getting started/SimulatedDevice/.

1. Dans une fenêtre de terminal local, accédez au dossier racine de la solution. Accédez ensuite au dossier iothub\device\samples\getting started\SimulatedDevice.

2. Utilisez un éditeur de texte pour ouvrir le fichier SimulatedDevice.cs.

   1. Remplacez la valeur de la variable s_connectionString par la chaîne de connexion de l’appareil que vous avez notée lorsque vous avez exécuté le script pour configurer des ressources.

   2. Dans la méthode SendDeviceToCloudMessagesAsync, remplacez la valeur 1000 de Task.Delay par 1, ce qui réduit l’intervalle de temps entre l’envoi de messages de 1 à 0,001 seconde. Le fait d’écourter ce délai augmente le nombre de messages envoyés. (Vous n’atteindrez probablement pas un taux de 100 messages par seconde.)

      await Task.Delay(1);
      

   3. Enregistrez les changements apportés à SimulatedDevice.cs.

3. Dans la fenêtre de terminal local, exécutez la commande suivante pour installer les packages requis pour l’application d’appareil simulé :

   dotnet restore
   

4. Dans la fenêtre de terminal local, exécutez la commande suivante pour générer et exécuter l’application d’appareil simulé :

   dotnet run
   

   La capture d’écran suivante présente la sortie lorsque l’application d’appareil simulé envoie des données de télémétrie à votre IoT Hub :

   

Laissez l’application s’exécuter pendant au moins 10 à 15 minutes. Dans l’idéal, laissez-la s’exécuter jusqu’à ce qu’elle cesse d’envoyer des messages (environ 20 à 30 minutes). Cela se produira lorsque vous aurez dépassé le quota quotidien de messages pour votre hub IoT et qu’il aura cessé d’accepter des messages.

Afficher le graphique des métriques dans votre tableau de bord

1. Dans le coin supérieur gauche du portail Azure, ouvrez le menu du portail, puis sélectionnez Tableau de bord.

   

2. Recherchez le graphique que vous avez épinglé et cliquez n’importe où sur la vignette en dehors des données du graphique pour le développer. Le graphique montre les messages de télémétrie envoyés et le nombre total de messages utilisés. Les nombres les plus récents apparaissent en bas du graphique. Vous pouvez déplacer le curseur dans le graphique pour afficher les valeurs de métrique pour des heures spécifiques. Vous pouvez également modifier la valeur de temps et la précision en haut du graphique pour affiner ou développer les données sur une période qui vous intéresse.

   

   Dans ce scénario, le débit des messages de l’appareil simulé n’est pas suffisamment élevé pour qu’IoT Hub limite ses messages. Dans un scénario qui implique réellement une limitation, vous constaterez peut-être que le nombre de messages de télémétrie envoyés dépasse le seuil de limitation de votre hub IoT pendant une période limitée. Cela permet de gérer le trafic en rafale. Pour plus d’informations, consultez Régulation de flux.

Afficher les alertes

Lorsque le nombre de messages envoyés dépasse les limites que vous avez définies dans vos règles d’alerte, vous commencez à recevoir des alertes par e-mail.

Pour voir s’il existe des alertes actives, sélectionnez Alertes sous Supervision dans le volet gauche de votre hub IoT. Le volet Alertes montre le nombre d’alertes déclenchées, triées par gravité pour la période spécifiée.

Sélectionnez la ligne correspondant à la gravité 3. Le volet Toutes les alertes s’ouvre et contient la liste des alertes de gravité 3 qui ont été déclenchées.

Sélectionnez l’une des alertes pour en afficher les détails.

Ouvrez votre boîte de réception pour consulter les e-mails de Microsoft Azure. La ligne d’objet décrit l’alerte qui a été déclenchée. Par exemple, Azure : Gravité activée : 3 Alerte si plus de 1000 messages en cinq minutes. Le corps ressemblera à l’image suivante :

Afficher les journaux Azure Monitor

Dans la section Collecter les journaux pour les connexions et la télémétrie des appareils, vous avez créé un paramètre de diagnostic afin d’envoyer les journaux de ressources émis par votre hub IoT pour les opérations de télémétrie des connexions et des appareils vers les journaux à Azure Monitor. Dans cette section, vous allez exécuter une requête Kusto sur des journaux Azure Monitor pour observer les erreurs qui se sont produites.

1. Sous Supervision dans le volet gauche de votre hub IoT dans le portail Azure, sélectionnez Journaux. Fermez la fenêtre Requêtes initiale si elle s’ouvre.

2. Dans le volet Nouvelle requête, sélectionnez l’onglet Requêtes, puis développez IoT Hub pour afficher la liste des requêtes par défaut.

   

3. Sélectionnez la requête Récapitulatif de l’erreur. La requête s’affiche dans le volet Éditeur de requête. Sélectionnez Exécuter dans le volet de l’éditeur et observez les résultats de la requête. Développez l’une des lignes pour afficher les détails.

   

   Notes

   Si vous ne voyez aucune erreur, essayez d’exécuter la requête Appareils connectés récemment. Elle doit retourner une ligne pour l’appareil simulé.

Nettoyer les ressources

Pour supprimer toutes les ressources que vous avez créées dans ce tutoriel, supprimez le groupe de ressources. Cette opération supprime toutes les ressources contenues dans le groupe. En l’occurrence, elle supprime le hub IoT, l’espace de travail Log Analytics et le groupe de ressources proprement dit. Si vous avez épinglé des graphiques de métriques au tableau de bord, vous devez les supprimer manuellement en cliquant sur les trois points situés dans le coin supérieur droit de chaque métrique et en sélectionnant Supprimer. Veillez à enregistrer vos modifications après avoir supprimé les graphiques.

Pour supprimer le groupe de ressources, utilisez la commande az group delete.

az group delete --name ContosoResources

Étapes suivantes

Dans ce tutoriel, vous avez appris à utiliser des métriques et des journaux IoT Hub en effectuant les tâches suivantes :

Passez au tutoriel suivant pour découvrir comment tester les fonctionnalités de récupération d’urgence pour IoT Hub.