AWS Kit de développement X-Ray pour Node.js

Le SDK X-Ray pour Node.js est une bibliothèque pour les applications Web Express et les fonctions Lambda Node.js qui fournit des classes et des méthodes permettant de générer et d'envoyer des données de trace au démon X-Ray. Les données de suivi incluent des informations sur les requêtes HTTP entrantes traitées par l'application et les appels que l'application effectue aux services en aval à l'aide du AWS SDK ou des clients HTTP.

Si vous utilisez Express, commencez par ajouter le SDK comme intergiciel sur votre serveur d'applications afin de suivre les demandes entrantes. L'intergiciel crée un segment pour chaque demande suivie et termine le segment lorsque la réponse est envoyée. Tandis que le segment soit ouvert, vous pouvez utiliser les méthodes du client du SDK pour ajouter des informations au segment et créer des sous-segments afin de suivre les appels en amont. Le kit de développement logiciel (SDK) enregistre aussi automatiquement les exceptions que votre application renvoie quand le segment est ouvert.

Pour les fonctions Lambda appelées par une application ou un service instrumenté, Lambda lit l'en-tête de suivi et trace automatiquement les requêtes échantillonnées. Pour les autres fonctions, vous pouvez configurer Lambda pour échantillonner et suivre les demandes entrantes. Dans les deux cas, Lambda crée le segment et le fournit au SDK X-Ray.

Utilisez ensuite le SDK X-Ray pour Node.js afin d'instrumenter votre AWS SDK pour JavaScript les clients Node.js. Chaque fois que vous appelez une ressource Service AWS ou une ressource en aval avec un client instrumenté, le SDK enregistre les informations relatives à l'appel dans un sous-segment. Services AWS et les ressources auxquelles vous accédez au sein des services apparaissent sous forme de nœuds en aval sur la carte de trace pour vous aider à identifier les erreurs et les problèmes de limitation sur les connexions individuelles.

Le SDK X-Ray pour Node.js fournit également une instrumentation pour les appels en aval aux API Web HTTP et aux requêtes SQL. Enveloppez votre client HTTP dans la méthode de capture du kit de développement logiciel (SDK) afin d'enregistrer les informations sur les appels HTTP sortants. Pour les clients SQL, utilisez la méthode de capture correspondant à votre type de base de données.

L'intergiciel applique les règles d'échantillonnage aux demandes entrantes pour déterminer les demandes à suivre. Vous pouvez configurer le SDK X-Ray pour Node.js afin d'ajuster le comportement d'échantillonnage ou d'enregistrer des informations concernant les ressources de AWS calcul sur lesquelles votre application s'exécute.

Enregistrez les informations supplémentaires sur les demandes et le travail que votre application effectue dans les annotations et les métadonnées. Les annotations sont de simples paires clé-valeur, indexées en vue de leur utilisation avec les expressions de filtre, de telle sorte que vous pouvez explorer les suivis qui contiennent des données spécifiques. Les entrées des métadonnées sont moins restrictives et peuvent enregistrer des objets et tableaux entiers (tout ce qui peut être sérialisé en JSON).

Lorsque vous avez un grand nombre de clients instrumentés dans votre code, un seul segment de demande peut contenir un grand nombre de sous-segments, un par appel effectué à l'aide d'un client instrumenté. Vous pouvez organiser et grouper les sous-segments en enveloppant les appels clients dans des sous-segments personnalisés. Vous pouvez créer un sous-segment personnalisé pour une fonction complète ou une quelconque section du code, puis enregistrer les métadonnées et les annotations sur le sous-segment au lieu de tout écrire sur le segment parent.

Pour obtenir de la documentation de référence sur les classes et les méthodes du SDK, consultez le manuel de référence de l'API du AWS X-Ray SDK pour Node.js.

Prérequis

Le SDK X-Ray pour Node.js nécessite Node.js et les bibliothèques suivantes :

Le kit SDK extrait les bibliothèques lorsque vous l'installez avec NPM.

Pour suivre les clients du AWS SDK, le SDK X-Ray pour Node.js nécessite une version minimale du AWS SDK pour JavaScript Node.js.

Gestion des dépendances

Le SDK X-Ray pour Node.js est disponible auprès de NPM.

Pour le développement local, installez le kit de développement logiciel (SDK) dans le répertoire de votre projet avec npm.

