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

# Amazon 适用于 Node.js 的 X-ray SDK
适用于 Node.js 的 X-Ray 开发工具包

**注意**  
X-Ray SDK/Daemon 维护通知 — 2026 年 2 月 25 日， Amazon X-Ray SDKs/Daemon 将进入维护模式，在该模式下，X-Ray SDK 和 Daemon 的发布 Amazon 将仅限于解决安全问题。有关支持时间表的更多信息，请参阅 [X-Ray SDK 和 Daemon Support 时间表](xray-sdk-daemon-timeline.md)。我们建议迁移到 OpenTelemetry。有关迁移到的更多信息 OpenTelemetry，请参阅[从 X-Ray 仪器迁移到 OpenTelemetry 仪器](https://docs.amazonaws.cn/xray/latest/devguide/xray-sdk-migration.html)。

X-Ray SDK for Node.js 是一个面向 Express Web 应用程序和 Node.js Lambda 函数的库，可提供类和方法来生成跟踪数据并将跟踪数据发送给 X-Ray 进程守护程序。跟踪数据包括有关应用程序处理的传入 HTTP 请求的信息，以及应用程序使用 Amazon SDK 或 HTTP 客户端对下游服务进行的调用的信息。

**注意**  
X-Ray SDK for Node.js 是一种开源项目，支持 Node.js 14.x 版本及更高版本。你可以关注该项目并在 [github 上 GitHub提交议题和拉取请求。 com/aws/aws](https://github.com/aws/aws-xray-sdk-node)-xray-sdk-node

如果您使用 Express，首先，在应用程序服务器上[添加 SDK 作为中间件](xray-sdk-nodejs-middleware.md)来跟踪传入请求。此中间件为每个被跟踪请求创建一个[分段](xray-concepts.md#xray-concepts-segments)并在发送响应时完成该分段。当分段打开时，您可以使用开发工具包客户端的方法将信息添加到分段，并创建子分段以跟踪下游调用。开发工具包还会自动记录在分段打开时应用程序引发的异常。

对于由经过检测的应用程序或服务调用的 Lambda 函数，Lambda 会读取[跟踪标头](xray-concepts.md#xray-concepts-tracingheader)并自动跟踪采样的请求。对于其他函数，您可以[将 Lambda 配置](xray-services-lambda.md)为采样和跟踪传入请求。无论哪种情况，Lambda 都会创建分段并将其提供给 X-Ray 开发工具包。

**注意**  
在 Lambda 上，X-Ray 开发工具包是可选的。如果您不在函数中使用它，您的服务映射仍将包含一个用于 Lambda 服务的节点，以及每个 Lambda 函数的节点。可通过添加该开发工具包检测函数代码，将子分段添加到 Lambda 记录的函数分段。请参阅[Amazon Lambda 和 Amazon X-Ray](xray-services-lambda.md)了解更多信息。

接下来，使用适用于 Node.js 的 X-Ray S [Amazon DK JavaScript 在 Node.js 客户端中检测你的](xray-sdk-nodejs-awssdkclients.md) SDK。每当您使用已检测的客户端调用下游 Amazon Web Services 服务 或资源时，SDK 都会在子分段中记录有关该调用的信息。 Amazon Web Services 服务 您在服务中访问的资源将作为下游节点显示在跟踪地图上，以帮助您识别各个连接上的错误和限制问题。

适用于 Node.js 的 X-Ray SDK 还为对 HTTP Web APIs 和 SQL 查询的下游调用提供了工具。[将 HTTP 客户端包含在 SDK 的捕获方法中](xray-sdk-nodejs-httpclients.md)以记录有关传出 HTTP 调用的信息。对于 SQL 客户端，[将捕获方法用于数据库类型](xray-sdk-nodejs-sqlclients.md)。

中间件将采用规则应用于传入请求以确定要跟踪的请求。您可以[配置适用于 Node.js 的 X-Ray SDK](xray-sdk-nodejs-configuration.md) 来调整采样行为或记录有关运行应用程序的 Amazon 计算资源的信息。

记录有关请求以及应用程序在[注释和元数据](xray-sdk-nodejs-segment.md)中所做的工作的其他信息。注释是简单的键值对，已为这些键值对编制索引以用于[筛选条件表达式](xray-console-filters.md)，以便您能够搜索包含特定数据的跟踪。元数据条目的限制性较低，并且可以记录整个对象和数组 - 可序列化为 JSON 的任何项目。

**注释和元数据**  
注释和元数据是您使用 X-Ray 开发工具包添加到分段的任意文本。系统会对注释编制索引，以便与筛选表达式一起使用。元数据未编制索引，但可以使用 X-Ray 控制台或 API 在原始分段中查看。您授予 X-Ray 读取权限的任何人都可以查看这些数据。

当代码中具有大量检测的客户端时，一个请求分段可包含大量子分段，检测的客户端发起的每个调用均对应一个子分段。您可以通过将客户端调用包含在[自定义子分段](xray-sdk-nodejs-subsegments.md)中来整理子分段并为其分组。您可以为整个函数或任何代码部分创建自定义子分段，并记录子分段的元数据和注释，而不是编写父分段的所有内容。

有关 SDK 的类和方法的参考文档，请参阅 [Amazon X-Ray SDK for Node.js API 参考](https://docs.amazonaws.cn//xray-sdk-for-nodejs/latest/reference)。

## 要求


X-Ray SDK for Node.js 需要 Node.js 和以下库：
+ `atomic-batcher` - 1.0.2
+ `cls-hooked` - 4.2.2
+ `pkginfo` - 0.4.0
+ `semver` - 5.3.0

在将 SDK 与 NPM 一起安装时，SDK 会拉入这些库。

要跟踪 Amazon SDK 客户端，适用于 Node.js 的 X-Ray Amazon SDK 需要 Node.js JavaScript 中最低版本的 SDK。
+ `aws-sdk` - 2.7.15

## 依赖关系管理


可从 NPM 获得 X-Ray SDK for Node.js。
+ **程序包** - [https://www.npmjs.com/package/aws-xray-sdk](https://www.npmjs.com/package/aws-xray-sdk)

对于本地开发，将 SDK 与 NPM 一起安装在项目目录中。

```
~/nodejs-xray$ npm install aws-xray-sdk
aws-xray-sdk@3.3.3
  ├─┬ aws-xray-sdk-core@3.3.3
  │ ├── @aws-sdk/service-error-classification@3.15.0
  │ ├── @aws-sdk/types@3.15.0
  │ ├─┬ @types/cls-hooked@4.3.3
  │ │ └── @types/node@15.3.0
  │ ├── atomic-batcher@1.0.2
  │ ├─┬ cls-hooked@4.2.2
  │ │ ├─┬ async-hook-jl@1.7.6
  │ │ │ └── stack-chain@1.3.7
  │ │ └─┬ emitter-listener@1.1.2
  │ │   └── shimmer@1.2.1
  │ └── semver@5.7.1
  ├── aws-xray-sdk-express@3.3.3
  ├── aws-xray-sdk-mysql@3.3.3
  └── aws-xray-sdk-postgres@3.3.3
```

使用 `--save` 选项可将 SDK 作为应用程序的 `package.json` 中的依赖项保存。

```
~/nodejs-xray$ npm install aws-xray-sdk --save
aws-xray-sdk@3.3.3
```

 如果应用程序具有任何其版本与 X-Ray SDK 的依赖项冲突的依赖项，则将会同时安装两个版本以确保兼容性。有关详细信息，请参阅[依赖项解析的官方 NPM 文档](http://npm.github.io/how-npm-works-docs/npm3/how-npm3-works.html)。

## Node.js 示例


使用 Amazon X-Ray 适用于 Node.js 的 SDK，在请求通过你的 Node.js 应用程序时 end-to-end查看这些请求。
+ [Node.js 示例应用程序已启用](https://github.com/aws-samples/aws-xray-sdk-node-sample) GitHub。

# 配置适用于 Node.js 的 X-Ray 开发工具包
配置

**注意**  
X-Ray SDK/Daemon 维护通知 — 2026 年 2 月 25 日， Amazon X-Ray SDKs/Daemon 将进入维护模式，在该模式下，X-Ray SDK 和 Daemon 的发布 Amazon 将仅限于解决安全问题。有关支持时间表的更多信息，请参阅 [X-Ray SDK 和 Daemon Support 时间表](xray-sdk-daemon-timeline.md)。我们建议迁移到 OpenTelemetry。有关迁移到的更多信息 OpenTelemetry，请参阅[从 X-Ray 仪器迁移到 OpenTelemetry 仪器](https://docs.amazonaws.cn/xray/latest/devguide/xray-sdk-migration.html)。

您可以配置带有插件的适用于 Node.js 的 X-Ray 开发工具包 以包括应用程序在其上运行的服务的相关信息，修改默认采样行为，或者添加应用于特定路径请求的采样规则。

**Topics**
+ [

## 服务插件
](#xray-sdk-nodejs-configuration-plugins)
+ [

## 采样规则
](#xray-sdk-nodejs-configuration-sampling)
+ [

## 日志记录
](#xray-sdk-nodejs-configuration-logging)
+ [

## X-Ray 进程守护程序地址
](#xray-sdk-nodejs-configuration-daemon)
+ [

## 环境变量
](#xray-sdk-nodejs-configuration-envvars)

## 服务插件


`plugins` 用于记录有关托管应用程序的服务的信息。

**插件**
+ Amazon EC2 — `EC2Plugin` 添加实例 ID、可用区和 CloudWatch 日志组。
+ Elastic Beanstalk - `ElasticBeanstalkPlugin` 添加环境名称、版本标签和部署 ID。
+ Amazon ECS — `ECSPlugin` 添加容器 ID。

要使用插件，请使用 `config` 方法配置适用于 Node.js 的 X-Ray 开发工具包客户端。

**Example app.js - 插件**  

```
var AWSXRay = require('aws-xray-sdk');
AWSXRay.config([AWSXRay.plugins.EC2Plugin,AWSXRay.plugins.ElasticBeanstalkPlugin]);
```

该 SDK 还使用插件设置为设置分段上的 `origin` 字段。这表示运行您的应用程序的 Amazon 资源类型。当您使用多个插件时，SDK 使用以下解析顺序来确定来源： ElasticBeanstalk > EKS > ECS > EC2。

## 采样规则


该 SDK 使用您在 X-Ray 控制台中定义的采样规则来确定要记录的请求。默认规则跟踪每秒的第一个请求，以及所有将跟踪发送到 X-Ray 的服务的任何其他请求的百分之五。[在 X-Ray 控制台中创建其他规则](xray-console-sampling.md)以自定义为每个应用程序记录的数据量。

该 SDK 按照定义的顺序应用自定义规则。如果请求与多个自定义规则匹配，则 SDK 仅应用第一条规则。

**注意**  
如果 SDK 无法访问 X-Ray 来获取采样规则，它将恢复为默认的本地规则，即每秒第一个请求以及每个主机所有其他请求的百分之五。如果主机无权调用采样，或者无法连接到 X-Ray 守护程序 APIs，后者充当 SDK 发出的 API 调用的 TCP 代理，则可能会发生这种情况。

您还可以将 SDK 配置为从 JSON 文档加载采样规则。在 X-Ray 采样不可用的情况下，SDK 可以使用本地规则作为备份，也可以只使用本地规则。

**Example sampling-rules.json**  

```
{
  "version": 2,
  "rules": [
    {
      "description": "Player moves.",
      "host": "*",
      "http_method": "*",
      "url_path": "/api/move/*",
      "fixed_target": 0,
      "rate": 0.05
    }
  ],
  "default": {
    "fixed_target": 1,
    "rate": 0.1
  }
}
```

此示例定义了一个自定义规则和一个默认规则。自定义规则采用百分之五的采样率，对于 `/api/move/` 之下的路径要跟踪的请求数量不设下限。默认规则中每秒的第一个请求以及其他请求的百分之十。

在本地定义规则的缺点是，固定目标由记录器的每个实例独立应用而不是由 X-Ray 服务管理。随着您部署更多主机，固定速率会成倍增加，这使得控制记录的数据量变得更加困难。

开启后 Amazon Lambda，您无法修改采样率。如果您的函数由检测服务调用，Lambda 将记录生成由该服务采样的请求的调用。如果启用了主动跟踪且不存在任何跟踪标头，则 Lambda 会做出采样决定。

要配置备份规则，请指示从具有适用于 Node.js 的 X-Ray 开发工具包 `setSamplingRules` 的文件加载采样规则。

**Example app.js - 来自文件的采样规则**  

```
var AWSXRay = require('aws-xray-sdk');
AWSXRay.middleware.setSamplingRules('sampling-rules.json');
```

您也可以在代码中定义规则，并将它们作为对象传递给 `setSamplingRules`。

**Example app.js - 来自对象的采样规则**  

```
var AWSXRay = require('aws-xray-sdk');
var rules = {
  "rules": [ { "description": "Player moves.", "service_name": "*", "http_method": "*", "url_path": "/api/move/*", "fixed_target": 0, "rate": 0.05 } ],
  "default": { "fixed_target": 1, "rate": 0.1 },
  "version": 1
  }

AWSXRay.middleware.setSamplingRules(rules);
```

要仅使用本地规则，请调用 `disableCentralizedSampling`。

```
AWSXRay.middleware.disableCentralizedSampling()
```

## 日志记录


 要从开发工具包中记录输出，请调用 `AWSXRay.setLogger(logger)`，其中 `logger` 是提供标准日志记录方法 (`warn`、`info` 等) 的对象。

默认情况下，开发工具包会使用控制台对象上的标准方法将错误消息记录到控制台。可以使用 `AWS_XRAY_DEBUG_MODE` 或 `AWS_XRAY_LOG_LEVEL` 环境变量设置内置记录器的日志级别。有关有效日志级别值的列表，请参阅[环境变量](#xray-sdk-nodejs-configuration-envvars)。

如果希望为日志提供不同的格式或目标，则可以提供包含您自己的记录器接口实现方式的开发工具包，如下所示。可以使用任何能够实现此接口的对象。这意味着，可以使用 Winton 等许多日志记录库并将其传递给开发工具包。

**Example app.js - 日志记录**  

```
var AWSXRay = require('aws-xray-sdk');

// Create your own logger, or instantiate one using a library.
var logger = {
  error: (message, meta) => { /* logging code */ },
  warn: (message, meta) => { /* logging code */ },
  info: (message, meta) => { /* logging code */ },
  debug: (message, meta) => { /* logging code */ }
}

AWSXRay.setLogger(logger);
AWSXRay.config([AWSXRay.plugins.EC2Plugin]);
```

在运行其他配置方法之前调用 `setLogger`，确保捕获这些操作的输出。

## X-Ray 进程守护程序地址


如果 X-Ray 进程守护程序侦听 `127.0.0.1:2000` 之外的端口或主机，则您可以配置适用于 Node.js 的 X-Ray 开发工具包将跟踪数据发送到不同的 UDP 地址。

```
AWSXRay.setDaemonAddress('host:port');
```

您可以按名称或 IPv4 地址指定主机。

**Example app.js - 进程守护程序地址**  

```
var AWSXRay = require('aws-xray-sdk');
AWSXRay.setDaemonAddress('daemonhost:8082');
```

如果您已将进程守护程序配置为在不同的端口上侦听 TCP 和 UDP，则可以同时在守护程序地址设置中指定二者。

**Example app.js – 不同的端口上的进程守护程序地址**  

```
var AWSXRay = require('aws-xray-sdk');
AWSXRay.setDaemonAddress('tcp:daemonhost:8082 udp:daemonhost:8083');
```

此外，您还可以通过使用 `AWS_XRAY_DAEMON_ADDRESS` [环境变量](#xray-sdk-nodejs-configuration-envvars)来设置守护程序地址。

## 环境变量


您可以使用环境变量来配置适用于 Node.js 的 X-Ray 开发工具包。SDK 支持以下变量。
+ `AWS_XRAY_CONTEXT_MISSING` - 设置为 `RUNTIME_ERROR` 在您的已检测代码尝试在分段未打开的情况下记录数据时引发异常。

**有效值**
  + `RUNTIME_ERROR`— 引发运行时异常。
  + `LOG_ERROR`— 记录错误并继续（默认）。
  + `IGNORE_ERROR`— 忽略错误并继续。

  对于在未打开任何请求时运行的启动代码或者会生成新线程的代码，如果您尝试在其中使用检测过的客户端，则可能发生与缺失分段或子分段相关的错误。
+ `AWS_XRAY_DAEMON_ADDRESS` - 设置 X-Ray 进程守护程序侦听器的主机和端口。默认情况下，SDK 使用用于跟踪数据（UDP）和采样（TCP）的 `127.0.0.1:2000`。如果您已将进程守护程序配置为[侦听不同端口](xray-daemon-configuration.md)或者进程守护程序在另一台主机上运行，则使用此变量。

**Format**
  + **同一个端口** — `address:port`
  + **不同的端口** — `tcp:address:port udp:address:port`
+ `AWS_XRAY_DEBUG_MODE` - 设置为 `TRUE` 以配置开发工具包在 `debug` 级别将日志输出到控制台。
+ `AWS_XRAY_LOG_LEVEL ` - 设置日志记录程序的默认日志级别。有效值为 `debug`、`info`、`warn`、`error` 和 `silent`。当设置为时 AWS\$1XRAY\$1DEBUG\$1MODE ，该值将被忽略`TRUE`。
+ `AWS_XRAY_TRACING_NAME` - 设置 SDK 用于进行分段的服务名称。覆盖您[通过 Express 中间件设置的](xray-sdk-nodejs-middleware.md)分段名称。

# 使用适用于 Node.js 的 X-Ray 开发工具包跟踪传入请求
传入请求

**注意**  
X-Ray SDK/Daemon 维护通知 — 2026 年 2 月 25 日， Amazon X-Ray SDKs/Daemon 将进入维护模式，在该模式下，X-Ray SDK 和 Daemon 的发布 Amazon 将仅限于解决安全问题。有关支持时间表的更多信息，请参阅 [X-Ray SDK 和 Daemon Support 时间表](xray-sdk-daemon-timeline.md)。我们建议迁移到 OpenTelemetry。有关迁移到的更多信息 OpenTelemetry，请参阅[从 X-Ray 仪器迁移到 OpenTelemetry 仪器](https://docs.amazonaws.cn/xray/latest/devguide/xray-sdk-migration.html)。

你可以使用适用于 Node.js 的 X-Ray SDK 来跟踪你的 Express 和 Restify 应用程序在亚马逊 EC2 或 Amazon ECS 的 EC2 实例上提供的 Amazon Elastic Beanstalk传入 HTTP 请求。

适用于 Node.js 的 X-Ray 开发工具包为使用 Express 和 Restify 框架的应用程序提供中间件。在您将 X-Ray 中间件添加到应用程序时，适用于 Node.js 的 X-Ray 开发工具包会为每个采样请求创建一个分段。此分段包括 HTTP 请求的计时、方法和处置。其他检测会在此分段上创建子分段。

**注意**  
对于 Amazon Lambda 函数，Lambda 会为每个采样请求创建一个分段。请参阅[Amazon Lambda 和 Amazon X-Ray](xray-services-lambda.md)了解更多信息。

每个分段都有一个名称，用于在服务映射中标识您的应用程序。可以静态命名分段，也可以将 SDK 配置为根据传入请求中的主机标头对其进行动态命名。动态命名允许根据请求中的域名对跟踪进行分组，并且在名称不匹配预期模式时（例如，如果主机标头是伪造的）应用默认名称。

**转发的请求**  
如果负载均衡器或其他中间将请求转发到您的应用程序，X-Ray 会提取请求 `X-Forwarded-For` 标头中的客户端 IP 而非 IP 数据包中的源 IP。由于转发的请求记录的客户端 IP 可以伪造，因此不应信任。

在转发请求时，SDK 在分段中设置附加字段来指示此行为。如果分段包含设置为 `x_forwarded_for` 的字段 `true`，则从 HTTP 请求的 `X-Forwarded-For` 标头获取客户端 IP。

信息处理程序使用包含以下信息的 `http` 数据块为每个传入请求创建一个分段：
+ **HTTP 方法** - GET、POST、PUT、DELETE 等。
+ **客户端地址** - 发送请求的客户端的 IP 地址。
+ **响应代码** - 已完成请求的 HTTP 响应代码。
+ **时间** - 开始时间（收到请求时）和结束时间（发送响应时）。
+ **用户代理** - 请求中的 `user-agent`。
+ **内容长度** - 响应中的 `content-length`。

**Topics**
+ [

## 通过 Express 跟踪传入请求
](#xray-sdk-nodejs-middleware-express)
+ [

## 通过 Restify 跟踪传入请求
](#xray-sdk-nodejs-middleware-restify)
+ [

## 配置分段命名策略
](#xray-sdk-nodejs-middleware-naming)

## 通过 Express 跟踪传入请求


要使用 Express 中间件，请在定义路由前，先初始化开发工具包客户端并使用 `express.openSegment` 函数返回的中间件。

**Example app.js - Express**  

```
var app = express();

var AWSXRay = require('aws-xray-sdk');
app.use(AWSXRay.express.openSegment('MyApp'));

app.get('/', function (req, res) {
  res.render('index');
});

app.use(AWSXRay.express.closeSegment());
```

定义路由后，按照所示方式使用 `express.closeSegment` 的输出，以便处理适用于 Node.js 的 X-Ray 开发工具包返回的任何错误。

## 通过 Restify 跟踪传入请求


要使用 Restify 中间件，请初始化开发工具包客户端并运行 `enable`。将您的 Restify 服务器和分段名传递给它。

**Example app.js - Restify**  

```
var AWSXRay = require('aws-xray-sdk');
var AWSXRayRestify = require('aws-xray-sdk-restify');

var restify = require('restify');
var server = restify.createServer();
AWSXRayRestify.enable(server, 'MyApp'));

server.get('/', function (req, res) {
  res.render('index');
});
```

## 配置分段命名策略


Amazon X-Ray 使用*服务名称*来标识您的应用程序，并将其与您的应用程序使用的其他应用程序、数据库 APIs、外部数据库和 Amazon 资源区分开来。当 X-Ray SDK 为传入请求生成分段时，会将应用程序的服务名称记录在分段的[名称字段](xray-api-segmentdocuments.md#api-segmentdocuments-fields)中。

X-Ray SDK 可以用在 HTTP 请求标头中的 hostname 来命名分段。不过，此标头可以伪造，会导致服务地图中出现意料之外的节点。为防止 SDK 由于包含伪造的主机标头的请求而错误地命名分段，必须为传入请求指定一个默认名称。

如果应用程序为多个域的请求提供服务，则可以将 SDK 配置为使用动态命名策略以在分段名称中反映出这一点。动态命名策略允许 SDK 将主机名用于符合预期模式的请求，并将默认名称应用于不符合预期模式的请求。

例如，可能有一款应用程序为发送到三个子域的请求提供服务，分别为 `www.example.com`、`api.example.com` 和 `static.example.com`。可以使用格式 `*.example.com` 的动态命名策略以识别包含不同名称的子域的分段，服务地图上因此会显示三个服务节点。如果应用程序收到包含与该格式不匹配的 hostname 的请求，您将会在服务地图上看到第四个节点，以及您指定的回退名称。

要对所有请求分段使用相同名称，请在初始化中间件时指定应用程序的名称，如前几节所示。

**注意**  
您可以使用 `AWS_XRAY_TRACING_NAME` [环境变量](xray-sdk-nodejs-configuration.md#xray-sdk-nodejs-configuration-envvars)覆盖您在代码中定义的默认服务名称。

动态命名策略定义一个主机名应匹配的模式和一个在 HTTP 请求中的主机名与该模式不匹配时要使用的默认名称。要动态命名分段，请使用 `AWSXRay.middleware.enableDynamicNaming`。

**Example app.js - 动态分段名称**  
如果请求中的主机名与模式 `*.example.com` 匹配，请使用主机名。否则，请使用 `MyApp`。  

```
var app = express();

var AWSXRay = require('aws-xray-sdk');
app.use(AWSXRay.express.openSegment('MyApp'));
AWSXRay.middleware.enableDynamicNaming('*.example.com');
        
app.get('/', function (req, res) {
  res.render('index');
});

app.use(AWSXRay.express.closeSegment());
```

# 使用适用于 Node.js 的 X-Ray SD Amazon K 追踪 SDK 调用
Amazon SDK 客户端

**注意**  
X-Ray SDK/Daemon 维护通知 — 2026 年 2 月 25 日， Amazon X-Ray SDKs/Daemon 将进入维护模式，在该模式下，X-Ray SDK 和 Daemon 的发布 Amazon 将仅限于解决安全问题。有关支持时间表的更多信息，请参阅 [X-Ray SDK 和 Daemon Support 时间表](xray-sdk-daemon-timeline.md)。我们建议迁移到 OpenTelemetry。有关迁移到的更多信息 OpenTelemetry，请参阅[从 X-Ray 仪器迁移到 OpenTelemetry 仪器](https://docs.amazonaws.cn/xray/latest/devguide/xray-sdk-migration.html)。

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

您通过 [适用于 JavaScript 的 Amazon SDK V2 或适用于 JavaScript 的 Amazon SDK V](https://docs.amazonaws.cn/sdk-for-javascript/v2/developer-guide/welcome.html) [3](https://docs.amazonaws.cn/sdk-for-javascript/v3/developer-guide/welcome.html) 创建的仪器 Amazon SDK 客户端。每个 Amazon SDK 版本都提供了不同的方法来检测 S Amazon DK 客户端。

**注意**  
目前，与检测 V2 客户端相比， Amazon X-Ray 适用于 Node.js 的 SDK 在检测 适用于 JavaScript 的 Amazon SDK V3 客户端时返回的细分信息较少。例如，代表对 DynamoDB 的子分段不会返回表名称。如果您在跟踪中需要此区段信息，请考虑使用 适用于 JavaScript 的 Amazon SDK V2。

------
#### [ 适用于 JavaScript 的 Amazon SDK V2 ]

您可以通过在调用中包装 `aws-sdk` require 语句来检测所有 Amazon SDK V2 客户端。`AWSXRay.captureAWS`

**Example app.js- Amazon SDK 工具**  

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

要检测单个客户端，请将您的 Amazon SDK 客户端封装在调用中`AWSXRay.captureAWSClient`。例如，要检测 `AmazonDynamoDB` 客户端：

**Example app.js - DynamoDB 客户端检测**  

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

**警告**  
不要将 `captureAWS` 和 `captureAWSClient` 一起使用。这将导致重复的子分段。

如果要[TypeScript](https://www.typescriptlang.org/docs/handbook/typescript-in-5-minutes.html)使用[ECMAScript模块](https://nodejs.org/api/esm.html) (ESM) 来加载JavaScript代码，请使用以下示例来导入库：

**Example app.js- Amazon SDK 工具**  

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

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

**Example app.js- Amazon 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 节点。

**Example 对 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** - 队列名称

------
#### [ 适用于 JavaScript 的 Amazon SDK V3 ]

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

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

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

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

**Example app.js - 使用 SDK for Javascript V3 检测 DynamoDB 客户端**  

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

使用 适用于 JavaScript 的 Amazon SDK V3 时，当前不会返回表名、存储桶和密钥名称或队列名称等元数据，因此跟踪映射不会像使用 适用于 JavaScript 的 Amazon SDK V2 检测 Amazon SDK 客户端时那样包含每个命名资源的离散节点。

**Example 使用 V3 时调用 DynamoDB 以保存项目的子分段 适用于 JavaScript 的 Amazon SDK**  

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

------

# 使用适用于 Node.js 的 X-Ray 开发工具包跟踪对下游 HTTP Web 服务的调用
传出 HTTP 调用

**注意**  
X-Ray SDK/Daemon 维护通知 — 2026 年 2 月 25 日， Amazon X-Ray SDKs/Daemon 将进入维护模式，在该模式下，X-Ray SDK 和 Daemon 的发布 Amazon 将仅限于解决安全问题。有关支持时间表的更多信息，请参阅 [X-Ray SDK 和 Daemon Support 时间表](xray-sdk-daemon-timeline.md)。我们建议迁移到 OpenTelemetry。有关迁移到的更多信息 OpenTelemetry，请参阅[从 X-Ray 仪器迁移到 OpenTelemetry 仪器](https://docs.amazonaws.cn/xray/latest/devguide/xray-sdk-migration.html)。

当您的应用程序调用微服务或公共 HTTP 时 APIs，您可以使用适用于 Node.js 的 X-Ray SDK 客户端来检测这些调用，并将该 API 作为下游服务添加到服务图中。

将您的 `http` 或 `https` 客户端传递给适用于 Node.js 的 X-Ray 开发工具包的 `captureHTTPs` 方法以跟踪传出调用。

**注意**  
支持通过 [`captureHTTPsGlobal()` API](https://docs.amazonaws.cn/xray-sdk-for-nodejs/latest/reference/module-http_p.html) 使用第三方 HTTP 请求库（如 Axios 或 Superagent）进行调用，并且在使用原生 `http` 模块时仍会跟踪它们。

**Example app.js - HTTP 客户端**  

```
var AWSXRay = require('aws-xray-sdk');
var http = AWSXRay.captureHTTPs(require('http'));
```

要在所有 HTTP 客户端上启用跟踪，请先调用 `captureHTTPsGlobal`，然后加载 `http`。

**Example app.js - HTTP 客户端（全局）**  

```
var AWSXRay = require('aws-xray-sdk');
AWSXRay.captureHTTPsGlobal(require('http'));
var http = require('http');
```

当您检测对下游 Web API 的调用时，适用于 Node.js 的 X-Ray 开发工具包记录一个子分段，其中包含有关 HTTP 请求和响应的信息。X-Ray 使用子分段为远程 API 生成推断分段。

**Example 下游 HTTP 调用的子分段**  

```
{
  "id": "004f72be19cddc2a",
  "start_time": 1484786387.131,
  "end_time": 1484786387.501,
  "name": "names.example.com",
  "namespace": "remote",
  "http": {
    "request": {
      "method": "GET",
      "url": "https://names.example.com/"
    },
    "response": {
      "content_length": -1,
      "status": 200
    }
  }
}
```

**Example 下游 HTTP 调用的推断分段**  

```
{
  "id": "168416dc2ea97781",
  "name": "names.example.com",
  "trace_id": "1-62be1272-1b71c4274f39f122afa64eab",
  "start_time": 1484786387.131,
  "end_time": 1484786387.501,
  "parent_id": "004f72be19cddc2a",
  "http": {
    "request": {
      "method": "GET",
      "url": "https://names.example.com/"
    },
    "response": {
      "content_length": -1,
      "status": 200
    }
  },
  "inferred": true
}
```

# 使用适用于 Node.js 的 X-Ray 开发工具包跟踪 SQL 查询
SQL 查询

**注意**  
X-Ray SDK/Daemon 维护通知 — 2026 年 2 月 25 日， Amazon X-Ray SDKs/Daemon 将进入维护模式，在该模式下，X-Ray SDK 和 Daemon 的发布 Amazon 将仅限于解决安全问题。有关支持时间表的更多信息，请参阅 [X-Ray SDK 和 Daemon Support 时间表](xray-sdk-daemon-timeline.md)。我们建议迁移到 OpenTelemetry。有关迁移到的更多信息 OpenTelemetry，请参阅[从 X-Ray 仪器迁移到 OpenTelemetry 仪器](https://docs.amazonaws.cn/xray/latest/devguide/xray-sdk-migration.html)。

通过将 SQL 客户端包含在相应的适用于 Node.js 的 X-Ray 开发工具包客户端方法中来检测 SQL 数据库查询。
+  **PostgreSQL** – `AWSXRay.capturePostgres()` 

  ```
  var AWSXRay = require('aws-xray-sdk');
  var pg = AWSXRay.capturePostgres(require('pg'));
  var client = new pg.Client();
  ```
+  **MySQL** – `AWSXRay.captureMySQL()` 

  ```
  var AWSXRay = require('aws-xray-sdk');
  var mysql = AWSXRay.captureMySQL(require('mysql'));
  ...
  var connection = mysql.createConnection(config);
  ```

在使用检测的客户端发起 SQL 查询时，适用于 Node.js 的 X-Ray 开发工具包会在子分段中记录有关连接和查询的信息。

## 在 SQL 子段中包括其他数据


您可以向为 SQL 查询生成的子分段添加其他信息，前提是这些子分段已映射到允许列表的 SQL 字段。例如，要在子段中记录经过清理的 SQL 查询字符串，可以将其直接添加到子分段的 SQL 对象中。

**Example 将 SQL 分配给子分段**  

```
    const queryString = 'SELECT * FROM MyTable';
connection.query(queryString, ...);

// Retrieve the most recently created subsegment
const subs = AWSXRay.getSegment().subsegments;

if (subs & & subs.length > 0) {
  var sqlSub = subs[subs.length - 1];
  sqlSub.sql.sanitized_query = queryString;
}
```

请参阅 *Amazon X-Ray 开发人员指南*中的 [SQL 查询](https://docs.amazonaws.cn/xray/latest/devguide/xray-api-segmentdocuments.html#api-segmentdocuments-sql)，查看加入允许列表的 SQL 字段的完整列表。

# 使用 X-Ray SDK for Node.js 生成自定义子分段
自定义子分段

子分段可为跟踪的[分段](xray-concepts.md#xray-concepts-segments)扩展为了给请求提供服务而已完成的工作的详细信息。每次使用已检测的客户端进行调用时，X-Ray SDK 在子分段中记录生成的信息。您可以创建其他子分段来分组其他子分段，来度量某个代码段的性能如何，或是来记录注释和元数据。

## 自定义 Express 子分段


**注意**  
X-Ray SDK/Daemon 维护通知 — 2026 年 2 月 25 日， Amazon X-Ray SDKs/Daemon 将进入维护模式，在该模式下，X-Ray SDK 和 Daemon 的发布 Amazon 将仅限于解决安全问题。有关支持时间表的更多信息，请参阅 [X-Ray SDK 和 Daemon Support 时间表](xray-sdk-daemon-timeline.md)。我们建议迁移到 OpenTelemetry。有关迁移到的更多信息 OpenTelemetry，请参阅[从 X-Ray 仪器迁移到 OpenTelemetry 仪器](https://docs.amazonaws.cn/xray/latest/devguide/xray-sdk-migration.html)。

使用 `captureAsyncFunc` 函数为调用下游服务的函数创建自定义子分段。

**Example app.js - 自定义子分段表示**  

```
var AWSXRay = require('aws-xray-sdk');

app.use(AWSXRay.express.openSegment('MyApp'));

app.get('/', function (req, res) {
  var host = 'api.example.com';

  AWSXRay.captureAsyncFunc('send', function(subsegment) {
    sendRequest(host, function() {
      console.log('rendering!');
      res.render('index');
      subsegment.close();
    });
  });
});

app.use(AWSXRay.express.closeSegment());

function sendRequest(host, cb) {
  var options = {
    host: host,
    path: '/',
  };

  var callback = function(response) {
    var str = '';

    response.on('data', function (chunk) {
      str += chunk;
    });

    response.on('end', function () {
      cb();
    });
  }

  http.request(options, callback).end();
};
```

在本示例中，应用程序将创建一个名为 `send` 的自定义子分段以调用 `sendRequest` 函数。`captureAsyncFunc` 传递您在回调函数发出的异步调用完成时必须在回调函数内关闭的子分段。

对于同步函数，您可以使用 `captureFunc` 函数，这会在函数块完成执行时立即自动结束子分段。

当您在分段或者其他子分段中创建子分段时，X-Ray SDK for Node.js 将为其生成 ID 并记录开始时间和结束时间。

**Example 包含元数据的子分段**  

```
"subsegments": [{
  "id": "6f1605cd8a07cb70",
  "start_time": 1.480305974194E9,
  "end_time": 1.4803059742E9,
  "name": "Custom subsegment for UserModel.saveUser function",
  "metadata": {
    "debug": {
      "test": "Metadata string from UserModel.saveUser"
    }
  },
```

## 自定义 Lambda 子分段


该 SDK 配置为在检测到运行于 Lambda 中时，将自动创建占位符 Facade 分段。要创建基本子分段（这将在 X-Ray 跟踪地图上创建单个 `AWS::Lambda::Function` 节点），请调用并重新调整 Facade 分段。如果您手动创建具有新 ID 的新分段（同时共享跟踪 ID、父 ID 和采样决策），则可以发送新分段。

**Example app.js - 手动自定义子分段**  

```
const segment = AWSXRay.getSegment(); //returns the facade segment
const subsegment = segment.addNewSubsegment('subseg');
...
subsegment.close();
//the segment is closed by the SDK automatically
```

# 使用 X-Ray SDK for Node.js，将注释和元数据添加到分段
注释和元数据

**注意**  
X-Ray SDK/Daemon 维护通知 — 2026 年 2 月 25 日， Amazon X-Ray SDKs/Daemon 将进入维护模式，在该模式下，X-Ray SDK 和 Daemon 的发布 Amazon 将仅限于解决安全问题。有关支持时间表的更多信息，请参阅 [X-Ray SDK 和 Daemon Support 时间表](xray-sdk-daemon-timeline.md)。我们建议迁移到 OpenTelemetry。有关迁移到的更多信息 OpenTelemetry，请参阅[从 X-Ray 仪器迁移到 OpenTelemetry 仪器](https://docs.amazonaws.cn/xray/latest/devguide/xray-sdk-migration.html)。

可以利用注释和元数据记录与请求、环境或应用程序相关的其他信息。可以将注释和元数据添加到 X-Ray 开发工具包创建的分段或您创建的自定义子分段。

**注释**是带字符串、数字或布尔值的键值对。系统会对注释编制索引，以便与[筛选表达式](xray-console-filters.md)一起使用。使用注释记录要用于对控制台中的跟踪进行分组的数据或在调用 [https://docs.amazonaws.cn/xray/latest/api/API_GetTraceSummaries.html](https://docs.amazonaws.cn/xray/latest/api/API_GetTraceSummaries.html) API 时使用的数据。

**元数据**是可以具有任何类型值的键-值对，包括对象和列表，但没有编制索引，无法与筛选条件表达式一起使用。使用元数据记录要存储在跟踪中但不需要用于搜索跟踪的其他数据。

除了注释和元数据之外，您还可以在分段上[记录用户 ID 字符串](#xray-sdk-nodejs-segment-userid)。用户 IDs 被记录在区段的单独字段中，并编制索引以供搜索使用。

**Topics**
+ [

## 使用 X-Ray SDK for Node.js 记录注释
](#xray-sdk-nodejs-segment-annotations)
+ [

## 使用 X-Ray SDK for Node.js 记录元数据
](#xray-sdk-nodejs-segment-metadata)
+ [

## 使用适用于 Node.js 的 X-R IDs ay SDK 录制用户
](#xray-sdk-nodejs-segment-userid)

## 使用 X-Ray SDK for Node.js 记录注释


使用注释记录有关要为其编制索引以进行搜索的分段和子分段的信息。

**注释要求**
+ **键** - X-Ray 注释的键最多可以包含 500 个字母数字字符。除了点或句点（.）之外，不能使用空格或符号
+ **值** - X-Ray 注释的值最多可以包含 1,000 个 Unicode 字符。
+ **注释**的数量 - 每个跟踪最多可使用 50 条注释。

**记录注释**

1. 获取对当前分段或子分段的引用。

   ```
   var AWSXRay = require('aws-xray-sdk');
   ...
   var document = AWSXRay.getSegment();
   ```

1. 调用带有字符串键和布尔值、数字值或字符串值的 `addAnnotation`。

   ```
   document.addAnnotation("mykey", "my value");
   ```

   以下示例说明如何使用包含点和布尔值、数字值或字符串值的字符串键调用 `putAnnotation`。

   ```
   document.putAnnotation("testkey.test", "my value");
   ```

开发工具包将注释以键-值对的形式记录在分段文档的 `annotations` 对象中。使用相同键调用两次 `addAnnotation` 将覆盖同一分段或子分段上之前记录的值。

要查找具有带特定值的注释的跟踪，请在`annotation[key]`筛选表达式[中使用 ](xray-console-filters.md) 关键字。

**Example app.js - 注释**  

```
var AWS = require('aws-sdk');
var AWSXRay = require('aws-xray-sdk');
var ddb = AWSXRay.captureAWSClient(new AWS.DynamoDB());
...
app.post('/signup', function(req, res) {
    var item = {
        'email': {'S': req.body.email},
        'name': {'S': req.body.name},
        'preview': {'S': req.body.previewAccess},
        'theme': {'S': req.body.theme}
    };

    var seg = AWSXRay.getSegment();
    seg.addAnnotation('theme', req.body.theme);
  
    ddb.putItem({
      'TableName': ddbTable,
      'Item': item,
      'Expected': { email: { Exists: false } }
  }, function(err, data) {
...
```

## 使用 X-Ray SDK for Node.js 记录元数据


使用元数据记录有关您无需为其编制索引以进行搜索的分段或子分段的信息。元数据值可以是字符串、数字、布尔值或可序列化为 JSON 对象或数组的任何其他对象。

**记录元数据**

1. 获取对当前分段或子分段的引用。

   ```
   var AWSXRay = require('aws-xray-sdk');
   ...
   var document = AWSXRay.getSegment();
   ```

1. 使用字符串键、布尔值、数字、字符串或对象值以及字符串命名空间调用 `addMetadata`。

   ```
   document.addMetadata("my key", "my value", "my namespace");
   ```

   或者

   调用仅带有键和值的 `addMetadata`。

   ```
   document.addMetadata("my key", "my value");
   ```

如果您没有指定命名空间，则开发工具包将使用 `default`。使用相同键调用两次 `addMetadata` 将覆盖同一分段或子分段上之前记录的值。

## 使用适用于 Node.js 的 X-R IDs ay SDK 录制用户


记录请求细分中的用户，以识别发送请求的用户。 IDs 此操作与 Amazon Lambda 函数不兼容，因为 Lambda 环境中的分段是不可变的。仅可以对分段而不能对子分段应用 `setUser` 调用。

**要记录用户 IDs**

1. 获取对当前分段或子分段的引用。

   ```
   var AWSXRay = require('aws-xray-sdk');
   ...
   var document = AWSXRay.getSegment();
   ```

1. 使用发送请求的用户的字符串 ID 调用 `setUser()`。

   ```
   var user = 'john123';
   
   AWSXRay.getSegment().setUser(user);
   ```

您可以调用 `setUser` 以便在快速应用程序开始处理请求后立即记录用户 ID。如果您只打算使用分段来设置用户 ID，可以在单个行中链接这些调用。

**Example app.js - 用户 ID**  

```
var AWS = require('aws-sdk');
var AWSXRay = require('aws-xray-sdk');
var uuidv4 = require('uuid/v4');
var ddb = AWSXRay.captureAWSClient(new AWS.DynamoDB());
...
    app.post('/signup', function(req, res) {
    var userId = uuidv4();
    var item = {
        'userId': {'S': userId},
        'email': {'S': req.body.email},
        'name': {'S': req.body.name}
    };

    var seg = AWSXRay.getSegment().setUser(userId);
  
    ddb.putItem({
      'TableName': ddbTable,
      'Item': item,
      'Expected': { email: { Exists: false } }
  }, function(err, data) {
...
```

要查找用户 ID 的跟踪，请在`user`筛选表达式[中使用 ](https://docs.amazonaws.cn/xray/latest/devguide/xray-console-filters.html) 关键字。