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 de développement X-Ray pour Node.js **Note** Avis de SDK/Daemon maintenance de X-Ray — Le 25 février 2026, le AWS X-Ray SDKs/Daemon passera en mode maintenance, où les versions du SDK et du Daemon de X-Ray AWS seront limitées uniquement pour résoudre les problèmes de sécurité. Pour plus d'informations sur le calendrier de support, consultez[Chronologie du support pour le SDK et Daemon X-Ray](xray-sdk-daemon-timeline.md). Nous vous recommandons de migrer vers OpenTelemetry. Pour plus d'informations sur la migration vers OpenTelemetry, voir [Migration de l'instrumentation X-Ray vers OpenTelemetry l'instrumentation](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html). 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. **Topics** + [Plug-ins de service](#xray-sdk-nodejs-configuration-plugins) + [Règles d'échantillonnage](#xray-sdk-nodejs-configuration-sampling) + [Logging](#xray-sdk-nodejs-configuration-logging) + [Adresse du daemon X-Ray](#xray-sdk-nodejs-configuration-daemon) + [Variables d’environnement](#xray-sdk-nodejs-configuration-envvars) ## Plug-ins de service Permet `plugins` d'enregistrer des informations sur le service hébergeant votre application. **Plug-ins** + Amazon EC2 — `EC2Plugin` ajoute l'ID de l'instance, la zone de disponibilité et le groupe de CloudWatch journaux. + Elastic `ElasticBeanstalkPlugin` Beanstalk : 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 plugin, configurez le SDK X-Ray pour le client Node.js à l'aide de la `config` méthode. **Example 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 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](xray-console-sampling.md) 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. **Note** Si le SDK ne parvient pas à accéder à X-Ray pour obtenir des règles d'échantillonnage, il revient à une règle locale par défaut concernant la première demande chaque seconde, et 5 % des demandes supplémentaires par hôte. Cela peut se produire si l'hôte n'est pas autorisé à appeler sampling APIs ou ne peut pas se connecter au daemon X-Ray, qui agit comme un 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 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. **Example 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 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 contenant`setSamplingRules`. **Example 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. **Example 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() ``` ## Logging 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_LEVEL`environnement `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](#xray-sdk-nodejs-configuration-envvars). 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. **Example 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 daemon X-Ray Si le daemon X-Ray écoute sur un port ou un hôte autre que celui-ci`127.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 son nom ou son IPv4 adresse. **Example 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. **Example 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](#xray-sdk-nodejs-configuration-envvars). ## 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. + `AWS_XRAY_CONTEXT_MISSING`— Réglé sur `RUNTIME_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`— Lance une exception d'exécution. + `LOG_ERROR`— Enregistrez une erreur et continuez (par défaut). + `IGNORE_ERROR`— Ignorez l'erreur et continuez. Des erreurs liées à des segments ou sous-segments manquants peuvent se produire lorsque vous essayez d'utiliser un client instrumenté dans un code de démarrage qui s'exécute lorsqu'aucune demande n'est ouverte, ou dans un code qui génère un nouveau thread. + `AWS_XRAY_DAEMON_ADDRESS`— Définissez l'hôte et le port de l'écouteur du daemon X-Ray. Par défaut, le SDK utilise à la fois `127.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 port différent](xray-daemon-configuration.md) ou s'il s'exécute sur un autre hôte. **Format** + **Même port** — `address:port` + **Différents ports** — `tcp:address:port udp:address:port` + `AWS_XRAY_DEBUG_MODE`— Définissez sur `TRUE` pour configurer le SDK afin qu'il génère des journaux sur la console, au `debug` niveau 1. + `AWS_XRAY_LOG_LEVEL `— Définissez 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 lorsqu'elle AWS\$1XRAY\$1DEBUG\$1MODE est définie 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](xray-sdk-nodejs-middleware.md).