Suivre les messages appareil-à-cloud Azure IoT avec le suivi distribué (préversion)

Utilisez le suivi distribué (préversion) dans IoT Hub pour monitorer les messages IoT quand ils passent par les services Azure. IoT Hub est l’un des premiers services Azure à prendre en charge le traçage distribué. Lorsque le suivi distribué sera pris en charge par davantage de services Azure, vous pouvez suivre les messages IoT (Internet des objets) dans tous les services Azure qui sont impliqués dans votre solution. Pour plus d’informations sur la fonctionnalité, consultez Qu’est-ce que le suivi distribué ?.

Lorsque vous activez le suivi distribué pour IoT Hub, vous pouvez :

• Monitorez le flux de chaque message dans IoT Hub avec le contexte de trace. Ce contexte de suivi inclut des ID de corrélation qui vous permettent de corréler les événements d’un composant avec les événements d’un autre composant. Vous pouvez l’appliquer à un sous-ensemble ou à l’ensemble des messages d’appareil IoT en utilisant un jumeau d’appareil.
• Journalisez le contexte de trace dans les journaux Azure Monitor.
• Mesurer et comprendre le flux et la latence des messages entre les appareils, IoT Hub et les points de terminaison de routage.

Prérequis

• Un hub IoT Azure créé dans une des régions suivantes.

  • Europe Nord
  • Asie Sud-Est
  • USA Ouest 2

• Un appareil inscrit dans votre hub IoT. Si vous n’avez aucun appareil dans votre hub IoT, suivez les étapes décrites dans Inscrire un appareil et enregistrez la chaîne de connexion de l’appareil pour l’utiliser dans cet article.

• Cet article suppose que vous savez envoyer des messages de télémétrie aux hubs IoT.

• La dernière version de Git.

Considérations et limites concernant la préversion publique

Tenez compte des limitations suivantes pour déterminer si cette fonctionnalité en préversion convient à vos scénarios :

• La proposition d’une norme W3C pour le contexte de suivi est encore au stade d’ébauche.

• Le seul langage de développement pris en charge actuellement par le SDK client est C, dans la branche en préversion publique d’Azure IoT device SDK pour C

• La fonctionnalité de jumeau cloud-à-appareil n’est pas disponible pour le niveau de base d’IoT Hub. Toutefois, IoT Hub continue de journaliser dans Azure Monitor s’il voit un en-tête de contexte de trace correctement composé.

• Pour garantir un fonctionnement efficace, IoT Hub impose une limitation au niveau du taux de journalisation effectuée dans le cadre du traçage distribué.

• La fonctionnalité de suivi distribué est uniquement prise en charge par les hubs IoT créés dans les régions suivantes :

  • Europe Nord
  • Asie Sud-Est
  • USA Ouest 2

Comprendre le traçage distribué Azure IoT

De nombreuses solutions IoT, y compris l’architecture de référence Azure IoT, suivent généralement une variante de l’architecture de microservice. Lorsque votre solution IoT gagne en complexité, vous vous retrouvez à utiliser une dizaine de microservices, voire davantage. Ces microservices peuvent ou non provenir d’Azure.

Il peut être difficile de déterminer à quel endroit les messages IoT ralentissent. Par exemple, supposons que vous disposiez d’une solution IoT qui utilise cinq services Azure différents et 1500 appareils actifs. Chaque appareil envoie 10 messages appareil-à-cloud par seconde, pour un total de 15 000 messages par seconde. Cependant, vous remarquez que votre application web ne voit que 10 000 messages par seconde. Comment trouver le responsable ?

Pour que vous puissiez recréer le flux d’un message IoT dans différents services, chaque service doit propager un ID de corrélation qui identifie le message de façon unique. Une fois qu’Azure Monitor a collecté les ID de corrélation dans un système centralisé, vous pouvez utiliser ces ID pour voir le flux de messages. Cette méthode est appelée modèle de traçage distribué.

En vue de permettre une plus large adoption du traçage distribué, Microsoft contribue à une proposition de norme W3C pour le traçage distribué. Une fois que la prise en charge du suivi distribué est activée pour IoT Hub, il suit ce flux pour chaque message généré :

