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

# Rastreando chamadas AWS do SDK com o X-Ray SDK para Node.js
<a name="xray-sdk-nodejs-awssdkclients"></a>

**nota**  
Aviso de SDK/Daemon manutenção do X-Ray — Em 25 de fevereiro de 2026, o AWS X-Ray SDKs/Daemon entrará no modo de manutenção, onde AWS limitará as versões do X-Ray SDK e do Daemon para tratar apenas de problemas de segurança. Para obter mais informações sobre a linha do tempo do suporte, consulte [Cronograma de suporte do X-Ray SDK e do Daemon Support](xray-sdk-daemon-timeline.md). Recomendamos migrar para o. OpenTelemetry Para obter mais informações sobre a migração para OpenTelemetry, consulte [Migrando da instrumentação X-Ray para a instrumentação](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html). OpenTelemetry 

[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.](xray-sdk-nodejs-subsegments.md) 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 para JavaScript V2 ou AWS SDK para JavaScript V3](https://docs.aws.amazon.com/sdk-for-javascript/v2/developer-guide/welcome.html).](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/welcome.html) 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 para 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 para JavaScript V2. 

------
#### [ AWS SDK para 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`

**Example app.js - Instrumentação AWS do SDK**  

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

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

**Example 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 [TypeScript](https://www.typescriptlang.org/docs/handbook/typescript-in-5-minutes.html)com [ECMAScriptmódulos](https://nodejs.org/api/esm.html) (ESM) para carregar seu JavaScript código, use o exemplo a seguir para importar bibliotecas:

**Example 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:

**Example 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.

**Example 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 para JavaScript V3 ]

A AWS SDK para 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 quiser usar TypeScript com ECMAScript Módulos (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`:

**Example 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 para 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 para JavaScript 

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

------