使用适用于 Node.js 的 X-Ray SD AWS K 追踪 SDK 调用 - AWS X-Ray

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

使用适用于 Node.js 的 X-Ray SD AWS K 追踪 SDK 调用

当您的应用程序调用 AWS 服务 以存储数据、写入队列或发送通知时，适用于 Node.js 的 X-Ray SDK 会按子分段跟踪下游的调用。被跟踪 AWS 服务的资源以及您在这些服务中访问的资源（例如，Amazon S3 存储桶或 Amazon SQS 队列）在 X-Ray 控制台的跟踪地图上显示为下游节点。

您通过 AWS SDK for JavaScript V2 或AWS SDK for JavaScript V 3 创建的仪器 AWS SDK 客户端。每个 AWS SDK 版本都提供了不同的方法来检测 S AWS DK 客户端。

注意

目前，与检测 V2 客户端相比， AWS X-Ray 适用于 Node.js 的 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 SDK 工具
import * as AWS from 'aws-sdk';
import * as AWSXRay from 'aws-xray-sdk';

要使用 ESM 检测所有 AWS 客户端，请使用以下代码：

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

对于所有服务，都可以在 X-Ray 控制台中看到调用的 API 的名称。X-Ray 开发工具包会为一部分服务将信息添加到分段，从而在服务地图中提供更高的粒度。

例如，当使用经过检测的 DynamoDB 客户端发出调用时，对于针对表的调用，开发工具包会将表名称添加到分段中。在控制台中，每个表在服务地图中显示为一个独立的节点，以及没有表作为目标的调用的一般 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 Simple Storage Service - 存储桶和键名称

  • Amazon Simple Queue Service - 队列名称

AWS SDK for JavaScript V3

AWS SDK for JavaScript V3 是模块化的，因此您的代码只加载所需的模块。因此，不可能检测所有 AWS SDK 客户端，因为 V3 不支持该captureAWS方法。

如果要 TypeScript 与 ECMAScript 模块 (ESM) 一起使用来加载 JavaScript代码，则可以使用以下示例来导入库：

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

使用该AWSXRay.captureAWSv3Client方法检测每个 AWS SDK 客户端。例如，要检测 AmazonDynamoDB 客户端：

例 app.js - 使用适用于 Javascript V3 的开发工具包检测 DynamoDB 客户端
    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",
  }
}