1. Un message est généré sur l’appareil IoT.
2. L’appareil IoT décide (avec l’aide du cloud) que ce message doit se voir attribuer un contexte de suivi.
3. Le SDK ajoute une valeur tracestate à la propriété du message qui contient l’horodatage de la création de messages.
4. L’appareil IoT envoie le message à IoT Hub.
5. Le message arrive à la passerelle IoT Hub.
6. IoT Hub recherche la valeur tracestate dans les propriétés du message, puis vérifie qu’elle est au bon format. Dans ce cas, IoT Hub génère une valeur globale unique trace-id pour le message ainsi qu’une valeur span-id pour le « tronçon ». IoT Hub enregistre ces valeurs dans les journaux de suivi distribué IoT Hub sous l’opération DiagnosticIoTHubD2C.
7. Une fois que le traitement des messages est terminé, IoT Hub génère une autre valeur span-id, puis la journalise avec la valeur trace-id existante, sous l’opération DiagnosticIoTHubIngress.
8. Si le routage est activé pour le message, IoT Hub écrit des données sur le point de terminaison personnalisé. IoT Hub journalise une autre valeur span-id avec la même valeur trace-id sous la catégorie DiagnosticIoTHubEgress.

Configurer le suivi distribué dans un hub IoT

Dans cette section, vous allez configurer un hub IoT pour qu’il journalise les attributs du suivi distribué (ID de corrélation et horodatages).

1. Sur le portail Azure, accédez à votre hub IoT.

2. Dans le volet gauche de votre hub IoT, faites défiler jusqu’à la section Monitoring, puis sélectionnez Paramètres de diagnostic.

3. Sélectionnez Ajouter le paramètre de diagnostic.

4. Dans la zone Nom du paramètre de diagnostic, entrez un nom pour le nouveau paramètre de diagnostic. Par exemple, entrez DistributedTracingSettings.

   

5. Choisissez une ou plusieurs des options situées sous Détails de la destination pour configurer où les informations des journaux doivent être envoyés :

   • Archiver dans un compte de stockage : configurez le compte de stockage qui doit contenir les informations de journalisation.
   • Diffuser vers un hub d’événements : configurez le hub d’événements qui doit contenir les informations de journalisation.
   • Envoyer à Log Analytics : configurez l’espace de travail Log Analytics qui doit contenir les informations de journalisation.

6. Dans la section Journaux, sélectionnez les opérations que vous souhaitez journaliser.

   Ajoutez le Suivi distribué, puis configurez une durée de Conservation pour les journaux. La durée de conservation des journaux impacte les coûts de stockage.

   

7. Sélectionnez Enregistrer.

8. (Facultatif) Pour voir le flux des messages à différents emplacements, configurez des règles de routage pour au moins deux points de terminaison différents.

Une fois que la journalisation est activée, IoT Hub enregistre un journal lorsqu’un message contenant des propriétés de trace valides est trouvé dans l’une des situations suivantes :

• Le message arrive à la passerelle du hub IoT.
• Le hub IoT traite le message.
• Le message est routé vers des points de terminaison personnalisés. Le routage doit être activé.

Pour plus d’informations sur ces journaux d’activité et ces schémas, consultez Surveiller IoT Hub et Traçage distribué dans les journaux de ressources IoT Hub.

Modifier les options d’échantillonnage

Pour modifier le pourcentage de messages devant être suivis à partir du cloud, vous devez mettre à jour le jumeau d’appareil. Vous pouvez effectuer des mises à jour à l’aide de l’éditeur JSON dans le portail Azure ou SDK du service IoT Hub. Les sous-sections suivantes fournissent des exemples.

Mettre à jour un seul appareil

Vous pouvez utiliser le portail Azure ou l’extension Azure IoT Hub pour Visual Studio Code (VS Code) afin de mettre à jour le taux d’échantillonnage d’un seul appareil.

Mettre à jour en bloc plusieurs appareils

Pour mettre à jour la configuration d’échantillonnage du traçage distribué pour plusieurs appareils, utilisez la configuration automatique des appareils. Suivez ce schéma de jumeaux :

