如何将AWS X-Ray集成到Express Gateway中间件中？

问题核心 #

• 无法正确将X-Ray中间件挂载到Express Gateway内部的Express实例
• 全局HTTP捕获配置后，追踪数据未出现在AWS X-Ray控制台

一、正确接入X-Ray中间件的可行方案 #

你当前的代码存在中间件顺序错误（关闭段中间件需放在所有路由之后），调整后的实现如下：

调整后的代码示例 #

const path = require("path");
const gateway = require("express-gateway");
const AWSXRay = require('aws-xray-sdk');
const nconf = require("nconf");
const { loadConfigurations } = require("./aws");

nconf.use('memory').env({ parseValues: true });

(async () => {
    await loadConfigurations();

    // 全局捕获必须在加载其他依赖http/https的模块前执行
    AWSXRay.captureHTTPsGlobal(require('http'));
    AWSXRay.captureHTTPsGlobal(require('https'));

    const gatewayInstance = gateway().load(path.join(__dirname, "config"));

    gatewayInstance.on('loaded', () => {
        const expressApp = gatewayInstance.app;
        // 开段中间件必须在所有路由、插件之前挂载
        expressApp.use(AWSXRay.express.openSegment('appstore-gateway'));

        // 服务器启动后挂载关闭段中间件（确保所有路由已加载）
        gatewayInstance.server.on('listening', () => {
            expressApp.use(AWSXRay.express.closeSegment());
            console.log('AWS X-Ray middleware applied correctly.');
        });
    });

    gatewayInstance.run();
})();

关键注意事项 #

• 中间件顺序：openSegment需前置，closeSegment必须放在所有路由之后，否则会导致追踪段无法正确闭合
• 全局捕获时机：captureHTTPsGlobal要在Express Gateway本身加载前执行，否则无法捕获内部HTTP调用
• IAM权限：确保运行网关的IAM角色拥有xray:PutTraceSegments和xray:PutTelemetryRecords权限

二、Express Gateway 添加自定义追踪中间件的官方方法/最佳实践 #

1. 使用官方插件系统（推荐） #

Express Gateway推荐通过自定义插件扩展功能，能更好地适配网关生命周期：

步骤1：创建自定义插件

在项目中创建plugins/xray-tracking目录，添加两个文件：

manifest.js

module.exports = {
  version: '1.0.0',
  policies: ['xray-tracking'],
  init: function (pluginContext) {
    pluginContext.registerPolicy({
      name: 'xray-tracking',
      schema: {
        $id: 'http://express-gateway.io/schemas/policies/xray-tracking.json',
        type: 'object',
        properties: {
          segmentName: { type: 'string' }
        },
        required: ['segmentName']
      },
      policy: (actionParams) => {
        return (req, res, next) => {
          let segment = AWSXRay.getSegment();
          if (!segment) {
            segment = new AWSXRay.Segment(actionParams.segmentName);
            AWSXRay.setSegment(segment);
            req.xraySegment = segment;

            // 响应结束时关闭追踪段
            res.on('finish', () => segment.close());
            res.on('error', () => segment.close());
          }
          next();
        };
      }
    });
  }
};

index.js

const AWSXRay = require('aws-xray-sdk');

// 全局捕获HTTP请求
AWSXRay.captureHTTPsGlobal(require('http'));
AWSXRay.captureHTTPsGlobal(require('https'));

module.exports = require('./manifest');

步骤2：启用插件

在config/system.config.yml中添加插件配置：

plugins:
  xray-tracking:
    package: './plugins/xray-tracking'

步骤3：在API策略中应用

在config/gateway.config.yml的API规则里添加该策略：

apis:
  - name: my-api
    policies:
      - xray-tracking:
          - action:
              segmentName: 'appstore-gateway'
      - proxy:
          - action:
              serviceEndpoint: 'http://backend-service'

2. 最佳实践总结 #

• 优先用插件系统：符合Express Gateway扩展规范，便于管理和复用
• 生命周期对齐：在插件init阶段完成X-Ray初始化，确保全局捕获生效
• 段管理规范：请求开始创建段，响应结束/出错时关闭，避免内存泄漏
• 错误处理：添加异常捕获逻辑，确保错误场景下追踪段正常关闭

内容的提问来源于stack exchange，提问作者Jaffer Sathick