Amazon适用于 Node.js 的 X-Ray 软 - Amazon X-Ray
要求依赖项管理Node.js 示例
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

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

Amazon适用于 Node.js 的 X-Ray 软

适用于 Node.js 的 X-Ray 开发工具包是一个面向 Express Web 应用程序和 Node.js Lambda 函数的库，提供类和方法来生成跟踪数据并将跟踪数据发送给 X-Ray 守护程序 跟踪数据包括有关由应用程序提供服务的传入 HTTP 请求的相关信息，以及应用程序使用Amazon开发工具包或 HTTP 客户端。

注意

适用于 Node.js 的 X-Ray 开发工具包是一个开源项目。您可以跟踪该项目并在 GitHub 上提交问题和拉取请求：github.com/aws/aws-xray-sdk-node

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

对于由分析应用程序或服务调用的 Lambda 函数，Lambda 会读取跟踪标头并自动跟踪采样的请求。对于其他功能，你可以配置 Lambda对传入请求进行采样和跟踪。无论哪种情况，Lambda 都会创建区段并将其提供给 X-Ray SDK。

注意

在 Lambda 上，X-Ray 开发工具包是可选的。如果您不在函数中使用它，则您的服务映射仍将包含 Lambda 服务的节点，每个 Lambda 函数都包含一个节点。通过添加开发工具包，您可以对函数代码进行调整，将子区段添加到 Lambda 记录的函数区段。参阅 Amazon Lambda 和 Amazon X-Ray 了解更多信息。

然后，使用适用于 Node.js 的 X-Ray 开发工具包分析您的Amazon适用于 JavaScript 在 Node.js 客户端中. 每当你打电话给下游Amazon具有分析客户端的服务或资源时，开发工具包在子分段中记录有关调用的信息。Amazon您访问的 服务及其资源将在服务地图中显示为下游节点，帮助您标识单个连接上的错误和限制问题。

适用于 Node.js 的 X-Ray 开发工具包还为对 HTTP Web API 和 SQL 查询的下游调用提供分析。将 HTTP 客户端包含在开发工具包的捕获方法中以记录有关传出 HTTP 调用的信息。对于 SQL 客户端，将捕获方法用于数据库类型。

中间件将采用规则应用于传入请求以确定要跟踪的请求。您可以为 Node.js 配置 X-Ray 开发工具包调整采样行为或记录有关Amazon计算应用程序运行的资源。

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

注释和元数据

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

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

有关开发工具包的类和方法的参考文档，请参阅Amazon X-Ray适用于 Node.js 的开发工具包 API.

要求

适用于 Node.js 的 X-Ray 开发工具包需要 Node.js 和以下库：

  • atomic-batcher— 1.0.2

  • cls-hooked— 4.2.2

  • pkginfo— 0.4.0

  • semver— 5.3.0

当您将开发工具包与 NPM 一起安装时，开发工具包会拉入这些库。

要跟踪Amazon适用于 Node.js 的 X-Ray 开发工具包需要最低版本的Amazon适用于 JavaScript 在 Node.js 中。

  • aws-sdk— 2.7.15

依赖项管理

适用于 Node.js 的 X-Ray 开发工具包可从 NPM 获得。

对于本地开发，将开发工具包与 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 选项可将开发工具包作为应用程序的 package.json 中的依赖项保存。

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

如果您的应用程序有任何版本与 X-Ray SDK 的依赖关系冲突的依赖关系，则将安装这两个版本以确保兼容性。有关更多详细信息，请参阅用于依赖项解决的官方 NPM 文档.

Node.js 示例

使用Amazon X-Ray适用于 Node.js 的开发工具包以获取 end-to-end 查看在您的 Node.js 应用程序中传输请求时的请求。