Ajoutez des annotations et des métadonnées aux segments avec le SDK X-Ray pour Python

Vous pouvez utiliser des annotations et des métadonnées pour enregistrer des informations supplémentaires sur les demandes, l'environnement ou votre application. Vous pouvez ajouter des annotations et des métadonnées aux segments créés par le SDK X-Ray ou aux sous-segments personnalisés que vous créez.

Les annotations sont des paires clé-valeur avec des chaînes, des nombres ou des valeurs booléennes. Les annotations sont indexées pour être utilisées avec les expressions de filtre. Utilisez les annotations pour enregistrer les données que vous souhaitez utiliser pour regrouper les suivis dans la console ou lors de l'appel de l'API GetTraceSummaries.

Les métadonnées sont des paires clé-valeur qui peuvent contenir des valeurs de n'importe quel type, y compris des objets et des listes, mais qui ne sont pas indexées pour être utilisées avec des expressions de filtre. Utilisez les métadonnées pour enregistrer des données supplémentaires que vous souhaitez stocker dans le traçage, mais que vous n'avez pas besoin d'utiliser pour la recherche.

En plus des annotations et des métadonnées, vous pouvez également enregistrer les chaînes d'ID utilisateur sur des segments. Les ID utilisateur sont enregistrés dans un champ distinct des segments et indexés en vue d'une utilisation avec la recherche.

Enregistrer des annotations avec le SDK X-Ray pour Python

Utilisez les annotations pour enregistrer les informations sur les segments ou sous-segments qui doivent être indexés pour la recherche.

Exigences liées aux annotations

• Clés — La clé d'une annotation X-Ray peut comporter jusqu'à 500 caractères alphanumériques. Vous ne pouvez pas utiliser d'espaces ou de symboles autres que le trait de soulignement (_).

• Valeurs — La valeur d'une annotation X-Ray peut comporter jusqu'à 1 000 caractères Unicode.

• Nombre d'annotations : vous pouvez utiliser jusqu'à 50 annotations par trace.

Pour enregistrer les annotations

1. Obtenez une référence au segment ou sous-segment en cours à partir d'xray_recorder.

   from aws_xray_sdk.core import xray_recorder
   ...
   document = xray_recorder.current_segment()

   or

   from aws_xray_sdk.core import xray_recorder
   ...
   document = xray_recorder.current_subsegment()

2. Appelez put_annotation avec une clé de type chaîne et une valeur de type booléen, numérique ou chaîne.

   document.put_annotation("mykey", "my value");

Vous pouvez également utiliser la méthode put_annotation sur le xray_recorder. Cette méthode enregistre les annotations sur le sous-segment actuel ou, si aucun sous-segment n'est ouvert, sur le segment.

xray_recorder.put_annotation("mykey", "my value");

Le kit de développement logiciel enregistre les annotations sous forme de paires clé-valeur dans un objet annotations du document de segment. Si vous appelez deux fois put_annotation avec la même clé, les valeurs précédemment enregistrées sur le même segment ou sous-segment sont remplacées.

Pour rechercher les suivis ayant des annotations avec des valeurs spécifiques, utilisez le mot clé annotations.key dans une expression de filtre.

Enregistrement de métadonnées avec le SDK X-Ray pour Python

Utilisez les métadonnées pour enregistrer des informations sur les segments ou sous-segments qui n'ont pas besoin d'être indexés pour la recherche. Les valeurs des métadonnées peuvent être de type chaîne, valeur numérique, valeur booléenne ou tout objet à même d'être sérialisé en un tableau ou objet JSON.

Pour enregistrer les métadonnées

1. Obtenez une référence au segment ou sous-segment en cours à partir d'xray_recorder.

   from aws_xray_sdk.core import xray_recorder
   ...
   document = xray_recorder.current_segment()

   or

   from aws_xray_sdk.core import xray_recorder
   ...
   document = xray_recorder.current_subsegment()

2. Appelez put_metadata avec une clé de type chaîne, une valeur de type booléen, numérique, chaîne ou objet et un espace de noms de type chaîne.

   document.put_metadata("my key", "my value", "my namespace");

   or

   Appelez put_metadata avec seulement une clé et une valeur.

   document.put_metadata("my key", "my value");

Vous pouvez également utiliser la méthode put_metadata sur le xray_recorder. Cette méthode enregistre les métadonnées sur le sous-segment actuel ou, si aucun sous-segment n'est ouvert, sur le segment.

xray_recorder.put_metadata("my key", "my value");

Si vous ne spécifiez pas d'espace de noms, le kit de développement logiciel utilise default. Si vous appelez deux fois put_metadata avec la même clé, les valeurs précédemment enregistrées sur le même segment ou sous-segment sont remplacées.

Enregistrement des identifiants utilisateur avec le SDK X-Ray pour Python

Enregistrez les ID utilisateur sur les segments de la demande afin d'identifier l'utilisateur à l'origine de la demande.

Pour enregistrer les ID utilisateur

1. Obtenez une référence au segment en cours à partir d'xray_recorder.

   from aws_xray_sdk.core import xray_recorder
   ...
   document = xray_recorder.current_segment()

2. Appelez setUser avec l'ID de type chaîne de l'utilisateur ayant envoyé la demande.

   document.set_user("U12345");

Vous pouvez appeler set_user dans vos contrôleurs pour enregistrer l'ID utilisateur dès que votre application commence le traitement d'une demande.

Pour rechercher les suivis d'un ID utilisateur, utilisez le mot clé user dans une expression de filtre.