Node.js版AWS SDK v3如何正确使用AWS X-Ray instrumentation

service.customizeRequests is not a function报错的核心原因是：旧版X-Ray SDK的captureAWSClient方法是针对AWS SDK v2的客户端架构设计的，SDK v3重构为中间件栈架构后不存在customizeRequests接口，因此完全不兼容。SDK v3内置的X-Ray客户端仅提供主动上报追踪数据的能力，不包含自动埋点逻辑，官方推荐实践如下：

原生X-Ray SDK 适配方案 #

官方aws-xray-sdk从2.3.0版本开始已经原生支持AWS SDK v3，无需引入额外依赖，仅需替换捕获方法即可：

• 禁止使用v2时代的captureAWSClient方法处理v3客户端
• 使用v3专用的captureAWSv3Client方法完成埋点，注意该方法仅接收实例化后的客户端对象，不支持传入客户端类本身

修正后的代码示例：

const { DynamoDBClient, ScanCommand } = require("@aws-sdk/client-dynamodb");
const AWSXRay = require("aws-xray-sdk");

// 实例化客户端后直接传入捕获方法，不要传入DynamoDBClient类
const client = AWSXRay.captureAWSv3Client(new DynamoDBClient({region: process.env.AWS_REGION}));

const scan = new ScanCommand({
    TableName: 'xxx',
});
await client.send(scan)

该方法会自动向v3客户端的中间件栈注入X-Ray追踪逻辑，自动采集调用时延、错误状态、请求属性等元数据，上报格式与SDK v2版本的埋点效果完全一致。

全链路追踪场景方案 #

如果服务使用OpenTelemetry做统一全链路追踪，可直接使用AWS官方提供的OpenTelemetry AWS SDK instrumentation包，初始化后会自动拦截所有AWS SDK v3的客户端调用，自动生成符合X-Ray规范的追踪Span，无需逐个客户端手动调用捕获方法。

注意事项 #

• 若运行环境为AWS Lambda，需确认部署包中携带的aws-xray-sdk版本不低于2.3.0，Lambda默认内置的低版本X-Ray SDK不支持v3适配，需要自行打包新版SDK到部署产物中
• 禁止同时混用captureAWSClient（v2专用）和captureAWSv3Client（v3专用）方法，避免出现重复埋点或不可预期的报错

内容的提问来源于stack exchange，提问作者Martin Macak