如何配置AWS X-Ray跳过ECS Docker容器Node API的特定端点追踪

AI 小北

2026-8-29

结论

该需求可实现。X-Ray控制台自定义采样规则不支持将每秒采样数设为0是平台侧的参数限制，无需依赖控制台配置，通过SDK侧配置即可完成指定端点的追踪排除。

可行实现方案

方案1：SDK中间件直接配置忽略路径（推荐，实现成本最低）

如果你的Node API服务基于Express框架开发，在注册X-Ray中间件时直接传入ignorePaths参数，指定需要排除追踪的路径即可。该配置会在SDK层直接拦截匹配的请求，不生成任何追踪段、不向X-Ray守护进程发送对应请求的追踪数据，完全跳过追踪流程。
示例配置代码：

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

// 注册X-Ray中间件时配置忽略路径
app.use(AWSXRay.express.openSegment('your-node-api-service', {
  ignorePaths: ['/api/upload/directUploadConfirmation']
}));

// 其余业务路由配置

如果使用Koa、Fastify等其他Node框架，也可以在X-Ray SDK初始化时传入自定义采样判断逻辑，匹配到目标路径时直接返回不采样的结果即可。

方案2：本地采样规则文件配置

如果不想修改业务代码，可以在Docker镜像构建时将自定义采样规则文件打入容器，通过本地规则配置目标路径的采样率为0。本地采样规则优先级高于X-Ray控制台的托管规则，不受控制台参数最小值为1的限制。

新建采样规则文件xray-sampling-rules.json，内容如下：

{
  "version": 2,
  "rules": [
    {
      "description": "Skip tracing for direct upload confirmation endpoint",
      "host": "*",
      "http_method": "*",
      "url_path": "/api/upload/directUploadConfirmation",
      "fixed_target": 0,
      "rate": 0.0
    }
  ],
  "default": {
    "fixed_target": 1,
    "rate": 0.05
  }
}