本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# Amazon 适用于 Node.js 的 X-ray 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)。
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。