~/nodejs-xray$ npm install aws-xray-sdk
aws-xray-sdk@3.3.3
  ├─┬ aws-xray-sdk-core@3.3.3
  │ ├── @aws-sdk/service-error-classification@3.15.0
  │ ├── @aws-sdk/types@3.15.0
  │ ├─┬ @types/cls-hooked@4.3.3
  │ │ └── @types/node@15.3.0
  │ ├── atomic-batcher@1.0.2
  │ ├─┬ cls-hooked@4.2.2
  │ │ ├─┬ async-hook-jl@1.7.6
  │ │ │ └── stack-chain@1.3.7
  │ │ └─┬ emitter-listener@1.1.2
  │ │   └── shimmer@1.2.1
  │ └── semver@5.7.1
  ├── aws-xray-sdk-express@3.3.3
  ├── aws-xray-sdk-mysql@3.3.3
  └── aws-xray-sdk-postgres@3.3.3

Utilisez l'option --save pour sauvegarder le SDK comme dépendance dans le package.json de votre application.

~/nodejs-xray$ npm install aws-xray-sdk --save
aws-xray-sdk@3.3.3

Si votre application possède des dépendances dont les versions entrent en conflit avec les dépendances du SDK X-Ray, les deux versions seront installées pour garantir la compatibilité. Pour plus de détails, consultez la documentation officielle de NPM pour la résolution des dépendances.

Exemples Node.js

Utilisez le AWS X-Ray SDK pour Node.js pour avoir une end-to-end vue d'ensemble des demandes lorsqu'elles transitent par vos applications Node.js.

Configuration du SDK X-Ray pour Node.js

Vous pouvez configurer le SDK X-Ray pour Node.js à l'aide de plug-ins afin d'inclure des informations sur le service sur lequel votre application s'exécute, de modifier le comportement d'échantillonnage par défaut ou d'ajouter des règles d'échantillonnage qui s'appliquent aux demandes adressées à des chemins spécifiques.

Plug-ins de service

Permet plugins d'enregistrer des informations sur le service hébergeant votre application.

Pour utiliser un plugin, configurez le SDK X-Ray pour le client Node.js à l'aide de la config méthode.

var AWSXRay = require('aws-xray-sdk');
AWSXRay.config([AWSXRay.plugins.EC2Plugin,AWSXRay.plugins.ElasticBeanstalkPlugin]);

Le SDK utilise également les paramètres du plugin pour définir le origin champ du segment. Cela indique le type de AWS ressource qui exécute votre application. Lorsque vous utilisez plusieurs plug-ins, le SDK utilise l'ordre de résolution suivant pour déterminer l'origine : ElasticBeanstalk > EKS > ECS > EC2.

Règles d'échantillonnage

Le SDK utilise les règles d'échantillonnage que vous définissez dans la console X-Ray pour déterminer les demandes à enregistrer. La règle par défaut suit la première demande chaque seconde, et 5 % de toutes les demandes supplémentaires provenant de tous les services envoient des traces à X-Ray. Créez des règles supplémentaires dans la console X-Ray pour personnaliser la quantité de données enregistrées pour chacune de vos applications.

Le SDK applique les règles personnalisées dans l'ordre dans lequel elles sont définies. Si une demande correspond à plusieurs règles personnalisées, le SDK applique uniquement la première règle.

Vous pouvez également configurer le SDK pour charger des règles d'échantillonnage à partir d'un document JSON. Le SDK peut utiliser les règles locales comme solution de rechange dans les cas où l'échantillonnage X-Ray n'est pas disponible, ou utiliser exclusivement les règles locales.

{
  "version": 2,
  "rules": [
    {
      "description": "Player moves.",
      "host": "*",
      "http_method": "*",
      "url_path": "/api/move/*",
      "fixed_target": 0,
      "rate": 0.05
    }
  ],
  "default": {
    "fixed_target": 1,
    "rate": 0.1
  }
}

Cet exemple définit une règle personnalisée et une règle par défaut. La règle personnalisée applique un taux d'échantillonnage de 5 % sans nombre minimum de demandes à suivre pour les chemins sous-jacents. /api/move/ La règle par défaut suit la première demande chaque seconde et 10 % des demandes supplémentaires.

L'inconvénient de définir des règles localement est que la cible fixe est appliquée par chaque instance de l'enregistreur indépendamment, au lieu d'être gérée par le service X-Ray. Au fur et à mesure que vous déployez de nouveaux hôtes, le taux fixe est multiplié, ce qui complique le contrôle de la quantité de données enregistrées.

