AWS X-Ray不展示错误排查：Node.js Lambda代理集成场景

问题1：让X-Ray展示new Error()引发的4xx客户端错误到异常板块 #

默认情况下，X-Ray主要自动捕获未处理的异常和5xx级别的服务端错误，4xx客户端错误因为通常是业务逻辑主动返回的，不会触发未捕获异常，所以不会自动出现在X-Ray的异常列表里。你可以通过手动记录错误到X-Ray追踪的方式来解决：

1. 确保X-Ray SDK正确初始化
   首先在你的Lambda项目中安装依赖：

   npm install aws-xray-sdk
   

   然后在Lambda代码开头初始化SDK：

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

2. 手动将4xx错误记录到X-Ray Segment
   当你在业务逻辑中生成4xx错误（比如参数错误、权限不足），不要只返回API响应，还要把错误对象添加到当前的X-Ray Segment中：

   exports.handler = async (event) => {
     try {
       // 业务逻辑：比如验证请求参数
       if (!event.body) {
         const err = new Error('请求体不能为空');
         err.statusCode = 400;
         // 获取当前X-Ray Segment并添加错误
         const segment = AWSXRay.getSegment();
         if (segment) {
           segment.addError(err);
         }
         return {
           statusCode: 400,
           body: JSON.stringify({ message: err.message })
         };
       }
       // 正常业务流程...
       return { statusCode: 200, body: JSON.stringify({ success: true }) };
     } catch (err) {
       // 捕获其他异常，同样记录到X-Ray
       const segment = AWSXRay.getSegment();
       if (segment) {
         segment.addError(err);
       }
       return {
         statusCode: err.statusCode || 500,
         body: JSON.stringify({ message: err.message })
       };
     }
   };
   

   这样操作后，这些4xx错误就会出现在X-Ray追踪的「异常」板块里，方便你排查客户端侧的问题。

问题2：让X-Ray展示Lambda超时等精准错误信息 #

Lambda超时属于运行时的fault类型错误，X-Ray应该能捕获，但有时候因为配置或SDK的问题，详情没有显示出来，你可以按以下步骤排查和优化：

1. 检查Lambda角色权限
   确保你的Lambda执行角色已经附加了AWSXRayDaemonWriteAccess策略，这样Lambda才能将完整的追踪数据发送给X-Ray。如果权限不足，X-Ray可能只会收到部分错误标记，没有详细信息。

2. 配置X-Ray SDK捕获超时信号
   Lambda超时前会发送SIGTERM信号，你可以监听这个信号，手动记录超时错误到X-Ray：

   exports.handler = async (event) => {
     const segment = AWSXRay.getSegment();
     // 监听超时信号
     process.on('SIGTERM', () => {
       const timeoutErr = new Error('Lambda函数执行超时');
       timeoutErr.name = 'TimeoutError';
       if (segment) {
         segment.addError(timeoutErr);
         segment.close(); // 确保segment被正确关闭并发送到X-Ray
       }
     });
   
     try {
       // 你的业务逻辑：比如S3写入和DynamoDB操作
       await Promise.all([
         s3.putObject(...).promise(),
         dynamodb.putItem(...).promise()
       ]);
       return { statusCode: 200, body: JSON.stringify({ success: true }) };
     } catch (err) {
       if (segment) {
         segment.addError(err);
       }
       return { statusCode: 500, body: JSON.stringify({ message: err.message }) };
     }
   };
   

3. 查看X-Ray追踪的详情面板
   有时候超时错误不会直接出现在「异常列表」，但会在追踪的Segment详情里标记为fault（红色感叹号），点击对应的Lambda Segment，查看「Errors」标签页，里面会有超时的详细信息，比如执行时长超过了配置的超时时间。

4. 调整Lambda超时配置
   同时，建议你根据业务逻辑的实际耗时，合理设置Lambda的超时时间（比如如果S3和DynamoDB操作需要3秒，就把超时设为5秒），避免频繁触发超时，也方便X-Ray更清晰地记录错误场景。

内容的提问来源于stack exchange，提问作者Mahdi Azarboon