{
    "properties": {
        "desired": {
            "azureiot*com^dtracing^1": {
                "sampling_mode": 1,
                "sampling_rate": 100
            }
        }
    }
}

Interroger et visualiser des traces

Pour voir toutes les traces journalisées par un hub IoT, interrogez le magasin de journaux que vous avez sélectionné dans les paramètres de diagnostic. Cette section montre comment interroger à l’aide de Log Analytics.

Si vous avez configuré Log Analytics avec les journaux de ressource, recherchez les journaux de la catégorie DistributedTracing. Par exemple, la requête suivante montre toutes les traces journalisées :

// All distributed traces 
AzureDiagnostics 
| where Category == "DistributedTracing" 
| project TimeGenerated, Category, OperationName, Level, CorrelationId, DurationMs, properties_s 
| order by TimeGenerated asc  

Voici quelques exemples de journaux dans Log Analytics :

Pour connaître les types de journaux d’activité, consultez Journaux de suivi distribué Azure IoT Hub.

Exécuter un exemple d’application

Dans cette section, vous allez préparer un environnement de développement à utiliser avec le SDK Azure IoT pour le langage C. Ensuite, vous allez modifier un des exemples afin d’activer le suivi distribué dans les messages de télémétrie de votre appareil.

Ces instructions concernent la création de l’exemple sur un système Windows. Pour les autres environnements, consultez Compile the C SDK ou Prepackaged C SDK for Platform Specific Development.

Cloner le code source et initialiser

1. Installez la charge de travail Développement Desktop en C++ pour Visual Studio 2022. Visual Studio 2019 est également pris en charge.

2. Installez CMake. Vérifiez qu’il se trouve dans votre PATH en entrant cmake -version à partir d’une invite de commandes.

3. Ouvrez une invite de commandes ou l’interpréteur de commandes Git Bash. Exécutez les commandes suivantes pour cloner la dernière version de la branche public-preview du dépôt GitHub Azure IoT C SDK :

   git clone -b public-preview https://github.com/Azure/azure-iot-sdk-c.git
   cd azure-iot-sdk-c
   git submodule update --init
   

   Attendez-vous à ce que cette opération prenne plusieurs minutes.

4. Exécutez les commandes suivantes à partir du répertoire azure-iot-sdk-c pour créer un sous-répertoire cmake, puis accédez au dossier cmake :

   mkdir cmake
   cd cmake
   cmake ..
   

   Si CMake ne trouve pas votre compilateur C++, vous pourrez rencontrer des erreurs de build lors de l’exécution de la commande précédente. Si cela se produit, essayez d’exécuter la commande dans l’invite de commandes de Visual Studio.

   Une fois la génération terminée, les dernières lignes de sortie doivent ressembler à ceci :

   $ cmake ..
   -- Building for: Visual Studio 15 2017
   -- Selecting Windows SDK version 10.0.16299.0 to target Windows 10.0.17134.
   -- The C compiler identification is MSVC 19.12.25835.0
   -- The CXX compiler identification is MSVC 19.12.25835.0
   
   ...
   
   -- Configuring done
   -- Generating done
   -- Build files have been written to: E:/IoT Testing/azure-iot-sdk-c/cmake
   

Modifier l’exemple de données de télémétrie pour activer le suivi distribué

Dans cette section, vous modifiez l’exemple iothub_ll_telemetry_sample.c dans le dépôt SDK pour activer le suivi distribué. Vous pouvez également copier une version déjà modifiée de l’exemple à partir du dépôt azure-iot-distributed-tracing-sample.

1. Utilisez un éditeur pour ouvrir le fichier source azure-iot-sdk-c/iothub_client/samples/iothub_ll_telemetry_sample/iothub_ll_telemetry_sample.c.

2. Recherchez la déclaration de la constante connectionString :

   /* Paste in the your iothub connection string  */
   static const char* connectionString = "[device connection string]";
   #define MESSAGE_COUNT        5000
   static bool g_continueRunning = true;
   static size_t g_message_count_send_confirmations = 0;
   

   Remplacez la valeur de la constante connectionString par la chaîne de connexion d’appareil que vous avez enregistrée dans la section Inscrire un appareil du guide de démarrage rapide sur l’envoi de données de télémétrie.

