Rastreo de llamadas del SDK de AWS con el SDK de X-Ray para Node.js - AWS X-Ray

Rastreo de llamadas del SDK de AWS con el SDK de X-Ray para Node.js

Cuando su aplicación realiza llamadas a los Servicios de AWS para almacenar datos, escribir a una cola, o enviar notificaciones, el SDK de X-Ray para Node.js rastrea las llamadas posteriores en subsegmentos. Los recursos y Servicios de AWS rastreados a los que accede dentro de dichos servicios (por ejemplo, un bucket de Amazon S3 o una cola de Amazon SQS) aparecerán como nodos posteriores en el mapa de rastros en la consola de X-Ray.

Instrumente los clientes del SDK de AWS que cree mediante la V2 del AWS SDK for JavaScript o la V3 del AWS SDK for JavaScript. Cada versión del SDK de AWS proporciona diferentes métodos para instrumentar clientes del SDK de AWS.

nota

Actualmente, el SDK de AWS X-Ray para Node.js devuelve menos información de segmentos al instrumentar clientes de la V3 del AWS SDK for JavaScript, en comparación con instrumentar clientes de la V2. Por ejemplo, los subsegmentos que representan llamadas a DynamoDB no devolverán el nombre de la tabla. Si necesita esta información de segmento en sus rastros, considere la posibilidad de utilizar la V2 del AWS SDK for JavaScript.

AWS SDK for JavaScript V2

Puede instrumentar todos los clientes de la V2 del SDK de AWS mediante el encapsulamiento de su instrucción de requisito de aws-sdk en una llamada a AWSXRay.captureAWS.

ejemplo app.js: instrumentación con el SDK de AWS
const AWS = AWSXRay.captureAWS(require('aws-sdk'));

Para instrumentar clientes individuales, encapsule su cliente del SDK de AWS en una llamada a AWSXRay.captureAWSClient. Por ejemplo, para instrumentar un cliente de AmazonDynamoDB:

ejemplo app.js - Instrumentación de clientes de DynamoDB
    const AWSXRay = require('aws-xray-sdk');
...
    const ddb = AWSXRay.captureAWSClient(new AWS.DynamoDB());
aviso

No use captureAWS y captureAWSClient conjuntamente. Esto dará lugar a subsegmentos duplicados.

Si quieres usar TypeScript con módulos ECMAScript (ESM) para cargar tu código de JavaScript, usa el siguiente ejemplo para importar bibliotecas:

ejemplo app.js: instrumentación con el SDK de AWS
import * as AWS from 'aws-sdk';
import * as AWSXRay from 'aws-xray-sdk';

Para instrumentar todos los clientes de AWS con ESM, usa el siguiente código:

ejemplo app.js: instrumentación con el SDK de AWS
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();

Para todos los servicios, puede ver el nombre de la API a la que se llama en la consola de X-Ray. Para un subconjunto de servicios, el SDK de X-Ray agrega información al segmento para proporcionar una mayor granularidad en el mapa de servicio.

Por ejemplo, cuando realiza una llamada con un cliente instrumentado de DynamoDB, el SDK agrega el nombre de tabla al segmento para las llamadas que se dirigen a una tabla. En la consola, cada tabla aparece como nodo independiente en el mapa de servicio, con un nodo genérico de DynamoDB para las llamadas que no se dirigen a una tabla.

ejemplo Subsegmento para una llamada a DynamoDB con el fin de guardar un elemento
{
  "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",
  }
}

Cuando accede a recursos designados, las llamadas a los siguientes servicios crean nodos adicionales en el mapa de servicio. Las llamadas que no están dirigidas a recursos concretos crean un nodo genérico en el servicio.

  • Amazon DynamoDB: nombre de tabla

  • Amazon Simple Storage Service: nombre de bucket y de clave

  • Amazon Simple Queue Service: nombre de cola

AWS SDK for JavaScript V3

La V3 del AWS SDK for JavaScript es modular, por lo que el código solo carga los módulos que necesita. Por este motivo, no es posible instrumentar todos los clientes del SDK de AWS, ya que la V3 no admite el método captureAWS.

Si quiere usar TypeScript con módulos ECMAScript (ESM) para cargar tu código de JavaScript, puede usar el siguiente ejemplo para importar bibliotecas:

import * as AWS from 'aws-sdk';
import * as AWSXRay from 'aws-xray-sdk';

Instrumente cada cliente del SDK de AWS mediante el método AWSXRay.captureAWSv3Client. Por ejemplo, para instrumentar un cliente de AmazonDynamoDB:

ejemplo app.js: instrumentación de clientes de DynamoDB mediante la V3 del SDK para Javascript
    const AWSXRay = require('aws-xray-sdk');
    const { DynamoDBClient } = require("@aws-sdk/client-dynamodb");
...
    const ddb = AWSXRay.captureAWSv3Client(new DynamoDBClient({ region: "region" }));

Actualmente cuando se utiliza la V3 del AWS SDK for JavaScript no se devuelven metadatos como el nombre de la tabla, el nombre del bucket y la clave o el nombre de la cola y, por lo tanto, el mapa de rastros no incluirá nodos discretos para cada recurso nombrado, como ocurre cuando se instrumentan clientes del SDK de AWS mediante la V2 del AWS SDK for JavaScript.

ejemplo Subsegmento para una llamada a DynamoDB con el fin de guardar un elemento, cuando se utiliza la V3 del 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",
  }
}