CloudWatch RUM与API Gateway v2/Lambda X-Ray链路追踪问题咨询

一、开启API Gateway v2的X-Ray追踪 #

API Gateway v2（HTTP/WebSocket API）的X-Ray配置入口和v1不同，两种配置方式：

控制台操作 #

• 打开API Gateway控制台，选中你的目标API
• 左侧导航栏拉至底部，进入Settings页面
• 在X-Ray tracing区域开启开关，采样率可先设为100%方便调试

CLI命令配置 #

替换<你的API唯一ID>后执行：

aws apigatewayv2 update-api \
    --api-id <你的API唯一ID> \
    --tracing-enabled

如需设置采样率，追加参数：

aws apigatewayv2 update-api \
    --api-id <你的API唯一ID> \
    --tracing-enabled \
    --trace-sampling-rate 100

二、确保Lambda延续客户端Trace ID #

Lambda默认会读取请求头中的x-amzn-trace-id并延续追踪，需确认两点：

• Lambda执行角色附加AWSXRayDaemonWriteAccess托管策略，拥有X-Ray写入权限
• 若代码中手动处理请求头，不要丢弃x-amzn-trace-id，保证其正常传递

三、全链路关联逻辑 #

API Gateway v2开启X-Ray后，客户端RUM生成的x-amzn-trace-id会被接收并传递给Lambda：

• CloudWatch服务地图将自动拼接客户端→API Gateway→Lambda的完整链路
• Lambda不再生成独立Trace ID，而是沿用客户端的追踪上下文，形成完整调用链

四、验证配置生效 #

1. 触发Web应用的XHR请求
2. 进入CloudWatch X-Ray控制台查看Traces，应能看到包含RUM、API Gateway、Lambda的完整追踪条目
3. 查看CloudWatch服务地图，确认整条链路已连通

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