Rastreando chamadas AWS do SDK com o X-Ray SDK para Node.js

Quando seu aplicativo faz chamadas Serviços da AWS para armazenar dados, gravar em uma fila ou enviar notificações, o X-Ray SDK para Node.js rastreia as chamadas downstream em subsegmentos. O rastreamento Serviços da AWS e os recursos que você acessa nesses serviços (por exemplo, um bucket do Amazon S3 ou uma fila do Amazon SQS) aparecem como nós downstream no mapa de rastreamento no console X-Ray.

Clientes AWS do Instrument SDK que você cria por meio da AWS SDK for JavaScript V2 ou AWS SDK for JavaScript V3. Cada versão do AWS SDK fornece métodos diferentes para instrumentar clientes AWS SDK.

nota

Atualmente, o AWS X-Ray SDK para Node.js retorna menos informações de segmentos ao instrumentar clientes AWS SDK for JavaScript V3, em comparação com a instrumentação de clientes V2. Por exemplo, os subsegmentos que representam chamadas para o DynamoDB não retornarão o nome da tabela. Se você precisar dessas informações de segmento em seus rastreamentos, considere usar o AWS SDK for JavaScript V2.

AWS SDK for JavaScript V2

Você pode instrumentar todos os clientes do AWS SDK V2 agrupando sua instrução aws-sdk require em uma chamada para. AWSXRay.captureAWS

exemplo app.js: instrumentação de SDK da AWS

const AWS = AWSXRay.captureAWS(require('aws-sdk'));

Para instrumentar clientes individuais, envolva seu cliente AWS SDK em uma chamada paraAWSXRay.captureAWSClient. Por exemplo, para instrumentar um cliente AmazonDynamoDB:

exemplo app.js: instrumentação de cliente do DynamoDB

    const AWSXRay = require('aws-xray-sdk');
...
    const ddb = AWSXRay.captureAWSClient(new AWS.DynamoDB());

Atenção

Não use captureAWS e captureAWSClient juntos. Isso resultará em subsegmentos duplicados.

Se você quiser usar TypeScriptcom módulos ECMAScript (ESM) para carregar seu JavaScript código, use o exemplo a seguir para importar bibliotecas:

exemplo app.js - Instrumentação AWS do SDK

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

Para instrumentar todos os AWS clientes com ESM, use o seguinte código:

exemplo app.js - Instrumentação AWS do 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 os serviços, o nome da API chamada no console do X-Ray pode ser visto. Para um subconjunto de serviços, o X-Ray SDK adiciona informações ao segmento para fornecer maior detalhamento no mapa de serviços.

Por exemplo, quando você faz uma chamada com um cliente instrumentado do DynamoDB, o SDK adiciona o nome da tabela ao segmento para chamadas direcionadas a uma tabela. No console, cada tabela aparece como um nó separado no mapa de serviços, com um nó genérico do DynamoDB para chamadas não direcionadas a uma tabela.

exemplo Subsegmento para uma chamada ao DynamoDB para salvar um item

{
  "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",
  }
}

Ao acessar recursos nomeados, as chamadas para os serviços os seguir criam nós adicionais no mapa de serviço. As chamadas que não apontam para recursos específicos criam um nó genérico para o serviço.

• Amazon DynamoDB: nome da tabela

• Amazon Simple Storage Service: nome de chave e bucket

• Amazon Simple Queue Service: nome da fila

AWS SDK for JavaScript V3

A AWS SDK for JavaScript V3 é modular, então seu código carrega apenas os módulos necessários. Por esse motivo, não é possível instrumentar todos os clientes do AWS SDK, pois a V3 não oferece suporte ao captureAWS método.

Se você quiser usar TypeScript com os Módulos ECMAScript (ESM) para carregar seu JavaScript código, você pode usar o exemplo a seguir para importar bibliotecas:

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

Instrumente cada cliente AWS SDK usando o AWSXRay.captureAWSv3Client método. Por exemplo, para instrumentar um cliente AmazonDynamoDB:

exemplo app.js: instrumentação de cliente do DynamoDB usando o SDK para Javascript V3

    const AWSXRay = require('aws-xray-sdk');
    const { DynamoDBClient } = require("@aws-sdk/client-dynamodb");
...
    const ddb = AWSXRay.captureAWSv3Client(new DynamoDBClient({ region: "region" }));

Ao usar a AWS SDK for JavaScript V3, metadados como nome da tabela, nome do bucket e da chave ou nome da fila não são retornados atualmente e, portanto, o mapa de rastreamento não conterá nós discretos para cada recurso nomeado, como faria ao instrumentar clientes AWS SDK usando a V2. AWS SDK for JavaScript

exemplo Subsegmento para uma chamada ao DynamoDB para salvar um item, ao usar a 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",
  }
}