配置适用于 Node.js 的 X-Ray 开发工具包 - Amazon X-Ray
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅 中国的 Amazon Web Services 服务入门 (PDF)

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

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

您可以使用插件配置 Node.js 的 X-Ray SDK,以包含有关应用程序运行的服务的信息、修改默认采样行为或添加适用于特定路径请求的采样规则。

服务插件

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

插件
  • Amazon EC2 —EC2Plugin 添加实例 ID、可用区和 CloudWatch 日志组。

  • Elastic Beanstalk —ElasticBeanstalkPlugin 添加环境名称、版本标签和部署 ID。

  • 亚马逊 ECS —ECSPlugin 添加容器 ID。

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

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

SDK 还使用插件设置来设置区段上的origin字段。这表示运行您的应用程序的Amazon资源类型。当您使用多个插件时,SDK 使用以下解析顺序来确定来源: ElasticBeanstalk > EKS > ECS > EC2。

采样规则

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

开发工具包将按它们的定义顺序应用自定义规则。如果请求匹配多个自定义规则,则 SDK 仅应用第一条规则。

注意

如果 SDK 无法访问 X-Ray 获取采样规则,它将恢复为每秒第一个请求的默认本地规则,以及每台主机任何额外请求的百分之五。如果主机没有权限调用采样 API,或者无法连接到 X-Ray 守护程序,后者充当 SDK 发出的 API 调用的 TCP 代理,就会发生这种情况。

您也可以将 SDK 配置为从 JSON 文档加载采样规则。在无法使用 X-Ray 采样的情况下,SDK 可以使用本地规则作为备份,也可以仅使用本地规则。

例 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 } }

此示例定义了一个自定义规则和一个默认规则。自定义规则采用 5% 的采样率,没有最低追踪路径的请求数/api/move/。默认规则每秒跟踪第一个请求和 10% 的其他请求。

在本地定义规则的缺点是,固定目标由记录器的每个实例独立应用,而不是由 X-Ray 服务管理。随着部署更多主机,固定速率会成倍增加,这使得控制记录的数据量变得更加困难。

启Amazon Lambda用,您无法修改采样率。如果您的函数由仪器化服务调用,则生成由该服务采样的请求的调用将由 Lambda 记录。如果启用了主动跟踪且不存在跟踪标头,则 Lambda 会做出采样决定。

要配置备份规则,请告知适用于 Node.js 的 X-Ray 开发工具包从文件中加载采样规则setSamplingRules

例 app.js - 来自文件的采样规则
var AWSXRay = require('aws-xray-sdk'); AWSXRay.middleware.setSamplingRules('sampling-rules.json');

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

例 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()

日志记录

要从开发工具包中记录输出,请调用 AWSXRay.setLogger(logger),其中 logger 是提供标准日志记录方法 (warninfo 等) 的对象。

默认情况下,SDK 将使用控制台对象上的标准方法将错误消息记录到控制台。可以使用AWS_XRAY_DEBUG_MODEAWS_XRAY_LOG_LEVEL环境变量来设置内置记录器的日志级别。有关有效日志级别值的列表,请参阅环境变量

如果您希望为日志提供不同的格式或目的地,则可以为 SDK 提供您自己实现的记录器接口,如下所示。任何实现此接口的对象都可以使用。这意味着可以使用许多日志库,例如 Winston,并将其直接传递给 SDK。

例 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 守护程序地址

如果 X-Ray 守护程序监听其他端口或主机127.0.0.1:2000,则可以将 Node.js 的 X-Ray SDK 配置为将跟踪数据发送到其他地址。

AWSXRay.setDaemonAddress('host:port');

您可以通过名称或 IPv4 地址指定主机。

例 app.js - 守护程序地址
var AWSXRay = require('aws-xray-sdk'); AWSXRay.setDaemonAddress('daemonhost:8082');

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

例 app.js – 不同的端口上的守护程序地址
var AWSXRay = require('aws-xray-sdk'); AWSXRay.setDaemonAddress('tcp:daemonhost:8082 udp:daemonhost:8083');

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

环境变量

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

  • AWS_XRAY_CONTEXT_MISSING— 设置为RUNTIME_ERROR,当您的仪器化代码在未打开任何区段时尝试记录数据时抛出异常。

    有效值
    • RUNTIME_ERROR— 抛出运行时异常。

    • LOG_ERROR— 记录错误并继续(默认)。

    • IGNORE_ERROR— 忽略错误并继续。

    当您尝试在未打开请求时运行的启动代码中或在生成新线程的代码中使用仪器化客户端时,可能会发生与缺失分段或子分段相关的错误。

  • AWS_XRAY_DAEMON_ADDRESS— 设置 X-Ray 守护程序侦听器的主机和端口。默认情况下,SDK 同时使用127.0.0.1:2000跟踪数据 (UDP) 和采样 (TCP)。如果您已将守护程序配置为监听其他端口,或者它在其他主机上运行,请使用此变量。

    格式
    • 相同的端口address:port

    • 不同的端口tcp:address:port udp:address:port

  • AWS_XRAY_DEBUG_MODE— 设置为,TRUE将 SDK 配置为在debug级别上将日志输出到控制台。

  • AWS_XRAY_LOG_LEVEL — 为默认记录器设置日志级别。有效值为 debuginfowarnerrorsilent。将 AWS_XRAY_DEBUG_MODE 设置为 TRUE 时,将忽略此值。

  • AWS_XRAY_TRACING_NAME— 设置 SDK 用于分段的服务名称。覆盖您通过 Express 中间件设置的分段名称。