Activé AWS Lambda, vous ne pouvez pas modifier le taux d'échantillonnage. Si votre fonction est appelée par un service instrumenté, les appels ayant généré des demandes échantillonnées par ce service seront enregistrés par Lambda. Si le suivi actif est activé et qu'aucun en-tête de suivi n'est présent, Lambda prend la décision d'échantillonnage.

Pour configurer les règles de sauvegarde, demandez au SDK X-Ray pour Node.js de charger les règles d'échantillonnage à partir d'un fichier contenantsetSamplingRules.

var AWSXRay = require('aws-xray-sdk');
AWSXRay.middleware.setSamplingRules('sampling-rules.json');

Vous pouvez également définir des règles dans votre code et les transférer à setSamplingRules en tant qu'objet.

var AWSXRay = require('aws-xray-sdk');
var rules = {
  "rules": [ { "description": "Player moves.", "service_name": "*", "http_method": "*", "url_path": "/api/move/*", "fixed_target": 0, "rate": 0.05 } ],
  "default": { "fixed_target": 1, "rate": 0.1 },
  "version": 1
  }

AWSXRay.middleware.setSamplingRules(rules);

Pour utiliser uniquement des règles locales, appelez disableCentralizedSampling.

AWSXRay.middleware.disableCentralizedSampling()

Journalisation

Pour vous connecter à partir du kit SDK, appelez AWSXRay.setLogger(logger), où logger est un objet qui fournit des méthodes de journalisation standard (warn, info, etc.).

Par défaut, le SDK enregistre les messages d'erreur sur la console en utilisant les méthodes standard de l'objet de console. Le niveau de journalisation de l'enregistreur intégré peut être défini à l'aide des variables d'AWS_XRAY_LOG_LEVELenvironnement AWS_XRAY_DEBUG_MODE ou des variables d'environnement. Pour obtenir la liste des valeurs de niveau de journalisation valides, consultez la section Variables d'environnement.

Si vous souhaitez fournir un format ou une destination différents pour les journaux, vous pouvez fournir au SDK votre propre implémentation de l'interface de journalisation, comme indiqué ci-dessous. Tout objet implémentant cette interface peut être utilisé. Cela signifie que de nombreuses bibliothèques de journalisation, par exemple Winston, pourraient être utilisées et transmises directement au SDK.

var AWSXRay = require('aws-xray-sdk');

// Create your own logger, or instantiate one using a library.
var logger = {
  error: (message, meta) => { /* logging code */ },
  warn: (message, meta) => { /* logging code */ },
  info: (message, meta) => { /* logging code */ },
  debug: (message, meta) => { /* logging code */ }
}

AWSXRay.setLogger(logger);
AWSXRay.config([AWSXRay.plugins.EC2Plugin]);

Appelez setLogger avant d'exécuter d'autres méthodes de configuration afin de veiller à capturer la sortie de ces opérations.

Adresse du daemon X-Ray

Si le daemon X-Ray écoute sur un port ou un hôte autre que celui-ci127.0.0.1:2000, vous pouvez configurer le SDK X-Ray pour Node.js afin d'envoyer les données de suivi à une adresse différente.

AWSXRay.setDaemonAddress('host:port');

Vous pouvez spécifier l'hôte par nom ou par adresse IPv4.

var AWSXRay = require('aws-xray-sdk');
AWSXRay.setDaemonAddress('daemonhost:8082');

Si vous avez configuré le démon de façon à ce qu'il écoute sur des ports différents pour les protocoles TCP et UDP, vous pouvez spécifier les deux dans l'adresse du démon.

var AWSXRay = require('aws-xray-sdk');
AWSXRay.setDaemonAddress('tcp:daemonhost:8082 udp:daemonhost:8083');

Vous pouvez également définir l'adresse du démon à l'aide de la AWS_XRAY_DAEMON_ADDRESS variable d'environnement.

Variables d’environnement

Vous pouvez utiliser des variables d'environnement pour configurer le SDK X-Ray pour Node.js. Le kit SDK prend en charge les variables suivantes.

Suivi des demandes entrantes avec le SDK X-Ray pour Node.js

Vous pouvez utiliser le SDK X-Ray pour Node.js afin de suivre les requêtes HTTP entrantes que vos applications Express et Restify traitent sur une instance EC2 dans Amazon EC2 ou Amazon ECS. AWS Elastic Beanstalk

