使用AWS X-Ray追踪SNS-SQS扇出模式请求时，追踪在SNS处中断

我之前也踩过这个坑！用API Gateway→Lambda→SNS→SQS→Lambda的扇出架构时，X-Ray追踪总是在SNS环节就断掉，折腾了好一阵才把整个链路打通。下面是亲测有效的排查和修复步骤：

1. 先确保SNS和SQS都开启了X-Ray追踪 #

这是最基础的一步，很多人容易忽略：

• SNS主题：进入SNS控制台找到你的主题，在「配置」→「追踪」里开启「启用X-Ray追踪」，同时给SNS的服务角色附加AWSXRayDaemonWriteAccess托管策略，允许它向X-Ray发送追踪数据。
• SQS队列：同理，在SQS控制台的队列「配置」→「追踪」中开启X-Ray，给SQS的服务角色也加上X-Ray写入权限。

2. 给Lambda→SNS的调用手动传递追踪上下文 #

Lambda调用SNS时，X-Ray不会自动把追踪头传递过去，必须手动在消息属性里带上X-Amzn-Trace-Id，否则SNS没法关联到上游的追踪链。

举个Node.js的示例代码：

const AWS = require('aws-sdk');
const AWSXRay = require('aws-xray-sdk');
const sns = AWSXRay.captureAWSClient(new AWS.SNS());

exports.handler = async (event) => {
  // 从API GW代理的事件中取出追踪头
  const traceHeader = event.headers['X-Amzn-Trace-Id'];
  
  await sns.publish({
    TopicArn: '你的SNS主题ARN',
    Message: JSON.stringify(event),
    MessageAttributes: {
      'X-Amzn-Trace-Id': {
        DataType: 'String',
        StringValue: traceHeader
      }
    }
  }).promise();
  
  return { statusCode: 200, body: 'Message published' };
};

Python版本的示例：

import boto3
from aws_xray_sdk.core import patch_all

# 自动修补所有AWS客户端以支持X-Ray
patch_all()
sns = boto3.client('sns')

def lambda_handler(event, context):
    trace_header = event['headers'].get('X-Amzn-Trace-Id')
    
    sns.publish(
        TopicArn='你的SNS主题ARN',
        Message=str(event),
        MessageAttributes={
            'X-Amzn-Trace-Id': {
                'DataType': 'String',
                'StringValue': trace_header
            }
        }
    )
    return {'statusCode': 200, 'body': 'Message published'}

3. 让SQS触发器把追踪头传递给下游Lambda #

SQS触发Lambda时，要确保消息属性（包括我们刚才加的追踪头）能被Lambda接收到，并且在Lambda里正确关联追踪上下文：

• 先在SQS控制台的触发器配置里，确认「包含消息属性」是开启的状态。
• 然后在处理SQS消息的Lambda代码中，从消息属性里取出追踪头，手动关联到X-Ray的追踪链：

Node.js示例：

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

exports.handler = async (event) => {
  for (const record of event.Records) {
    // 从SQS消息属性中提取追踪头
    const traceHeader = record.messageAttributes['X-Amzn-Trace-Id'].stringValue;
    // 基于追踪头创建关联的子段
    const segment = AWSXRay.getSegmentFromTraceHeader(traceHeader);
    AWSXRay.setSegment(segment);
    
    // 这里写你的业务处理逻辑
    console.log('Processing message:', record.body);
    
    // 记得结束子段
    AWSXRay.endSegment();
  }
  return { statusCode: 200 };
};

Python示例：

from aws_xray_sdk.core import xray_recorder
from aws_xray_sdk.core.models.trace_header import TraceHeader

def lambda_handler(event, context):
    for record in event['Records']:
        trace_header_str = record['messageAttributes']['X-Amzn-Trace-Id']['stringValue']
        trace_header = TraceHeader.from_header_str(trace_header_str)
        
        # 创建关联到父追踪的子段
        subsegment = xray_recorder.begin_subsegment('Process-SQS-Message')
        subsegment.trace_id = trace_header.root
        subsegment.parent_id = trace_header.parent
        
        # 业务逻辑处理
        print(f'Processing message content: {record["body"]}')
        
        # 结束子段
        xray_recorder.end_subsegment()
    return {'statusCode': 200}

4. 验证所有角色的X-Ray权限 #

整个流程涉及的所有IAM角色（API GW执行角色、发布SNS的Lambda角色、SNS服务角色、SQS服务角色、处理SQS消息的Lambda角色）都需要有xray:PutTraceSegments和xray:PutTelemetryRecords权限。最省心的方式是直接给这些角色附加AWSXRayDaemonWriteAccess托管策略。

5. 检查X-Ray采样规则 #

有时候追踪中断是因为采样率不够，导致部分请求没被追踪到。你可以在X-Ray控制台的「采样规则」里，创建一个覆盖API GW、Lambda、SNS、SQS的规则，测试阶段可以把采样率设为100%，确保所有请求都能被追踪。

按照上面的步骤一步步排查，应该就能把整个链路的追踪打通了。我当时就是漏了手动传递SNS的消息属性，导致追踪在SNS那里断掉，加上之后整个流程的追踪就完整显示出来了。

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