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

# 配置适用于 Node.js 的 X-Ray 开发工具包
<a name="xray-sdk-nodejs-configuration"></a>

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

## 服务插件
<a name="xray-sdk-nodejs-configuration-plugins"></a>

`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` 字段。这表示运行您的应用程序的 AWS 资源类型。当您使用多个插件时，SDK 使用以下解析顺序来确定来源： ElasticBeanstalk > EKS > ECS > EC2。

## 采样规则
<a name="xray-sdk-nodejs-configuration-sampling"></a>

该 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 服务管理。随着您部署更多主机，固定速率会成倍增加，这使得控制记录的数据量变得更加困难。

开启后 AWS 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()
```

## 日志记录
<a name="xray-sdk-nodejs-configuration-logging"></a>

 要从开发工具包中记录输出，请调用 `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 进程守护程序地址
<a name="xray-sdk-nodejs-configuration-daemon"></a>

如果 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)来设置守护程序地址。

## 环境变量
<a name="xray-sdk-nodejs-configuration-envvars"></a>

您可以使用环境变量来配置适用于 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)分段名称。