AWS X-Ray SDK for Node.js - AWS X-Ray
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 AWS 服务入门

AWS X-Ray SDK for Node.js

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

注意

X-Ray SDK for Node.js 是一个开源项目。您可以跟踪该项目并在 GitHub 上提交问题和拉取请求:github.com/aws/aws-xray-sdk-node

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

对于由已分析应用程序或服务调用的 Lambda 函数,Lambda 自动读取跟踪标头并跟踪采样的请求。对于其他函数,您可以配置 Lambda 以采样和跟踪传入请求。无论哪种情况,Lambda 都会创建分段并将其提供给 X-Ray 开发工具包。

注意

在 Lambda 上,X-Ray 开发工具包是可选的。如果您不将它用于您的函数,则您的服务地图仍将为 Lambda 服务包含节点,每个 Lambda 函数各一个。通过添加开发工具包,您可以分析您的函数代码,以将子分段添加到 Lambda 所记录的函数分段。请参阅 AWS Lambda 和 AWS X-Ray 以了解更多信息。

接下来,使用X-Ray SDK for Node.js分析您的 AWS SDK for JavaScript in Node.js 客户端。当您使用分析过的客户端调用下游 AWS 服务或资源时,开发工具包会在子分段中记录有关调用的信息。您访问的 AWS 服务及其资源将在服务地图中显示为下游节点,帮助您标识单个连接上的错误和限制问题。

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

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

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

注释和元数据

注释和元数据是您用 X-Ray 开发工具包添加到分段中的任意文本。会对注释编制索引,用于与筛选表达式一同使用。不会对元数据编制索引,但是可以在原始分段中通过 X-Ray 控制台或 API 查看。您授予对 X-Ray 读取权限的人都可以查看此数据。

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

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

要求

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

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

要跟踪 AWS 开发工具包客户端,X-Ray SDK for Node.js需要最低版本的 AWS SDK for JavaScript in Node.js。

  • aws-sdk – 2.7.15

依赖项管理

X-Ray SDK for Node.js 可从 NPM 使用。

对于本地开发,将开发工具包与 NPM 一起安装在项目目录中。

~/nodejs-xray$ npm install aws-xray-sdk aws-xray-sdk@3.0.0 ├─┬ aws-xray-sdk-core@3.0.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 │ ├── pkginfo@0.4.1 │ └── semver@5.7.1 ├── aws-xray-sdk-express@3.0.0 ├── aws-xray-sdk-mysql@3.0.0 └── aws-xray-sdk-postgres@3.0.0

使用 --save 选项可将开发工具包作为应用程序的 package.json 中的依赖项保存。

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

Node.js 示例

使用适用于 Node.js 的 AWS X-Ray 开发工具包,获取在请求通过 Node.js 应用程序时的端到端视图。