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

Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

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

nota

Aviso de SDK/Daemon mantenimiento de X-Ray: el 25 de febrero de 2026, el AWS X-Ray SDKs/Daemon entrará en modo de mantenimiento, donde AWS se limitarán las versiones de X-Ray SDK y Daemon para abordar únicamente los problemas de seguridad. Para obtener más información sobre la cronología del soporte, consulte Cronología de X-Ray SDK y Daemon Support. Recomendamos migrar a. OpenTelemetry Para obtener más información sobre la migración a OpenTelemetry, consulte Migración de una instrumentación de rayos X a una instrumentación. OpenTelemetry

Cuando la aplicación realiza llamadas Servicios de AWS para almacenar datos, escribir en una cola o enviar notificaciones, el SDK de X-Ray para Node.js rastrea las llamadas en sentido descendente en subsegmentos. El Servicios de AWS rastreo y los recursos a los que accede dentro de esos servicios (por ejemplo, un bucket de Amazon S3 o una cola de Amazon SQS) aparecen como nodos descendentes en el mapa de rastreo de la consola X-Ray.

Clientes del AWS SDK de instrumentos que se crean a través de la V2 o la AWS SDK para JavaScript V3.AWS SDK para JavaScript Cada versión AWS del SDK proporciona diferentes métodos para instrumentar AWS los clientes del SDK.

nota

Actualmente, el AWS X-Ray SDK para Node.js devuelve menos información de segmentos al instrumentar los clientes de la AWS SDK para JavaScript V3, en comparación con la instrumentación de los 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 trazas, considere la posibilidad de utilizar la V2. AWS SDK para JavaScript

AWS SDK para JavaScript V2

Puede instrumentar todos los clientes AWS del SDK V2 empaquetando la sentencia aws-sdk require en una llamada aAWSXRay.captureAWS.

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

Para instrumentar a clientes individuales, incluye tu cliente del AWS SDK en una llamada aAWSXRay.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 TypeScriptECMAScriptmódulos (ESM) para cargar tu JavaScript código, usa el siguiente ejemplo para importar bibliotecas:

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

Para instrumentar ESM AWS a todos los clientes, utilice el siguiente código:

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

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 para JavaScript V3

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

Si quieres usar TypeScript ECMAScript Modules (ESM) para cargar tu JavaScript código, puedes usar el siguiente ejemplo para importar bibliotecas:

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

Instrumente cada cliente AWS del SDK mediante el AWSXRay.captureAWSv3Client método. 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" }));

Cuando se utiliza la AWS SDK para JavaScript V3, actualmente 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 rastreo no contendrá nodos discretos para cada recurso nombrado, como ocurre cuando se instrumentan los clientes del AWS SDK mediante la V2. AWS SDK para JavaScript

ejemplo Subsegmento para una llamada a DynamoDB para guardar un elemento, cuando se utiliza la V3 AWS SDK para 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",
  }
}