Le SDK X-Ray pour Node.js fournit un intergiciel pour les applications qui utilisent les frameworks Express et Restify. Lorsque vous ajoutez le middleware X-Ray à votre application, le SDK X-Ray pour Node.js crée un segment pour chaque requête échantillonnée. Ce segment comprend la durée, la méthode et l'état de la demande HTTP. L'instrumentation supplémentaire crée des sous-segments sur ce segment.

Chaque segment porte un nom qui identifie votre application dans la carte des services. Le segment peut être nommé de manière statique ou vous pouvez configurer le SDK pour qu'il soit nommé dynamiquement en fonction de l'en-tête de l'hôte dans la demande entrante. La dénomination dynamique vous permet de regrouper les traces en fonction du nom de domaine indiqué dans la demande et d'appliquer un nom par défaut si le nom ne correspond pas au modèle attendu (par exemple, si l'en-tête de l'hôte est falsifié).

Lorsqu'une demande est transmise, le SDK définit un champ supplémentaire dans le segment pour l'indiquer. Si le segment contient le champ x_forwarded_for défini surtrue, l'adresse IP du client a été extraite de l'X-Forwarded-Foren-tête de la requête HTTP.

Le gestionnaire de messages crée un segment pour chaque demande entrante avec un bloc http contenant les informations suivantes :

Suivi des demandes entrantes avec Express

Pour utiliser l'intergiciel Express, initialisez le client du kit de développement logiciel et utilisez l'intergiciel renvoyé par la fonction express.openSegment avant de définir vos routes.

var app = express();

var AWSXRay = require('aws-xray-sdk');
app.use(AWSXRay.express.openSegment('MyApp'));

app.get('/', function (req, res) {
  res.render('index');
});

app.use(AWSXRay.express.closeSegment());

Après avoir défini vos itinéraires, utilisez la sortie de express.closeSegment comme indiqué pour gérer les erreurs renvoyées par le SDK X-Ray pour Node.js.

Suivi des demandes entrantes avec Restify

Pour utiliser l'intergiciel Restify, initialisez le client du kit de développement logiciel et exécutez enable. Indiquez-lui votre serveur Restify et le nom de votre segment.

var AWSXRay = require('aws-xray-sdk');
var AWSXRayRestify = require('aws-xray-sdk-restify');

var restify = require('restify');
var server = restify.createServer();
AWSXRayRestify.enable(server, 'MyApp'));

server.get('/', function (req, res) {
  res.render('index');
});

Configuration d'une stratégie d'attribution de noms de segment

AWS X-Ray utilise un nom de service pour identifier votre application et la distinguer des autres applications, bases de données, API externes et AWS ressources utilisées par votre application. Lorsque le SDK X-Ray génère des segments pour les demandes entrantes, il enregistre le nom du service de votre application dans le champ du nom du segment.

Le SDK X-Ray peut nommer les segments d'après le nom d'hôte dans l'en-tête de la requête HTTP. Cependant, cet en-tête peut être falsifié, ce qui peut entraîner la création de nœuds inattendus dans votre carte de service. Pour éviter que le SDK ne nomme les segments de manière incorrecte en raison de demandes contenant des en-têtes d'hôte falsifiés, vous devez spécifier un nom par défaut pour les demandes entrantes.

Si votre application traite des demandes pour plusieurs domaines, vous pouvez configurer le SDK pour qu'il utilise une stratégie de dénomination dynamique afin de refléter cela dans les noms des segments. Une stratégie de dénomination dynamique permet au SDK d'utiliser le nom d'hôte pour les demandes qui correspondent à un modèle attendu et d'appliquer le nom par défaut aux demandes qui ne le sont pas.

Par exemple, il se peut qu'une seule application envoie des demandes à trois sous-domaines : www.example.comapi.example.com, etstatic.example.com. Vous pouvez utiliser une stratégie de dénomination dynamique avec le modèle *.example.com pour identifier les segments de chaque sous-domaine avec un nom différent, ce qui permet d'obtenir trois nœuds de service sur la carte des services. Si votre application reçoit des demandes dont le nom d'hôte ne correspond pas au modèle, vous verrez un quatrième nœud sur la carte des services avec un nom de remplacement que vous spécifiez.

Pour utiliser le même nom pour tous les segments de la demande, spécifiez le nom de votre application lorsque vous initialisez l'intergiciel, comme indiqué dans les sections précédentes.

Une stratégie d'attribution de noms dynamique définit un modèle auquel doivent correspondre les noms d'hôte et un nom par défaut à utiliser si le nom d'hôte de la demande HTTP ne correspond pas au modèle. Pour nommer dynamiquement des segments, utilisez AWSXRay.middleware.enableDynamicNaming.

