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

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

配置 X-Ray SDK for Node.js

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

服务插件

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

插件

  • Amazon EC2 – EC2Plugin 会添加实例 ID、可用区和 CloudWatch Logs 组。

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

  • Amazon ECS – ECSPlugin 添加容器 ID。

要使用插件,请使用 config 方法配置X-Ray SDK for Node.js客户端。

例 app.js - 插件

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

开发工具包还使用插件设置来设置分段上的 origin 字段。这指示运行您的应用程序的 AWS 资源的类型。资源类型显示在运行应用程序中您应用程序名称的下方。例如:AWS::ElasticBeanstalk::Environment

具有资源类型的服务节点。

在使用多个插件时,开发工具包将使用以下解析顺序确定来源:ElasticBeanstalk > EKS > ECS > EC2。

采样规则

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

SDK 将按定义自定义规则的顺序应用它们。如果一个请求与多个自定义规则匹配,SDK 将只应用第一个规则。

注意

如果开发工具包无法访问 X-Ray 来获取示例规则,则它将恢复为使用每台主机的默认本地规则每秒的第一个请求,以及任何额外请求中的 5%。如果主机无权调用采样 API,或者无法连接到 X-Ray 守护程序(充当开发工具包所发出 API 调用的 TCP 代理),则可能出现此情况。

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

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

本示例定义了一个自定义规则和一个默认规则。自定义规则应用了百分之五的取样率,并且对 /api/move/ 下的路径的请求未设置最低追踪请求数量。默认规则将跟踪每秒的第一个请求,以及任何额外请求中的 10%。

在本地定义规则的缺点是,每个记录器实例将独立应用固定目标,而不是由 X-Ray 服务进行管理。当您部署多台主机时,固定率将倍增,这使得记录的数据量更难控制。

在 AWS Lambda 上,您无法修改采样率。如果您的函数由已分析服务调用,则由该服务采样的调用生成请求将由 Lambda 记录。如果启用了活动跟踪,并且没有跟踪标头,则 Lambda 进行采样决策。

要配置备份规则,请指示X-Ray SDK for Node.js从具有 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 等) 的对象。

例 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,确保捕获这些操作的输出。

有关有效日志级别值的列表,请查看环境变量部分中的详细信息。

要配置开发工具包,无需使用日志记录库即可将日志输出到控制台,请使用 AWS_XRAY_DEBUG_MODE 环境变量。

X-Ray 守护程序地址

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

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 环境变量来设置守护程序地址。

环境变量

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

  • AWS_XRAY_CONTEXT_MISSING – 设置为 LOG_ERROR 可避免在您的已检测代码尝试在分段未打开的情况下记录数据时引发异常。

    有效值

    • RUNTIME_ERROR – 引发运行时异常(默认)。

    • LOG_ERROR – 记录错误并继续。

    对于在未打开任何请求时运行的启动代码或生成新线程的代码,如果您尝试在其中使用分析的客户端,则可能发生与缺失分段或子分段相关的错误。

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

    格式

    • 相同端口address:port

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

  • AWS_XRAY_DEBUG_MODE – 设置为 TRUE 可配置开发工具包以将日志输出到控制台,而不是配置记录器

  • AWS_XRAY_LOG_LEVEL – 设置日志记录程序的日志级别。有效值为 debuginfowarnerrorsilent。将 AWS_XRAY_DEBUG_MODE 设置为 TRUE 时,将忽略此值。

  • AWS_XRAY_TRACING_NAME – 设置开发工具包用于进行分段的服务名称。覆盖您通过 Express 中间件设置的分段名称。