Récupérer les journaux des déploiements IoT Edge
S’applique à :
IoT Edge 1.5 IoT Edge 1.4
Important
IoT Edge 1.5 LTS et IoT Edge 1.4 LTS sont des versions prises en charge. IoT Edge 1.4 LTS sera en fin de vie le 12 novembre 2024. Si vous utilisez une version antérieure, consultez l’article Mettre à jour IoT Edge.
Récupérez les journaux de vos déploiements IoT Edge sans avoir besoin d’un accès physique ou SSH à l’appareil à l’aide des méthodes directes incluses dans le module de l’agent IoT Edge. Les méthodes directes sont implémentées sur l’appareil, puis peuvent être appelées à partir du cloud. L’agent IoT Edge comprend des méthodes directes qui vous aident à surveiller et gérer vos appareils IoT Edge à distance. Les méthodes directes présentées dans cet article sont généralement disponibles avec la version 1.0.10.
Pour plus d’informations sur les méthodes directes, leur utilisation et la façon de les implémenter dans vos propres modules, consultez Comprendre et appeler des méthodes directes à partir d’IoT Hub.
Les noms de ces méthodes directes respectent la casse.
Format de journalisation recommandé
Bien qu’il ne soit pas obligatoire, pour une meilleure compatibilité avec cette fonction, le format de journalisation recommandé est le suivant :
<{Log Level}> {Timestamp} {Message Text}
{Timestamp} doit être au format yyyy-MM-dd HH:mm:ss.fff zzz, et {Log Level} doit suivre le tableau ci-dessous, qui dérive ses niveaux de gravité du Code de gravité dans la norme Syslog.
| Valeur | Niveau de gravité |
|---|---|
| 0 | Urgence |
| 1 | Alerte |
| 2 | Critique |
| 3 | Error |
| 4 | Avertissement |
| 5 | Prévenir |
| 6 | Informationnel |
| 7 | Déboguer |
La classe de journalisation dans IoT Edge sert d’implémentation canonique.
Récupérer les journaux de module
Utilisez la méthode directe GetModuleLogs pour récupérer les journaux d’un module IoT Edge.
Conseil
Utilisez les options de filtre since et until pour limiter la plage des journaux récupérés. L’appel de cette méthode directe sans limites a pour effet de récupérer tous les journaux, ce qui peut être conséquent, long ou coûteux.
La page de résolution des problèmes d’IoT Edge dans le portail Azure fournit une expérience simplifiée pour afficher les journaux du module. Pour plus d’informations, consultez Surveillance et résolution des problèmes des appareils IoT Edge sur le Portail Azure.
Cette méthode accepte une charge utile JSON avec le schéma suivant :
{
"schemaVersion": "1.0",
"items": [
{
"id": "regex string",
"filter": {
"tail": "int",
"since": "string",
"until": "string",
"loglevel": "int",
"regex": "regex string"
}
}
],
"encoding": "gzip/none",
"contentType": "json/text"
}
| Nom | Type | Description |
|---|---|---|
| schemaVersion | string | Paramètre à définir sur 1.0 |
| items | Tableau JSON | Tableau avec les tuples id et filter. |
| id | string | Expression régulière qui fournit le nom du module. Il peut correspondre à plusieurs modules sur un périphérique. Le format Expressions régulières .NET est attendu. En présence de plusieurs éléments dont l’ID correspond au même module, seules les options de filtre du premier ID correspondant seront appliquées à ce module. |
| filter | Section JSON | Filtres de journal à appliquer aux modules correspondant à l’expression régulière id dans le tuple. |
| tail | entier | Nombre de lignes de journal dans le passé à récupérer à partir de la dernière. FACULTATIF. |
| since | string | Retourne uniquement les journaux depuis cette heure, sous la forme d’un timestamp rfc3339, d’un timestamp UNIX ou d’une durée (jours (d) heures (h) minutes (m)). Par exemple, une durée d’un jour, 12 heures et 30 minutes peut être spécifiée comme suit : 1 jour 12 heures 30 minutes ou 1d 12h 30m. Si tail et since sont spécifiés, les journaux sont d’abord récupérés à l’aide de la valeur since. Ensuite, la valeur tail est appliquée au résultat, et le résultat final est retourné. FACULTATIF. |
| until | string | Retourne uniquement les journaux avant l’heure spécifiée, sous la forme d’un timestamp rfc3339, d’un timestamp UNIX ou d’une durée (jours (d) heures (h) minutes (m)). Par exemple, une durée de 90 minutes peut être spécifiée comme suit : 90 minutes ou 90m. Si tail et since sont spécifiés, les journaux sont d’abord récupérés à l’aide de la valeur since. Ensuite, la valeur tail est appliquée au résultat, et le résultat final est retourné. FACULTATIF. |
| loglevel | entier | Filtre les lignes de journal égales au niveau de journal spécifié. Les lignes de journal doivent suivre le format de journalisation recommandé et utiliser la norme Niveau de gravité Syslog. Si vous devez filtrer par plusieurs valeurs de gravité au niveau du journal, puis vous appuyer sur la correspondance des expressions régulières, à condition que le module respecte un format cohérent lors de la journalisation de niveaux de gravité différents. FACULTATIF. |
| regex | string | Filtre les lignes de journal dont le contenu correspond à l’expression régulière spécifiée à l’aide du format Expressions régulières .NET. FACULTATIF. |
| encodage | string | gzip ou none. La valeur par défaut est none. |
| contentType | string | json ou text. La valeur par défaut est text. |
Remarque
Si le contenu des journaux dépasse la limite de taille de réponse des méthodes directes, qui est actuellement de 128 ko, la réponse retourne une erreur.
Une récupération réussie des journaux retourne un « état » : 200 suivi d’une charge utile contenant les journaux récupérés à partir du module, filtrés par les paramètres que vous spécifiez dans votre demande.
Par exemple :
az iot hub invoke-module-method --method-name 'GetModuleLogs' -n <hub name> -d <device id> -m '$edgeAgent' --method-payload \
'
{
"schemaVersion": "1.0",
"items": [
{
"id": "edgeAgent",
"filter": {
"tail": 10
}
}
],
"encoding": "none",
"contentType": "text"
}
'
Dans le portail Azure, appelez la méthode avec le nom de la méthode GetModuleLogs et la charge utile JSON suivante :
{
"schemaVersion": "1.0",
"items": [
{
"id": "edgeAgent",
"filter": {
"tail": 10
}
}
],
"encoding": "none",
"contentType": "text"
}
Vous pouvez également canaliser la sortie CLI vers des utilitaires Linux, comme gzip, pour traiter une réponse compressée. Par exemple :
az iot hub invoke-module-method \
--method-name 'GetModuleLogs' \
-n <hub name> \
-d <device id> \
-m '$edgeAgent' \
--method-payload '{"contentType": "text","schemaVersion": "1.0","encoding": "gzip","items": [{"id": "edgeHub","filter": {"since": "2d","tail": 1000}}],}' \
-o tsv --query 'payload[0].payloadBytes' \
| base64 --decode \
| gzip -d
Charger les journaux de module
Utilisez la méthode directe UploadModuleLogs pour envoyer les journaux demandés à un conteneur Stockage Blob Azure spécifié.
Remarque
Utilisez les options de filtre since et until pour limiter la plage des journaux récupérés. L’appel de cette méthode directe sans limites a pour effet de récupérer tous les journaux, ce qui peut être conséquent, long ou coûteux.
Pour charger des journaux à partir d’un appareil situé derrière un appareil de passerelle, vous devez configurer les modules de proxy d’API et de stockage d’objets blob sur l’appareil de couche supérieure. Ces modules acheminent les journaux entre votre appareil de couche inférieure et votre stockage cloud via votre appareil de passerelle.
Cette méthode accepte une charge utile JSON similaire à GetModuleLogs, avec l’ajout de la clé « sasUrl » :
{
"schemaVersion": "1.0",
"sasUrl": "Full path to SAS URL",
"items": [
{
"id": "regex string",
"filter": {
"tail": "int",
"since": "string",
"until": "string",
"loglevel": "int",
"regex": "regex string"
}
}
],
"encoding": "gzip/none",
"contentType": "json/text"
}
| Nom | Type | Description |
|---|---|---|
| sasURL | chaîne (URI) | URL de signature d’accès partagé avec accès en écriture au conteneur Stockage Blob Azure. |
Une demande réussie de chargement des journaux retourne un « état » : 200 suivi d’une charge utile avec le schéma suivant :
{
"status": "string",
"message": "string",
"correlationId": "GUID"
}
| Nom | Type | Description |
|---|---|---|
| status | string | NotStarted, Running, Completed, Failed ou Unknown. |
| message | string | Message en cas d’erreur, chaîne vide dans le cas contraire. |
| correlationId | string | ID à interroger pour obtenir l’état de la demande de chargement. |
Par exemple :
L’appel suivant charge les 100 dernières lignes de journal de tous les modules, au format JSON compressé :
az iot hub invoke-module-method --method-name UploadModuleLogs -n <hub name> -d <device id> -m '$edgeAgent' --method-payload \
'
{
"schemaVersion": "1.0",
"sasUrl": "<sasUrl>",
"items": [
{
"id": ".*",
"filter": {
"tail": 100
}
}
],
"encoding": "gzip",
"contentType": "json"
}
'
L’appel suivant charge les 100 dernières lignes de journal d’edgeAgent et edgeHub avec les 1 000 dernières lignes de journal du module tempSensor dans un format de texte non compressé :
az iot hub invoke-module-method --method-name UploadModuleLogs -n <hub name> -d <device id> -m '$edgeAgent' --method-payload \
'
{
"schemaVersion": "1.0",
"sasUrl": "<sasUrl>",
"items": [
{
"id": "edge",
"filter": {
"tail": 100
}
},
{
"id": "tempSensor",
"filter": {
"tail": 1000
}
}
],
"encoding": "none",
"contentType": "text"
}
'
Dans le portail Azure, appelez la méthode avec le nom de la méthode UploadModuleLogs et la charge utile JSON suivante après avoir rempli la clé sasURL avec vos informations :
{
"schemaVersion": "1.0",
"sasUrl": "<sasUrl>",
"items": [
{
"id": "edgeAgent",
"filter": {
"tail": 10
}
}
],
"encoding": "none",
"contentType": "text"
}
Charger les diagnostics du pack de support
Utilisez la méthode directe UploadSupportBundle pour regrouper et charger un fichier zip des journaux du module IoT Edge dans un conteneur Stockage Blob Azure disponible. Cette méthode directe exécute la commande iotedge support-bundle sur votre appareil IoT Edge pour récupérer les journaux.
Remarque
Pour charger des journaux à partir d’un appareil situé derrière un appareil de passerelle, vous devez configurer les modules de proxy d’API et de stockage d’objets blob sur l’appareil de couche supérieure. Ces modules acheminent les journaux entre votre appareil de couche inférieure et votre stockage cloud via votre appareil de passerelle.
Cette méthode accepte une charge utile JSON avec le schéma suivant :
{
"schemaVersion": "1.0",
"sasUrl": "Full path to SAS url",
"since": "2d",
"until": "1d",
"edgeRuntimeOnly": false
}
| Nom | Type | Description |
|---|---|---|
| schemaVersion | string | Paramètre à définir sur 1.0 |
| sasURL | chaîne (URI) | URL de signature d’accès partagé avec accès en écriture au conteneur Stockage Blob Azure. |
| since | string | Retourne uniquement les journaux depuis cette heure, sous la forme d’un timestamp rfc3339, d’un timestamp UNIX ou d’une durée (jours (d) heures (h) minutes (m)). Par exemple, une durée d’un jour, 12 heures et 30 minutes peut être spécifiée comme suit : 1 jour 12 heures 30 minutes ou 1d 12h 30m. FACULTATIF. |
| until | string | Retourne uniquement les journaux avant l’heure spécifiée, sous la forme d’un timestamp rfc3339, d’un timestamp UNIX ou d’une durée (jours (d) heures (h) minutes (m)). Par exemple, une durée de 90 minutes peut être spécifiée comme suit : 90 minutes ou 90m. FACULTATIF. |
| edgeRuntimeOnly | booléen | Si la valeur est true, retourne uniquement les journaux de l’agent Edge, du hub Edge et du démon de sécurité Edge. Valeur par défaut : false. FACULTATIF. |
Important
Le pack de support IoT Edge peut contenir des informations d’identification personnelle.
Une demande réussie de chargement des journaux retourne un « état » : 200 suivi d’une charge utile avec le même schéma que la réponse UploadModuleLogs :
{
"status": "string",
"message": "string",
"correlationId": "GUID"
}
| Nom | Type | Description |
|---|---|---|
| status | string | NotStarted, Running, Completed, Failed ou Unknown. |
| message | string | Message en cas d’erreur, chaîne vide dans le cas contraire. |
| correlationId | string | ID à interroger pour obtenir l’état de la demande de chargement. |
Par exemple :
az iot hub invoke-module-method --method-name 'UploadSupportBundle' -n <hub name> -d <device id> -m '$edgeAgent' --method-payload \
'
{
"schemaVersion": "1.0",
"sasUrl": "Full path to SAS url",
"since": "2d",
"until": "1d",
"edgeRuntimeOnly": false
}
'
Dans le portail Azure, appelez la méthode avec le nom de la méthode UploadSupportBundle et la charge utile JSON suivante après avoir rempli la clé sasURL avec vos informations :
{
"schemaVersion": "1.0",
"sasUrl": "Full path to SAS url",
"since": "2d",
"until": "1d",
"edgeRuntimeOnly": false
}
Récupérer l’état de la demande de chargement
Utilisez la méthode directe GetTaskStatus pour interroger l’état d’une demande de chargement des journaux. La charge utile de la demande GetTaskStatus utilise le paramètre correlationId de la demande de chargement des journaux pour récupérer l’état de la tâche. Le correlationId est retourné en réponse à l’appel de la méthode directe UploadModuleLogs.
Cette méthode accepte une charge utile JSON avec le schéma suivant :
{
"schemaVersion": "1.0",
"correlationId": "<GUID>"
}
Une demande réussie de chargement des journaux retourne un « état » : 200 suivi d’une charge utile avec le même schéma que la réponse UploadModuleLogs :
{
"status": "string",
"message": "string",
"correlationId": "GUID"
}
| Nom | Type | Description |
|---|---|---|
| status | string | L’un des NotStarted, Running, Completed, Failed, Annulé ou or Unknown. |
| message | string | Message en cas d’erreur, chaîne vide dans le cas contraire. |
| correlationId | string | ID à interroger pour obtenir l’état de la demande de chargement. |
Par exemple :
az iot hub invoke-module-method --method-name 'GetTaskStatus' -n <hub name> -d <device id> -m '$edgeAgent' --method-payload \
'
{
"schemaVersion": "1.0",
"correlationId": "<GUID>"
}
'
Dans le portail Azure, appelez la méthode avec le nom de la méthode GetTaskStatus et la charge utile JSON suivante après avoir rempli le GUID avec vos informations :
{
"schemaVersion": "1.0",
"correlationId": "<GUID>"
}
Étapes suivantes
Propriétés des jumeaux de module de l’agent IoT Edge et du hub IoT Edge