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

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.

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.

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