Rastrear chamadas de SDK da AWS para o X-Ray SDK para Node.js - AWS X-Ray

As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Rastrear chamadas de SDK da AWS para o X-Ray SDK para Node.js

Quando a aplicação faz chamadas para 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 subsequentes em subsegmentos. Os Serviços da AWS rastreados e os recursos que você acessa nesses serviços (por exemplo, um bucket do Amazon S3 ou uma fila do Amazon SQS) são exibidos como nós subsequentes no mapa de rastreamento no console do X-Ray.

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

nota

No momento, o AWS X-Ray SDK para Node.js retorna menos informações de segmentos ao instrumentar clientes do AWS SDK for JavaScript V3, em comparação com a instrumentação de clientes do 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 de SDK da AWS V2 encapsulando sua instrução de exigência de aws-sdk 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, encapsule o cliente de SDK da AWS em uma chamada para AWSXRay.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 quiser usar o TypeScript com módulos ECMAScript (ESM) para carregar seu código JavaScript, use o exemplo a seguir para importar bibliotecas:

exemplo app.js: instrumentação de SDK da AWS
import * as AWS from 'aws-sdk';
import * as AWSXRay from 'aws-xray-sdk';

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

exemplo app.js: instrumentação de SDK da 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 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

O 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 de SDK da AWS, pois o V3 não oferece suporte ao método captureAWS.

Se quiser usar o TypeScript com módulos ECMAScript (ESM) para carregar o código JavaScript, 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 de SDK da AWS usando o método AWSXRay.captureAWSv3Client. 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 o 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; portanto, o mapa de rastreamento não conterá nós discretos para cada recurso nomeado, como ocorreria na instrumentação de clientes de SDK da AWS por meio do AWS SDK for JavaScript V2.

exemplo Subsegmento para uma chamada ao DynamoDB para salvar um item, ao usar o AWS SDK for JavaScript V3
{
  "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",
  }
}