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

您可以使用适用于 Node.js 的 X-Ray 开发工具包，跟踪 Amazon EC2、AWS Elastic Beanstalk 或 Amazon ECS 中在 EC2 实例上 Express 和 Restify 应用程序提供服务的传入 HTTP 请求。

适用于 Node.js 的 X-Ray 开发工具包为使用 Express 和 Restify 框架的应用程序提供中间件。在您将 X-Ray 中间件添加到应用程序时，适用于 Node.js 的 X-Ray 开发工具包会为每个采样请求创建一个分段。此分段包括 HTTP 请求的计时、方法和处置。其他检测会在此分段上创建子分段。

注意

如果使用的是 AWS Lambda 函数，Lambda 会为每个采样的请求创建一个分段。参阅 AWS Lambda 和 AWS X-Ray 了解更多信息。

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

转发的请求

如果负载均衡器或其他中间将请求转发到您的应用程序，X-Ray 会提取请求 X-Forwarded-For 标头中的客户端 IP 而非 IP 数据包中的源 IP。由于转发的请求记录的客户端 IP 可以伪造，因此不应信任。

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

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

• HTTP 方法 - GET、POST、PUT、DELETE 等。

• 客户端地址 - 发送请求的客户端的 IP 地址。

• 响应代码 - 已完成请求的 HTTP 响应代码。

• 时间 - 开始时间（收到请求时）和结束时间（发送响应时）。

• 用户代理 - 请求中的 user-agent。

• 内容长度 - 响应中的 content-length。

通过 Express 跟踪传入请求

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

例 app.js - Express

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

例 app.js - 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');
});

配置分段命名策略

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

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

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

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

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

注意

您可以使用 AWS_XRAY_TRACING_NAME 环境变量覆盖您在代码中定义的默认服务名称。

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

例 app.js - 动态分段名称

如果请求中的主机名与模式 *.example.com 匹配，请使用主机名。否则，请使用 MyApp。

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