Suivi des appels du AWS SDK avec le 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.

Suivi des appels du AWS SDK avec le SDK X-Ray pour Node.js

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. 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 for JavaScript V2 ou la AWS SDK for JavaScript V3. 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 for 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 for JavaScript V2.

AWS SDK for JavaScript V2

Vous pouvez instrumenter tous les clients du AWS SDK V2 en encapsulant votre instruction aws-sdk require dans un appel àAWSXRay.captureAWS.

Exemple 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 :

Exemple 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 TypeScriptdes modules ECMAScript (ESM) pour charger votre JavaScript code, utilisez l'exemple suivant pour importer des bibliothèques :

Exemple 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 :

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

Exemple 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 for JavaScript V3

La AWS SDK for 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 modules ECMAScript (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 :

Exemple 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 for 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 for JavaScript

Exemple Sous-segment pour un appel à DynamoDB pour enregistrer un élément, lors de l'utilisation de la V3 AWS SDK for 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",
  }
}