3. Recherchez la ligne de code qui appelle IoTHubDeviceClient_LL_SetConnectionStatusCallback pour inscrire une fonction de rappel d’état de connexion avant la boucle d’envoi de messages. Ajoutez du code sous cette ligne pour appeler IoTHubDeviceClient_LL_EnablePolicyConfiguration et activer le suivi distribué sur l’appareil :

   // Setting connection status callback to get indication of connection to iothub
   (void)IoTHubDeviceClient_LL_SetConnectionStatusCallback(device_ll_handle, connection_status_callback, NULL);
   
   // Enabled the distrubted tracing policy for the device
   (void)IoTHubDeviceClient_LL_EnablePolicyConfiguration(device_ll_handle, POLICY_CONFIGURATION_DISTRIBUTED_TRACING, true);
   
   do
   {
       if (messages_sent < MESSAGE_COUNT)
   

   La fonction IoTHubDeviceClient_LL_EnablePolicyConfiguration active des stratégies pour certaines fonctionnalités IoT Hub qui sont configurées via des jumeaux d’appareil. Une fois que vous aurez activé POLICY_CONFIGURATION_DISTRIBUTED_TRACING avec la ligne de code supplémentaire, le comportement de suivi de l’appareil reflétera les modifications de suivi distribué qui ont été apportées au jumeau d’appareil.

4. Pour continuer d’exécuter l’exemple d’application sans épuiser votre quota, ajoutez un délai d’une seconde à la fin de la boucle d’envoi de messages :

       else if (g_message_count_send_confirmations >= MESSAGE_COUNT)
       {
           // After all messages are all received stop running
           g_continueRunning = false;
       }
   
       IoTHubDeviceClient_LL_DoWork(device_ll_handle);
       ThreadAPI_Sleep(1000);
   
   } while (g_continueRunning);
   

Compilation et exécution

1. Accédez au répertoire du projet iothub_ll_telemetry_sample à partir du répertoire CMake (azure-iot-sdk-c/cmake) créé précédemment, puis compilez l’exemple :

   cd iothub_client/samples/iothub_ll_telemetry_sample
   cmake --build . --target iothub_ll_telemetry_sample --config Debug
   

2. Exécutez l’application. L’appareil envoie des données de télémétrie qui prennent en charge le suivi distribué.

   Debug/iothub_ll_telemetry_sample.exe
   

3. Gardez l’application active. Vous pouvez examiner les messages envoyés au hub IoT dans la fenêtre de console.

Pour une application cliente qui peut recevoir des décisions d’échantillonnage du cloud, essayez l’exemple iothub_devicetwin_sample.c dans le dépôt d’exemples de suivi distribué.

Solution de contournement pour les clients non-Microsoft

Si vous n’utilisez pas le SDK C, l’implémentation de la fonctionnalité de suivi distribué sera plus complexe. Nous ne le recommandons pas.

Tout d’abord, vous devez implémenter toutes les primitives de protocole IoT Hub dans vos messages en suivant le guide de développement Créer et lire des messages IoT Hub. Ensuite, modifiez les propriétés de protocole dans les messages MQTT et AMQP pour ajouter tracestate en tant que propriété système.

Plus précisément :

• Pour MQTT, ajoutez %24.tracestate=timestamp%3d1539243209 à la rubrique du message. Remplacez 1539243209 par l’heure de création du message au format d’horodatage Unix. Pour voir un exemple, reportez-vous à l’implémentation dans le SDK C.
• Pour AMQP, ajoutez key("tracestate") et value("timestamp=1539243209") en tant qu’annotation de message. Pour obtenir une implémentation de référence, consultez le fichier uamqp_messaging.c.

Pour contrôler le pourcentage de messages contenant cette propriété, implémentez une logique qui écoute les événements initiés par le cloud, tels que les mises à jour des jumeaux.

Étapes suivantes

• Pour plus d’informations sur le modèle général de traçage distribué dans les microservices, consultez Microservice architecture pattern: distributed tracing.