Configuration du kit 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

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

Pour utiliser un plug-in, configurez le kit SDK X-Ray pour le client Node.js en utilisant laconfig 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 leorigin champ sur le segment. Cela indique le type deAWS 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 effectue le suivi de la première demande chaque seconde et de 5 % de toutes les demandes supplémentaires, tous services confondus, qui envoient des traces à X-Ray. Créez des règles supplémentaires dans la console X-Ray afin de personnaliser la quantité de données enregistrées pour chacune de vos applications.

Le kit SDK applique des 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 des règles locales comme solution de sauvegarde dans les cas où l'échantillonnage X-Ray n'est pas disponible, ou utiliser exclusivement des 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 rechercher les chemins/api/move/. La règle par défaut effectue le suivi de 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 davantage d'hôtes, le débit 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 la fréquence d'échantillonnage. Si votre fonction est appelée par un service instrumenté, les appels ayant généré des requêtes é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 des règles de sauvegarde, demandez au kit SDK X-Ray pour Node.js de charger des règles d'échantillonnage depuis un fichier avecsetSamplingRules.

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 à l'aide des méthodes standard de l'objet console. Le niveau de journalisation de l'enregistreur intégré peut être défini à l'aide des variables d'AWS_XRAY_LOG_LEVELenvironnementAWS_XRAY_DEBUG_MODE ou. 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érent pour les journaux, vous pouvez fournir au SDK votre propre implémentation de l'interface de l'enregistreur, comme indiqué ci-dessous. Tout objet qui implémente cette interface peut être utilisé. Cela signifie que de nombreuses bibliothèques de journalisation, par exemple Winston, peuvent ê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 Démon X-Ray

Si le démon X-Ray écoute sur un port ou un hôte autre que127.0.0.1:2000, vous pouvez configurer le SDK X-Ray pour que Node.js envoie les données de trace à 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 kit SDK X-Ray pour Node.js. Le kit SDK prend en charge les variables suivantes.