var app = express();

var AWSXRay = require('aws-xray-sdk');
app.use(AWSXRay.express.openSegment('MyApp'));
AWSXRay.middleware.enableDynamicNaming('*.example.com');
        
app.get('/', function (req, res) {
  res.render('index');
});

app.use(AWSXRay.express.closeSegment());

Suivi des appels vers les services Web HTTP en aval à l'aide du SDK X-Ray pour Node.js

Lorsque votre application appelle des microservices ou des API HTTP publiques, vous pouvez utiliser le client X-Ray SDK for Node.js pour instrumenter ces appels et ajouter l'API au graphe de service en tant que service en aval.

Transmettez votre http ou votre https client au SDK X-Ray pour la captureHTTPs méthode Node.js afin de suivre les appels sortants.

var AWSXRay = require('aws-xray-sdk');
var http = AWSXRay.captureHTTPs(require('http'));

Pour activer le suivi sur tous les clients HTTP, appelez captureHTTPsGlobal avant de charger http.

var AWSXRay = require('aws-xray-sdk');
AWSXRay.captureHTTPsGlobal(require('http'));
var http = require('http');

Lorsque vous instrumentez un appel à une API Web en aval, le SDK X-Ray pour Node.js enregistre un sous-segment contenant des informations sur la requête et la réponse HTTP. X-Ray utilise le sous-segment pour générer un segment inféré pour l'API distante.

{
  "id": "004f72be19cddc2a",
  "start_time": 1484786387.131,
  "end_time": 1484786387.501,
  "name": "names.example.com",
  "namespace": "remote",
  "http": {
    "request": {
      "method": "GET",
      "url": "https://names.example.com/"
    },
    "response": {
      "content_length": -1,
      "status": 200
    }
  }
}

{
  "id": "168416dc2ea97781",
  "name": "names.example.com",
  "trace_id": "1-62be1272-1b71c4274f39f122afa64eab",
  "start_time": 1484786387.131,
  "end_time": 1484786387.501,
  "parent_id": "004f72be19cddc2a",
  "http": {
    "request": {
      "method": "GET",
      "url": "https://names.example.com/"
    },
    "response": {
      "content_length": -1,
      "status": 200
    }
  },
  "inferred": true
}

Suivi des requêtes SQL avec le SDK X-Ray pour Node.js

Instrumentez les requêtes de base de données SQL en encapsulant votre client SQL dans la méthode cliente X-Ray SDK for Node.js correspondante.

Lorsque vous utilisez un client instrumenté pour effectuer des requêtes SQL, le kit SDK X-Ray pour Node.js enregistre les informations sur la connexion et la requête dans un sous-segment.

Inclusion de données supplémentaires dans les sous-segments SQL

Vous pouvez ajouter des informations supplémentaires aux sous-segments générés pour les requêtes SQL, à condition qu'elles soient mappées à un champ SQL autorisé. Par exemple, pour enregistrer la chaîne de requête SQL nettoyée dans un sous-segment, vous pouvez l'ajouter directement à l'objet SQL du sous-segment.

    const queryString = 'SELECT * FROM MyTable';
connection.query(queryString, ...);

// Retrieve the most recently created subsegment
const subs = AWSXRay.getSegment().subsegments;

if (subs & & subs.length > 0) {
  var sqlSub = subs[subs.length - 1];
  sqlSub.sql.sanitized_query = queryString;
}
	 

Pour obtenir la liste complète des champs SQL autorisés, consultez la section Requêtes SQL du. Documents relatifs au segment X-Ray

Génération de sous-segments personnalisés avec le SDK X-Ray pour Node.js

Les sous-segments étendent le segment d'une trace avec des détails sur le travail effectué afin de répondre à une demande. Chaque fois que vous passez un appel avec un client instrumenté, le SDK X-Ray enregistre les informations générées dans un sous-segment. Vous pouvez créer des sous-segments supplémentaires pour regrouper d'autres sous-segments, pour mesurer les performances d'une section de code ou pour enregistrer des annotations et des métadonnées.

Sous-segments Express personnalisés

Pour créer un sous-segment personnalisé pour une fonction qui effectue des appels vers les services, utilisez la fonction captureAsyncFunc.

var AWSXRay = require('aws-xray-sdk');

app.use(AWSXRay.express.openSegment('MyApp'));

