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.
# Utilisation de 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, consultez la section [Migration de l'instrumentation X-Ray vers OpenTelemetry l'instrumentation](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html).
Il existe deux manières d'instrumenter votre application Node.js pour envoyer des traces à X-Ray :
+ [AWS Distro for OpenTelemetry JavaScript](xray-js-opentel-sdk.md) : AWS distribution qui fournit un ensemble de bibliothèques open source permettant d'envoyer des métriques et des traces corrélées à plusieurs solutions de AWS surveillance, notamment Amazon et Amazon OpenSearch Service CloudWatch AWS X-Ray, via [AWS Distro](https://aws-otel.github.io/docs/getting-started/collector) for Collector. OpenTelemetry
+ [AWS X-Ray SDK pour Node.js](xray-sdk-nodejs.md) : ensemble de bibliothèques permettant de générer et d'envoyer des traces à X-Ray via le [daemon X-Ray](xray-daemon.md).
Pour de plus amples informations, veuillez consulter [Choisir entre The AWS Distro for OpenTelemetry et X-Ray SDKs](xray-instrumenting-your-app.md#xray-instrumenting-choosing).
# AWS Distro pour OpenTelemetry JavaScript
Avec le AWS Distro for OpenTelemetry (ADOT) JavaScript, vous pouvez instrumenter vos applications une seule fois et envoyer des métriques et des traces corrélées à plusieurs solutions de AWS surveillance CloudWatch, notamment Amazon AWS X-Ray et Amazon Service. OpenSearch L'utilisation de X-Ray avec AWS Distro pour OpenTelemetry nécessite deux composants : un *OpenTelemetry SDK* activé pour une utilisation avec X-Ray, et un *AWS Distro for OpenTelemetry Collector activé pour une* utilisation avec X-Ray.
Pour commencer, consultez la [ OpenTelemetry JavaScript documentation de la AWS distribution](https://aws-otel.github.io/docs/getting-started/javascript-sdk).
**Note**
ADOT JavaScript est pris en charge pour toutes les applications Node.js côté serveur. ADOT n' JavaScript est pas en mesure d'exporter des données vers X-Ray à partir de clients de navigateur.
Pour plus d'informations sur l'utilisation du AWS Distro pour OpenTelemetry with AWS X-Ray et d'autres Services AWS, voir [AWS Distro for OpenTelemetry](https://aws-otel.github.io/) ou [AWS Distro pour la documentation](https://aws-otel.github.io/docs/introduction). OpenTelemetry
Pour plus d'informations sur la prise en charge et l'utilisation des langues, consultez [AWS Observability on GitHub](https://github.com/aws-observability).
# AWS 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, consultez la section [Migration de l'instrumentation X-Ray vers OpenTelemetry l'instrumentation](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html).
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.
**Note**
Le SDK X-Ray pour Node.js est un projet open source pris en charge pour les versions 14.x et supérieures de Node.js. Vous pouvez suivre le projet et soumettre des problèmes et des pull requests sur GitHub : [github. com/aws/aws](https://github.com/aws/aws-xray-sdk-node)- xray-sdk-node
Si vous utilisez Express, commencez par [ajouter le SDK comme intergiciel](xray-sdk-nodejs-middleware.md) sur votre serveur d'applications afin de suivre les demandes entrantes. L'intergiciel crée un [segment](xray-concepts.md#xray-concepts-segments) 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](xray-concepts.md#xray-concepts-tracingheader). Pour les autres fonctions, vous pouvez [configurer Lambda](xray-services-lambda.md) pour échantillonner et suivre les demandes entrantes. Dans les deux cas, Lambda crée le segment et le fournit au SDK X-Ray.
**Note**
Sur Lambda, le SDK X-Ray est facultatif. Si vous ne l'utilisez pas dans votre fonction, votre carte de service inclura toujours un nœud pour le service Lambda et un nœud pour chaque fonction Lambda. En ajoutant le SDK, vous pouvez instrumenter votre code de fonction pour ajouter des sous-segments au segment de fonction enregistré par Lambda. Pour plus d’informations, consultez [AWS Lambda et AWS X-Ray](xray-services-lambda.md).
Utilisez ensuite le SDK X-Ray pour Node.js afin d'[instrumenter votre AWS SDK pour JavaScript les clients Node.js](xray-sdk-nodejs-awssdkclients.md). 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 kit de développement X-Ray pour Node.js fournit également des instruments pour les appels en aval aux requêtes Web APIs et SQL HTTP. [Enveloppez votre client HTTP dans la méthode de capture du kit de développement logiciel (SDK)](xray-sdk-nodejs-httpclients.md) 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](xray-sdk-nodejs-sqlclients.md).
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](xray-sdk-nodejs-configuration.md) 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](xray-sdk-nodejs-segment.md). Les annotations sont de simples paires clé-valeur, indexées en vue de leur utilisation avec les [expressions de filtre](xray-console-filters.md), 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).
**Annotations et métadonnées**
Les annotations et les métadonnées sont du texte arbitraire que vous ajoutez aux segments avec le SDK X-Ray. Les annotations sont indexées pour être utilisées avec les expressions de filtre. Les métadonnées ne sont pas indexées, mais peuvent être consultées dans le segment brut à l'aide de la console ou de l'API X-Ray. Toute personne à qui vous accordez un accès en lecture à X-Ray peut consulter ces données.
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](xray-sdk-nodejs-subsegments.md). 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](https://docs.aws.amazon.com//xray-sdk-for-nodejs/latest/reference).
## Prérequis
Le SDK X-Ray pour Node.js nécessite Node.js et les bibliothèques suivantes :
+ `atomic-batcher`— 1,0,2
+ `cls-hooked`— 4.2.2
+ `pkginfo`— 0,4,0
+ `semver`— 5.3.0
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.
+ `aws-sdk`— 2,7,15
## Gestion des dépendances
Le SDK X-Ray pour Node.js est disponible auprès de NPM.
+ **Package** — [https://www.npmjs.com/package/aws-xray-sdk](https://www.npmjs.com/package/aws-xray-sdk)
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](http://npm.github.io/how-npm-works-docs/npm3/how-npm3-works.html).
## 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.
+ [Exemple d'application Node.js](https://github.com/aws-samples/aws-xray-sdk-node-sample) sur GitHub.
# 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).
# Suivi des demandes entrantes avec le SDK 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, consultez la section [Migration de l'instrumentation X-Ray vers OpenTelemetry l'instrumentation](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html).
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.
**Note**
Pour les AWS Lambda fonctions, Lambda crée un segment pour chaque requête échantillonnée. Pour plus d’informations, consultez [AWS Lambda et AWS X-Ray](xray-services-lambda.md).
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é).
**Demandes transmises**
Si un équilibreur de charge ou un autre intermédiaire transmet une demande à votre application, X-Ray prend l'adresse IP du client depuis l'`X-Forwarded-For`en-tête de la demande plutôt que depuis l'adresse IP source du paquet IP. L'adresse IP du client enregistrée pour une demande transférée peut être falsifiée, elle ne doit donc pas être fiable.
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 sur`true`, l'adresse IP du client a été extraite de l'`X-Forwarded-For`en-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 :
+ **Méthode HTTP** : GET, POST, PUT, DELETE, etc.
+ **Adresse du client** : adresse IP du client qui a envoyé la demande.
+ **Code de réponse** : code de réponse HTTP pour la demande terminée.
+ **Moment** : heure de début (date de réception de la demande) et heure de fin (date d'envoi de la réponse).
+ **Agent utilisateur** — Le formulaire `user-agent` de la demande.
+ **Longueur du contenu** : `content-length` extrait de la réponse.
**Topics**
+ [Suivi des demandes entrantes avec Express](#xray-sdk-nodejs-middleware-express)
+ [Suivi des demandes entrantes avec Restify](#xray-sdk-nodejs-middleware-restify)
+ [Configuration d'une stratégie d'attribution de noms de segment](#xray-sdk-nodejs-middleware-naming)
## 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.
**Example app.js - Express**
```
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.
**Example app.js - restify**
```
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, ressources externes APIs 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](xray-api-segmentdocuments.md#api-segmentdocuments-fields) 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.com``api.example.com`, et`static.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.
**Note**
Vous pouvez remplacer le nom de service par défaut que vous définissez avec la `AWS_XRAY_TRACING_NAME`variable d'environnement[Variables d’environnement](xray-sdk-nodejs-configuration.md#xray-sdk-nodejs-configuration-envvars).
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`.
**Example app.js - Noms de segment dynamiques**
Si le nom d'hôte dans la demande correspond au modèle `*.example.com`, utilisez le nom d'hôte. Dans le cas contraire, utilisez `MyApp`.
```
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 du AWS SDK avec le SDK 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).
Lorsque votre application effectue des appels Services AWS pour stocker des données, écrire dans une file d'attente ou envoyer des notifications, le SDK X-Ray pour Node.js suit les appels en aval dans des [sous-segments](xray-sdk-nodejs-subsegments.md). Les ressources tracées Services AWS et auxquelles vous accédez au sein de ces services (par exemple, un compartiment Amazon S3 ou une file d'attente Amazon SQS) apparaissent sous forme de nœuds en aval sur la carte de trace de la console X-Ray.
Clients du AWS SDK d'instruments que vous créez via la [AWS SDK pour JavaScript V2 ou la [AWS SDK pour JavaScript V3](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/welcome.html)](https://docs.aws.amazon.com/sdk-for-javascript/v2/developer-guide/welcome.html). Chaque version du AWS SDK propose différentes méthodes pour instrumenter les clients du AWS SDK.
**Note**
Actuellement, le AWS X-Ray SDK pour Node.js renvoie moins d'informations sur les segments lors de l'instrumentation des clients AWS SDK pour JavaScript V3 que lors de l'instrumentation des clients V2. Par exemple, les sous-segments représentant des appels à DynamoDB ne renverront pas le nom de la table. Si vous avez besoin de ces informations de segment dans vos traces, pensez à utiliser le AWS SDK pour JavaScript V2.
------
#### [ AWS SDK pour JavaScript V2 ]
Vous pouvez instrumenter tous les clients du AWS SDK V2 en encapsulant votre instruction `aws-sdk` require dans un appel à`AWSXRay.captureAWS`.
**Example app.js - AWS Instrumentation du SDK**
```
const AWS = AWSXRay.captureAWS(require('aws-sdk'));
```
Pour instrumenter des clients individuels, associez votre client AWS SDK à un appel à`AWSXRay.captureAWSClient`. Par exemple, pour instrumenter un client `AmazonDynamoDB` :
**Example app.js - Instrumentation du client DynamoDB**
```
const AWSXRay = require('aws-xray-sdk');
...
const ddb = AWSXRay.captureAWSClient(new AWS.DynamoDB());
```
**Avertissement**
N’utilisez pas `captureAWS` et `captureAWSClient` ensemble. Ceci conduira à des sous-segments dupliqués.
Si vous souhaitez utiliser [TypeScript](https://www.typescriptlang.org/docs/handbook/typescript-in-5-minutes.html)des [ECMAScriptmodules](https://nodejs.org/api/esm.html) (ESM) pour charger votre JavaScript code, utilisez l'exemple suivant pour importer des bibliothèques :
**Example app.js - AWS Instrumentation du SDK**
```
import * as AWS from 'aws-sdk';
import * as AWSXRay from 'aws-xray-sdk';
```
Pour instrumenter tous les AWS clients avec ESM, utilisez le code suivant :
**Example app.js - AWS Instrumentation du SDK**
```
import * as AWS from 'aws-sdk';
import * as AWSXRay from 'aws-xray-sdk';
const XRAY_AWS = AWSXRay.captureAWS(AWS);
const ddb = new XRAY_AWS.DynamoDB();
```
Pour tous les services, vous pouvez voir le nom de l'API appelée dans la console X-Ray. Pour un sous-ensemble de services, le SDK X-Ray ajoute des informations au segment afin d'améliorer la granularité de la carte des services.
Par exemple, lorsque vous passez un appel avec un client DynamoDB instrumenté, le SDK ajoute le nom de la table au segment pour les appels qui ciblent une table. Dans la console, chaque table apparaît sous la forme d'un nœud distinct dans la carte des services, avec un nœud DynamoDB générique pour les appels qui ne ciblent pas une table.
**Example Sous-segment pour un appel à DynamoDB pour enregistrer un élément**
```
{
"id": "24756640c0d0978a",
"start_time": 1.480305974194E9,
"end_time": 1.4803059742E9,
"name": "DynamoDB",
"namespace": "aws",
"http": {
"response": {
"content_length": 60,
"status": 200
}
},
"aws": {
"table_name": "scorekeep-user",
"operation": "UpdateItem",
"request_id": "UBQNSO5AEM8T4FDA4RQDEB94OVTDRVV4K4HIRGVJF66Q9ASUAAJG",
}
}
```
Lorsque vous accédez aux ressources nommées, les appels vers les services suivants créent des nœuds supplémentaires dans la cartographie des services. Les appels qui ne ciblent pas de ressources spécifiques créent un nœud générique pour le service.
+ **Amazon DynamoDB — Nom** de la table
+ **Amazon Simple Storage Service** : nom du compartiment et de la clé
+ **Amazon Simple Queue Service** — Nom de la file d'attente
------
#### [ AWS SDK pour JavaScript V3 ]
La AWS SDK pour JavaScript V3 étant modulaire, votre code ne charge que les modules dont il a besoin. De ce fait, il n'est pas possible d'instrumenter tous les clients du AWS SDK car la version 3 ne prend pas en charge cette méthode. `captureAWS`
Si vous souhaitez utiliser TypeScript des ECMAScript modules (ESM) pour charger votre JavaScript code, vous pouvez utiliser l'exemple suivant pour importer des bibliothèques :
```
import * as AWS from 'aws-sdk';
import * as AWSXRay from 'aws-xray-sdk';
```
Instrumentez chaque client du AWS SDK à l'aide de `AWSXRay.captureAWSv3Client` cette méthode. Par exemple, pour instrumenter un client `AmazonDynamoDB` :
**Example app.js - Instrumentation du client DynamoDB à l'aide du SDK pour Javascript V3**
```
const AWSXRay = require('aws-xray-sdk');
const { DynamoDBClient } = require("@aws-sdk/client-dynamodb");
...
const ddb = AWSXRay.captureAWSv3Client(new DynamoDBClient({ region: "region" }));
```
Lors de l'utilisation de la AWS SDK pour JavaScript V3, les métadonnées telles que le nom de la table, le nom du bucket et de la clé, ou le nom de la file d'attente, ne sont actuellement pas renvoyées. Par conséquent, la carte de trace ne contiendra pas de nœuds discrets pour chaque ressource nommée, comme elle le ferait lors de l'instrumentation des clients du AWS SDK à l'aide de la V2. AWS SDK pour JavaScript
**Example Sous-segment pour un appel à DynamoDB pour enregistrer un élément, lors de l'utilisation de la V3 AWS SDK pour JavaScript**
```
{
"id": "24756640c0d0978a",
"start_time": 1.480305974194E9,
"end_time": 1.4803059742E9,
"name": "DynamoDB",
"namespace": "aws",
"http": {
"response": {
"content_length": 60,
"status": 200
}
},
"aws": {
"operation": "UpdateItem",
"request_id": "UBQNSO5AEM8T4FDA4RQDEB94OVTDRVV4K4HIRGVJF66Q9ASUAAJG",
}
}
```
------
# Suivi des appels vers les services Web HTTP en aval à l'aide du SDK 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, consultez la section [Migration de l'instrumentation X-Ray vers OpenTelemetry l'instrumentation](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html).
Lorsque votre application fait des appels à des microservices ou à du protocole HTTP public APIs, 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.
**Note**
Les appels utilisant des bibliothèques de demandes HTTP tierces, telles qu’Axios ou Superagent, sont pris en charge via l'[API `captureHTTPsGlobal()`](https://docs.aws.amazon.com/xray-sdk-for-nodejs/latest/reference/module-http_p.html) et seront toujours suivis lorsqu'ils utilisent le module `http` natif.
**Example app.js - Client HTTP**
```
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`.
**Example app.js - Client HTTP (global)**
```
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.
**Example Sous-segment pour un appel HTTP en aval**
```
{
"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
}
}
}
```
**Example Segment déduit pour un appel HTTP en aval**
```
{
"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
**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).
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.
+ **PostgreSQL** – `AWSXRay.capturePostgres()`
```
var AWSXRay = require('aws-xray-sdk');
var pg = AWSXRay.capturePostgres(require('pg'));
var client = new pg.Client();
```
+ **MySQL** – `AWSXRay.captureMySQL()`
```
var AWSXRay = require('aws-xray-sdk');
var mysql = AWSXRay.captureMySQL(require('mysql'));
...
var connection = mysql.createConnection(config);
```
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.
**Example Affecter du code SQL à un 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](https://docs.aws.amazon.com/xray/latest/devguide/xray-api-segmentdocuments.html#api-segmentdocuments-sql) du manuel du *AWS X-Ray développeur*.
# Génération de sous-segments personnalisés avec le SDK X-Ray pour Node.js
Les sous-segments étendent le [segment](xray-concepts.md#xray-concepts-segments) 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
**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, consultez la section [Migration de l'instrumentation X-Ray vers OpenTelemetry l'instrumentation](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html).
Pour créer un sous-segment personnalisé pour une fonction qui effectue des appels vers les services, utilisez la fonction `captureAsyncFunc`.
**Example app.js - Sous segments personnalisés Express**
```
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.
**Example Sous-segment avec des métadonnées**
```
"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.
**Example app.js - sous-segments personnalisés manuels**
```
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
**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, consultez la section [Migration de l'instrumentation X-Ray vers OpenTelemetry l'instrumentation](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html).
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 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](xray-console-filters.md). 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 [https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html](https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html).
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](#xray-sdk-nodejs-segment-userid) sur des segments. IDs Les 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.
**Topics**
+ [Enregistrement d'annotations avec le SDK X-Ray pour Node.js](#xray-sdk-nodejs-segment-annotations)
+ [Enregistrement de métadonnées avec le SDK X-Ray pour Node.js](#xray-sdk-nodejs-segment-metadata)
+ [Utilisateur enregistrant IDs avec le SDK X-Ray pour Node.js](#xray-sdk-nodejs-segment-userid)
## 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.
**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.
```
var AWSXRay = require('aws-xray-sdk');
...
var document = AWSXRay.getSegment();
```
1. Appelez `addAnnotation` avec une clé de type chaîne et une valeur de type booléen, numérique ou chaîne.
```
document.addAnnotation("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");
```
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é `annotation[key]` dans une [expression de filtre](xray-console-filters.md).
**Example app.js - Annotations**
```
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.
**Pour enregistrer les métadonnées**
1. Obtenez une référence au segment ou sous-segment en cours.
```
var AWSXRay = require('aws-xray-sdk');
...
var document = AWSXRay.getSegment();
```
1. Appelez `addMetadata` avec une clé de type chaîne, une valeur de type booléen, numérique, chaîne ou objet et un espace de noms de type chaîne.
```
document.addMetadata("my key", "my value", "my namespace");
```
or
Appelez `addMetadata` avec seulement une clé et une valeur.
```
document.addMetadata("my key", "my value");
```
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.
## Utilisateur enregistrant IDs avec le SDK X-Ray pour Node.js
Enregistrez les segments utilisateur IDs sur demande pour identifier l'utilisateur qui a envoyé 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.
**Pour enregistrer un utilisateur IDs**
1. Obtenez une référence au segment ou sous-segment en cours.
```
var AWSXRay = require('aws-xray-sdk');
...
var document = AWSXRay.getSegment();
```
1. Appelez `setUser()` avec l'ID de type chaîne de l'utilisateur ayant envoyé la demande.
```
var user = 'john123';
AWSXRay.getSegment().setUser(user);
```
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.
**Example app.js - ID utilisateur**
```
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](https://docs.aws.amazon.com/xray/latest/devguide/xray-console-filters.html).