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

Vous pouvez enregistrer des informations supplémentaires sur les demandes, l'environnement ou votre application à l'aide d'annotations et de métadonnées. Vous pouvez ajouter des annotations et des métadonnées aux segments SDK créés par le 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 des annotations pour enregistrer les données que vous souhaitez utiliser pour regrouper les traces dans la console ou lorsque vous appelez le GetTraceSummariesAPI.

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. IDsLes utilisateurs sont enregistrés dans un champ distinct sur les segments et sont indexés pour être utilisés dans le cadre de la recherche.

Enregistrer des annotations avec X-Ray SDK pour Java

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 qu'un point ou un point (.)

• 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'AWSXRay.

   import com.amazonaws.xray.AWSXRay;
   import com.amazonaws.xray.entities.Segment;
   ...
   Segment document = AWSXRay.getCurrentSegment();

   or

   import com.amazonaws.xray.AWSXRay;
   import com.amazonaws.xray.entities.Subsegment;
   ...
   Subsegment document = AWSXRay.getCurrentSubsegment();

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

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

   L'exemple suivant montre comment appeler putAnnotation avec une clé String qui inclut un point et une valeur booléenne, numérique ou de chaîne.

   document.putAnnotation("testkey.test", "my value");

SDKEnregistre les annotations sous forme de paires clé-valeur dans un annotations objet du document segmenté. Si vous appelez deux fois putAnnotation 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é annotation[key] dans une expression de filtre.

Exemple src/main/java/scorekeep/GameModel.java— Annotations et métadonnées

import com.amazonaws.xray.AWSXRay;
import com.amazonaws.xray.entities.Segment;
import com.amazonaws.xray.entities.Subsegment;
...
  public void saveGame(Game game) throws SessionNotFoundException {
    // wrap in subsegment
    Subsegment subsegment = AWSXRay.beginSubsegment("## GameModel.saveGame");
    try {
      // check session
      String sessionId = game.getSession();
      if (sessionModel.loadSession(sessionId) == null ) {
        throw new SessionNotFoundException(sessionId);
      }
      Segment segment = AWSXRay.getCurrentSegment();
      subsegment.putMetadata("resources", "game", game);
      segment.putAnnotation("gameid", game.getId());
      mapper.save(game);
    } catch (Exception e) {
      subsegment.addException(e);
      throw e;
    } finally {
      AWSXRay.endSubsegment();
    }
  }

Enregistrer des métadonnées avec X-Ray SDK pour Java

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 de métadonnées peuvent être des chaînes, des nombres, des booléens ou tout autre objet pouvant être sérialisé dans un JSON objet ou un tableau.

Pour enregistrer les métadonnées

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

   import com.amazonaws.xray.AWSXRay;
   import com.amazonaws.xray.entities.Segment;
   ...
   Segment document = AWSXRay.getCurrentSegment();

   or

   import com.amazonaws.xray.AWSXRay;
   import com.amazonaws.xray.entities.Subsegment;
   ...
   Subsegment document = AWSXRay.getCurrentSubsegment();

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

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

   or

   Appelez putMetadata avec seulement une clé et une valeur.

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

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

Exemple src/main/java/scorekeep/GameModel.java— Annotations et métadonnées

import com.amazonaws.xray.AWSXRay;
import com.amazonaws.xray.entities.Segment;
import com.amazonaws.xray.entities.Subsegment;
...
  public void saveGame(Game game) throws SessionNotFoundException {
    // wrap in subsegment
    Subsegment subsegment = AWSXRay.beginSubsegment("## GameModel.saveGame");
    try {
      // check session
      String sessionId = game.getSession();
      if (sessionModel.loadSession(sessionId) == null ) {
        throw new SessionNotFoundException(sessionId);
      }
      Segment segment = AWSXRay.getCurrentSegment();
      subsegment.putMetadata("resources", "game", game);
      segment.putAnnotation("gameid", game.getId());
      mapper.save(game);
    } catch (Exception e) {
      subsegment.addException(e);
      throw e;
    } finally {
      AWSXRay.endSubsegment();
    }
  }

Utilisateur enregistrant IDs avec X-Ray SDK pour Java

Enregistrez les segments utilisateur IDs sur demande pour identifier l'utilisateur qui a envoyé la demande.

Pour enregistrer un utilisateur IDs

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

   import com.amazonaws.xray.AWSXRay;
   import com.amazonaws.xray.entities.Segment;
   ...
   Segment document = AWSXRay.getCurrentSegment();

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

   document.setUser("U12345");

Vous pouvez appeler setUser dans vos contrôleurs pour enregistrer l'ID utilisateur dès que votre application commence le traitement d'une demande. Si vous n'utilisez le segment que pour définir l'ID utilisateur, vous pouvez chaîner les appels sur une seule ligne.

Exemple src/main/java/scorekeep/ .java — ID utilisateur MoveController

import com.amazonaws.xray.AWSXRay;
...
  @RequestMapping(value="/{userId}", method=RequestMethod.POST)
  public Move newMove(@PathVariable String sessionId, @PathVariable String gameId, @PathVariable String userId, @RequestBody String move) throws SessionNotFoundException, GameNotFoundException, StateNotFoundException, RulesException {
    AWSXRay.getCurrentSegment().setUser(userId);
    return moveFactory.newMove(sessionId, gameId, userId, move);
  }

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