app.get('/', function (req, res) {
  var host = 'api.example.com';

  AWSXRay.captureAsyncFunc('send', function(subsegment) {
    sendRequest(host, function() {
      console.log('rendering!');
      res.render('index');
      subsegment.close();
    });
  });
});

app.use(AWSXRay.express.closeSegment());

function sendRequest(host, cb) {
  var options = {
    host: host,
    path: '/',
  };

  var callback = function(response) {
    var str = '';

    response.on('data', function (chunk) {
      str += chunk;
    });

    response.on('end', function () {
      cb();
    });
  }

  http.request(options, callback).end();
};

Dans cet exemple, l'application crée un sous-segment personnalisé nommé send pour les appels vers la fonction sendRequest. captureAsyncFunc transmet un sous-segment que vous devez fermer dans la fonction de rappel lorsque les appels asynchrones qu'elle effectue sont terminés.

Pour les fonctions synchrones, vous pouvez utiliser la fonction captureFunc qui ferme automatiquement le sous-segment dès la fin de l'exécution du bloc de fonction.

Lorsque vous créez un sous-segment au sein d'un segment ou d'un autre sous-segment, le SDK X-Ray pour Node.js génère un identifiant et enregistre l'heure de début et de fin.

"subsegments": [{
  "id": "6f1605cd8a07cb70",
  "start_time": 1.480305974194E9,
  "end_time": 1.4803059742E9,
  "name": "Custom subsegment for UserModel.saveUser function",
  "metadata": {
    "debug": {
      "test": "Metadata string from UserModel.saveUser"
    }
  },

Sous-segments Lambda personnalisés

Le SDK est configuré pour créer automatiquement un segment de façade fictif lorsqu'il détecte qu'il s'exécute dans Lambda. Pour créer un sous-segment de base, qui créera un AWS::Lambda::Function nœud unique sur la carte de trace X-Ray, appelez et réutilisez le segment de façade. Si vous créez manuellement un nouveau segment avec un nouvel ID (tout en partageant l'ID de suivi, l'ID parent et la décision d'échantillonnage), vous pourrez envoyer un nouveau segment.

const segment = AWSXRay.getSegment(); //returns the facade segment
const subsegment = segment.addNewSubsegment('subseg');
...
subsegment.close();
//the segment is closed by the SDK automatically

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

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.

Enregistrement d'annotations avec le SDK X-Ray pour Node.js

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

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 addAnnotation 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.

var AWS = require('aws-sdk');
var AWSXRay = require('aws-xray-sdk');
var ddb = AWSXRay.captureAWSClient(new AWS.DynamoDB());
...
app.post('/signup', function(req, res) {
    var item = {
        'email': {'S': req.body.email},
        'name': {'S': req.body.name},
        'preview': {'S': req.body.previewAccess},
        'theme': {'S': req.body.theme}
    };

    var seg = AWSXRay.getSegment();
    seg.addAnnotation('theme', req.body.theme);
  
    ddb.putItem({
      'TableName': ddbTable,
      'Item': item,
      'Expected': { email: { Exists: false } }
  }, function(err, data) {
...

Enregistrement de métadonnées avec le SDK X-Ray pour Node.js

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 autre objet à même d'être sérialisé en un tableau ou objet JSON.

Si vous ne spécifiez pas d'espace de noms, le kit de développement logiciel utilise default. Si vous appelez deux fois addMetadata 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 Node.js

Enregistrez les ID utilisateur sur les segments de la demande afin d'identifier l'utilisateur à l'origine de la demande. Cette opération n'est pas compatible avec AWS Lambda les fonctions car les segments dans les environnements Lambda sont immuables. L'appel setUser peut être appliqué uniquement aux segments, pas aux sous-segments.

Vous pouvez appeler setUser pour enregistrer l'ID utilisateur dès que votre application express commence à traiter 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.

var AWS = require('aws-sdk');
var AWSXRay = require('aws-xray-sdk');
var uuidv4 = require('uuid/v4');
var ddb = AWSXRay.captureAWSClient(new AWS.DynamoDB());
...
    app.post('/signup', function(req, res) {
    var userId = uuidv4();
    var item = {
        'userId': {'S': userId},
        'email': {'S': req.body.email},
        'name': {'S': req.body.name}
    };

    var seg = AWSXRay.getSegment().setUser(userId);
  
    ddb.putItem({
      'TableName': ddbTable,
      'Item': item,
      'Expected': { email: { Exists: false } }
  }, function(err, data) {
...

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