使用適用於 Node.js 的 X-Ray AWS SDK 追蹤 SDK 呼叫

當您的應用程式呼叫 AWS 服務 以儲存資料、寫入佇列或傳送通知時，Node.js 的 X-Ray SDK 會追蹤子區段中下游的呼叫。追蹤和您在這些服務中存取的資源 (例如，Amazon S3 儲存貯體或 Amazon SQS 佇列) 會在 X-Ray 主控 AWS 服務台的追蹤對應上顯示為下游節點。

您透過 AWS SDK for JavaScript V2 或 AWS SDK for JavaScript V3 建立的儀器 AWS SDK 用戶端。每個 AWS SDK 版本都提供不同的方法來檢測 AWS SDK 用戶端。

注意

目前，與檢測 V2 用戶端相比，Node.js 的 AWS X-Ray SDK 會在檢測 AWS SDK for JavaScript V3 用戶端時傳回較少的區段資訊。例如，代表呼叫 DynamoDB 的子區段不會傳回資料表名稱。如果您在追蹤中需要此區段資訊，請考慮使用 AWS SDK for JavaScript V2。

AWS SDK for JavaScript V2

您可以通過在呼叫中包裝您的 aws-sdk require 語句來檢測所有 AWS SDK V2 客戶端AWSXRay.captureAWS。

範例 app.js AWS 工具开发工具

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

若要檢測個別用戶端，請將您的 AWS SDK 用戶端包裝在呼叫中AWSXRay.captureAWSClient。例如，若要檢測 AmazonDynamoDB 用戶端：

範例 app.js-DynamoDB 端儀器

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

警告

請勿將 captureAWS 和 captureAWSClient 一起使用。這會導致重複的子區段。

如果您想要使TypeScript用 ECMAScript 模組 (ESM) 來載入JavaScript程式碼，請使用下列範例來匯入程式庫：

範例 app.js AWS 工具开发工具

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

若要使用 ESM 檢測所有用 AWS 戶端，請使用下列程式碼：

範例 app.js 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();

對於所有服務，您都可以在 X-Ray 控制台中看到調用的 API 的名稱。對於服務子集，X-Ray SDK 會將資訊新增至區段，以在服務對應中提供更多精細度。

例如，當您使用已檢測的 DynamoDB 用戶端進行呼叫時，SDK 會將資料表名稱新增至區段，以便針對以資料表為目標的呼叫。在主控台中，每個表格在服務對應中顯示為個別節點，其中包含一般 DynamoDB 節點，用於未針對資料表的呼叫。

範例 呼叫 DynamoDB 以儲存項目的子區段

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

您存取具名資源時，對以下服務的呼叫會在服務地圖中建立額外節點。未針對特定資源的呼叫，則會建立服務的一般節點。

• Amazon DynamoDB — 表名

• Amazon 簡單存儲服務 — 存儲桶和密鑰名稱

• Amazon 簡單隊列服務-隊列名稱

AWS SDK for JavaScript V3

AWS SDK for JavaScript V3 是模塊化的，所以你的代碼只加載它需要的模塊。因此，由於 V3 不支持該captureAWS方法，因此無法檢測所有 AWS SDK 客戶端。

如果您想要使 TypeScript 用 ECMAScript 模組 (ESM) 來載入 JavaScript程式碼，您可以使用下列範例來匯入程式庫：

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

使用該AWSXRay.captureAWSv3Client方法檢測每個 AWS SDK 客戶端。例如，若要檢測 AmazonDynamoDB 用戶端：

範例 app.js-DynamoDB SDK 的客戶端儀器

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

使用 AWS SDK for JavaScript V3 時，目前不會傳回資料表名稱、儲存貯體和金鑰名稱或佇列名稱等中繼資料，因此追蹤對應不會像使用 AWS SDK for JavaScript V2 檢測 AWS SDK 用戶端時一樣包含每個已命名資源的離散節點。

範例 使用 V3 時，呼叫 DynamoDB 以儲存項目的子區段 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",
  }
}