Collecter à distance les journaux de diagnostic d’appareils avec Device Update pour IoT Hub

Découvrez comment lancer une opération de journalisation avec Device Update pour IoT Hub et afficher les journaux collectés dans Stockage Blob Azure.

Prérequis

• Accès à un hub IoT avec Device Update pour IoT Hub activé.
• Un appareil IoT (ou simulateur) provisionné pour Device Update dans IOT Hub et implémentation de l’interface de diagnostic.
• Un compte Stockage Blob Azure sous le même abonnement que votre compte Device Update pour IoT Hub.

Remarque

La fonctionnalité de collecte de journaux à distance n’est actuellement compatible qu’avec les appareils qui implémentent l’interface de diagnostic et qui peuvent charger des fichiers vers Stockage Blob Azure. L’implémentation de l’agent de référence s’attend également à ce que l’appareil écrive les fichiers journaux dans un chemin de fichier spécifié par l’utilisateur sur l’appareil.

Azure portal

Navigateurs pris en charge :

• Microsoft Edge
• Google Chrome

Azure CLI

Environnement Azure CLI :

• Utilisez l’environnement Bash dans Azure Cloud Shell.

  

• Ou, si vous préférez exécuter les commandes de référence CLI localement, installez l’interface Azure CLI

  • Connectez-vous à l’interface Azure CLI à l’aide de la commande az login.
  • 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.
  • Lorsque vous y êtes invité, installez les extensions Azure CLI lors de la première utilisation. Les commandes de cet article utilisent l’extension CLI azure-iot. Exécutez az extension update --name azure-iot pour vous assurer que vous disposez de la version la plus récente de l’extension.

Conseil

