Amazon 适用于 Node.js 的 X-ray SDK

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

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

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

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

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

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

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

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

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

要求

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

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

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

依赖项管理

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

对于本地开发，将开发工具包与 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 开发工具包的依赖项冲突的依赖项，则将会同时安装两个版本以确保兼容性。有关详细信息，请参阅依赖项解析的官方 NPM 文档。

Node.js 示例

使用 Amazon X-Ray 适用于 Node.js 的 SDK，在请求通过你的 Node.js 应用程序时 end-to-end 查看这些请求。

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

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

服务插件

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

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

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

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

采样规则

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

开发工具包按照定义的顺序应用自定义规则。如果请求与多个自定义规则匹配，则开发工具包仅应用第一条规则。

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

{
  "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 的文件加载采样规则。

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

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

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 环境变量设置内置记录器的日志级别。有关有效日志级别值的列表，请参阅环境变量。

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

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 地址指定主机。

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

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

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

此外，您还可以通过使用 AWS_XRAY_DAEMON_ADDRESS 环境变量来设置守护程序地址。

环境变量

您可以使用环境变量来配置适用于 Node.js 的 X-Ray 开发工具包。开发工具包支持以下变量。

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

你可以使用适用于 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 请求的计时、方法和处置。其他检测会在此分段上创建子分段。

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

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

信息处理程序使用包含以下信息的 http 数据块为每个传入请求创建一个分段：

通过 Express 跟踪传入请求

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

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 服务器和分段名传递给它。

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 使用服务名称来标识您的应用程序，并将其与您的应用程序使用的其他应用程序、数据库、外部 API 和 Amazon 资源区分开来。当 X-Ray 开发工具包为传入请求生成分段时，会将应用程序的服务名称记录在分段的名称字段中。

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

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

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

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

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

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 开发工具包跟踪对下游 HTTP Web 服务的调用

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

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

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

要在所有 HTTP 客户端上启用跟踪，请先调用 captureHTTPsGlobal，然后加载 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 生成推断分段。

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

{
  "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 客户端包含在相应的适用于 Node.js 的 X-Ray 开发工具包客户端方法中来检测 SQL 数据库查询。

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

在 SQL 子段中包括其他数据

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

有关列入许可名单的 SQL 字段的完整列表，请参阅中的 “SQL 查询” 部分。X-Ray 片段文档

使用适用于 Node.js 的 X-Ray 开发工具包生成自定义子分段

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

自定义 Express 子分段

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

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 函数，这会在函数块完成执行时立即自动结束子分段。

当您在分段或者其他子分段中创建子分段时，适用于 Node.js 的 X-Ray 开发工具包将为其生成 ID 并记录开始时间和结束时间。

"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 子分段

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

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

使用适用于 Node.js 的 X-Ray 开发工具包，将注释和元数据添加到分段

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

注释是带字符串、数字或布尔值的键值对。系统会对注释编制索引，以便与筛选表达式一起使用。使用注释记录要用于对控制台中的跟踪进行分组的数据或在调用 GetTraceSummaries API 时使用的数据。

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

除了注释和元数据之外，您还可以在分段上记录用户 ID 字符串。用户 ID 记录在分段的单独字段中，并且不会为其编制索引以用于搜索。

使用适用于 Node.js 的 X-Ray 开发工具包记录注释

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

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

要查找具有带特定值的注释的跟踪，请在annotations.key筛选表达式中使用 关键字。

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) {
...

使用适用于 Node.js 的 X-Ray 开发工具包记录元数据

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

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

使用适用于 Node.js 的 X-Ray 开发工具包记录用户 ID

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

您可以调用 setUser 以便在快速应用程序开始处理请求后立即记录用户 ID。如果您只打算使用分段来设置用户 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筛选表达式中使用 关键字。