Configuration du kit SDK X-Ray pour Node.js - AWS X-Ray

Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

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.

Plugins
  • Amazon EC2 :EC2Plugin ajoute l'ID d'instance, la zone de disponibilité et le groupe de CloudWatch journaux.

  • Elastic Beanstalk :ElasticBeanstalkPlugin ajoute le nom de l'environnement, l'étiquette de version et l'ID de déploiement.

  • Amazon ECS :ECSPlugin ajoute l'ID du conteneur.

Pour utiliser un plug-in, configurez le kit SDK X-Ray pour le client Node.js en utilisant laconfig méthode.

Exemple app.js - plug-ins
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.

Note

Si le SDK ne parvient pas à joindre X-Ray pour obtenir les règles d'échantillonnage, il revient à une règle locale par défaut selon laquelle la première demande est effectuée chaque seconde et 5 % des demandes supplémentaires par hôte. Cela peut se produire si l'hôte n'est pas autorisé à appeler des API d'échantillonnage ou s'il ne peut pas se connecter au démon X-Ray, qui agit en tant que proxy TCP pour les appels d'API effectués par le SDK.

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.

Exemple sampling-rules.json
{ "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.

Exemple app.js - Règles d'échantillonnage à partir d'un fichier
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.

Exemple app.js - Échantillonnage des règles à partir d'un 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.

Exemple app.js - journalisation
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.

Exemple app.js - Adresse du démon
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.

Exemple app.js - Adresse du démon sur des ports distincts
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.

  • AWS_XRAY_CONTEXT_MISSING— DéfiniRUNTIME_ERROR pour générer des exceptions lorsque votre code instrumenté tente d'enregistrer des données alors qu'aucun segment n'est ouvert.

    Valeurs valides
    • RUNTIME_ERROR— Déclenche une exception d'exécution.

    • LOG_ERROR— Consigne une erreur et continue (par défaut).

    • IGNORE_ERROR— Ignorez l'erreur et continuez.

    Des erreurs liées à des segments ou sous-segments manquants peuvent survenir lorsque vous essayez d'utiliser un client instrumenté dans du code de démarrage qui s'exécute lorsqu'aucune demande n'est ouverte, ou dans du code qui génère un nouveau fil de discussion.

  • AWS_XRAY_DAEMON_ADDRESS— Définissez l'hôte et le port de l'écouteur du démon X-Ray. Par défaut, le SDK utilise à la fois127.0.0.1:2000 les données de trace (UDP) et l'échantillonnage (TCP). Utilisez cette variable si vous avez configuré le démon pour qu'il écoute sur un autre port ou s'il s'exécute sur un autre hôte.

    Format
    • Même portaddress:port

    • Différents portstcp:address:port udp:address:port

  • AWS_XRAY_DEBUG_MODE— Défini surTRUE pour configurer le SDK afin qu'il envoie les journaux à la console, audebug niveau 1.

  • AWS_XRAY_LOG_LEVEL — Définit un niveau de journalisation pour l'enregistreur par défaut. Les valeurs valides sont debug, info, warn, error et silent. Cette valeur est ignorée lorsque AWS_XRAY_DEBUG_MODE est défini sur TRUE.

  • AWS_XRAY_TRACING_NAME— Définissez un nom de service que le SDK utilise pour les segments. Remplace le nom de segment que vous définissez sur l'intergiciel Express.