Dans cet article, les commandes Azure CLI utilisent la barre oblique inverse \ pour la continuation de ligne afin que les arguments de commande soient plus faciles à lire. Cette syntaxe fonctionne dans les environnements Bash. Si vous exécutez ces commandes dans PowerShell, remplacez chacune des barres obliques inverses par un guillemet inversé (`), ou supprimez-les entièrement.

Lier votre compte Stockage Blob Azure à votre instance Device Update

Pour pouvoir utiliser la fonctionnalité de collecte de journaux à distance, vous devez d’abord lier un compte Stockage Blob Azure à votre instance Device Update. C’est dans ce compte Stockage Blob Azure que vos appareils chargeront les journaux de diagnostic.

Azure portal

1. Dans le Portail Azure, accédez à votre Device Update pour IoT Hub compte.

2. Sélectionnez Instance sous la section Gestion des instances du volet de navigation.

3. Sélectionnez votre instance Device Update dans la liste, puis Configurer les diagnostics.

4. Sélectionnez l’onglet Diagnostics des clients, puis Sélectionner le compte de stockage Azure.

5. Choisissez le compte de stockage de votre choix dans la liste, puis sélectionnez Enregistrer.

6. Une fois de retour dans la liste d’instances, sélectionnez Actualiser jusqu’à ce que l’état de provisionnement de l’instance indique « Réussi ». Cela prend généralement 2 à 3 minutes.

Azure CLI

Utilisez la commande az iot du instance create pour configurer les diagnostics de votre instance Device Update.

Conseil

Vous pouvez utiliser la commande az iot du instance create sur une instance Device Update existante et configurer l’instance avec les paramètres mis à jour.

Remplacez les espaces réservés suivants par vos propres informations :

• <account_name>: Le nom de votre compte Device Update.
• <instance_name>: Le nom de votre instance Device Update.
• <storage_id>: L'ID de ressource du compte de stockage où les journaux de diagnostic seront stockés. Vous pouvez récupérer l'ID de la ressource en utilisant la commande az storage show et en demandant la valeur de l'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>

Configurer la collecte des journaux

L'agent de mise à jour du dispositif fait référence à un fichier de configuration sur le dispositif, situé à /etc/adu/du-diagnostics-config.json dans l'agent de référence.

Chemins des fichiers de collection de journaux

L’agent Device Update collecte les fichiers à partir de chemins spécifiques sur l’appareil quand il reçoit le signal indiquant le démarrage du chargement des journaux du service Device Update. Ces chemins d’accès de fichier sont définis dans le fichier de configuration des diagnostics.

Dans le fichier de configuration, chaque fichier journal à collecter et à télécharger est représenté comme un objetlogComponent avec les propriétés componentName et logPath. Cette configuration peut être modifiée à volonté.

Taille maximale du fichier journal

L’agent Device Update collecte uniquement les fichiers journaux ne dépassant pas une certaine taille de fichier. Cette taille de fichier maximale est définie dans le fichier de configuration des diagnostics.

Le paramètre approprié « maxKilobytesToUploadPerLogPath » s’applique à chaque objet logComponent et peut être modifié au besoin.

Créer une opération de journalisation

Les opérations de journalisation sont une action pilotée par le service que vous pouvez demander à vos appareils IoT d'exécuter par le biais du service Device Update. Pour une explication plus détaillée du fonctionnement des opérations de journalisation, voir Diagnostics de mise à jour du dispositif.

Azure portal

1. Accédez à votre hub IoT et sélectionnez l’onglet Mises à jour sous la section Gestion des appareils du volet de navigation.

2. Sélectionnez l’onglet Diagnostics dans l’interface utilisateur. Si vous ne voyez pas l’onglet Diagnostics, vérifiez que vous utilisez la version la plus récente de l’interface utilisateur Device Update pour IoT Hub. Si vous voyez « Les diagnostics doivent être activés pour cette instance Device Update », vérifiez que vous avez lié un compte Stockage Blob Azure à votre instance Device Update.

3. Sélectionnez Ajouter une opération de chargement de journal pour accéder à la page de création d’une opération de journalisation.

4. Entrez un nom (ID) et une description pour votre nouvelle opération de journalisation, puis sélectionnez Ajouter des appareils pour sélectionner les appareils IOT à partir desquels vous souhaitez collecter les journaux de diagnostic.

5. Sélectionnez Ajouter.

6. De retour sous l’onglet Diagnostics, sélectionnez Actualiser jusqu’à ce que l’opération de journalisation apparaisse dans la table des opérations.

7. Quand l’état de l’opération indique Réussite ou Échec, sélectionnez le nom de l’opération pour voir les détails. L’état d’une opération indique « Réussite » uniquement si tous les appareils ciblés ont correctement chargé les journaux. Si certains dispositifs ciblés ont réussi et d'autres ont échoué, l'opération de journalisation sera marquée "Échec". Vous pouvez utiliser la page de détails de l'opération de journalisation pour voir quels dispositifs ont réussi et lesquels ont échoué.

8. Dans les détails de l’opération de journalisation, vous pouvez voir l’état spécifique à l’appareil et le chemin de l’emplacement des journaux. Ce chemin correspond au chemin du répertoire virtuel dans votre compte Stockage Blob Azure dans lequel les journaux de diagnostic ont été chargés.

Azure CLI

Utilisez la commande az iot du device log collect pour configurer une opération de collecte des journaux de diagnostic.

La commande device log collect prend les trois arguments suivants :

• --account : nom du compte Device Update.
• --instance : nom de l’instance Device Update.
• --log-collection-id : nom de l’opération de collecte des journaux.
• --agent-id : paires clé=valeur qui identifient un agent Device Update cible pour cette opération de collecte des journaux. Utilisez deviceId=<device name> si l’agent a une identité d’appareil. Utilisez deviceId=<device name> moduleId=<module name> si l’agent a une identité de module. Vous pouvez utiliser le paramètre --agent-id plusieurs fois pour cibler plusieurs appareils.

Par exemple :

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>

Utilisez az iot du device log show pour afficher les détails d’une opération de collecte des journaux de diagnostic spécifique.

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

Afficher et exporter les journaux de diagnostic collectés

1. Une fois l’opération de journalisation réussie, accédez à votre compte Stockage Blob Azure.

2. Sélectionnez Conteneurs sous la section Stockage des données du volet de navigation.

3. Sélectionnez le conteneur portant le même nom que votre instance Device Update.

4. Utilisez le chemin d’emplacement des journaux indiqué dans les détails de l’opération de journalisation pour accéder au bon répertoire contenant les journaux. Par défaut, la fonctionnalité de collecte des journaux à distance indique aux appareils ciblés de charger les journaux de diagnostic en utilisant le modèle de chemin de répertoire suivant : Conteneur de stockage d’objets blob/ID d’appareil cible/ID d’opération de journalisation/Chemin des journaux sur l’appareil

5. Si vous n’avez pas modifié le composant de diagnostic de l’agent Device Update, l’appareil tente de charger deux fichiers journaux de texte en clair en réponse à une opération de journalisation : le journal de diagnostic de l’agent Device Update (aduc.log) et le journal de diagnostic de l’agent DO (do-agent.log). Pour plus d’informations sur les fichiers journaux collectés par l’agent de référence Device Update, consultez la page expliquant le concept des diagnostics dans Device Update.

6. Pour voir le contenu du fichier journal, sélectionnez le nom du fichier, puis sélectionnez l’élément de menu (points de suspension) et cliquez sur Afficher/modifier. Vous pouvez également télécharger ou supprimer le fichier journal en sélectionnant les options étiquetées correspondantes.

   

Étapes suivantes

Pour en savoir plus sur les fonctionnalités de diagnostic de Device Update, consultez la vue d’ensemble des fonctionnalités de diagnostic de mise à jour d’appareil