本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# Amazon SQS 和 Amazon X-Ray
Amazon SQS

Amazon X-Ray 与 Amazon Simple Queue Service (Amazon SQS) 集成以跟踪通过 Amazon SQS 队列传递的消息。如果某项服务使用 X-Ray 开发工具包跟踪请求，则 Amazon SQS 可以发送跟踪标头并继续使用一致的跟踪 ID 将原始跟踪从发送者传播到使用者。跟踪连续性使用户能够跟踪、分析和调试整个下游服务。

Amazon X-Ray 支持跟踪使用 Amazon SQS 和 Amazon Lambda 的事件驱动型应用程序。使用 CloudWatch 控制台查看使用 Amazon SQS 排队并由下游 Lambda 函数处理的每个请求的互联视图。上游消息创建者的跟踪会自动链接到下游 Lambda 使用者节点的跟踪，从而创建应用程序的端到端视图。有关更多信息，请参阅[跟踪事件驱动型应用程序](xray-tracelinking.md)。

![\[通过 Amazon SQS 队列来自 Lambda 的跟踪地图。\]](http://docs.amazonaws.cn/xray/latest/devguide/images/console-batch-servicemap-linkededge.png)


Amazon SQS 支持以下跟踪标头检测：
+ **默认 HTTP 标头** – 当您通过 Amazon SDK 调用 Amazon SQS 时，X-Ray SDK 会自动将跟踪标头填充为 HTTP 标头。默认跟踪标头由 `X-Amzn-Trace-Id` 承载，对于包含在 [https://docs.amazonaws.cn/AWSSimpleQueueService/latest/APIReference/API_SendMessage.html](https://docs.amazonaws.cn/AWSSimpleQueueService/latest/APIReference/API_SendMessage.html) 或 [https://docs.amazonaws.cn/AWSSimpleQueueService/latest/APIReference/API_SendMessageBatch.html](https://docs.amazonaws.cn/AWSSimpleQueueService/latest/APIReference/API_SendMessageBatch.html) 请求中的所有消息。请参阅 [跟踪标头](xray-concepts.md#xray-concepts-tracingheader)，详细了解有关默认 HTTP 标头的信息。
+ **`AWSTraceHeader` 系统属性** - `AWSTraceHeader` 是 Amazon SQS 保留的[消息系统属性](https://docs.amazonaws.cn/AWSSimpleQueueService/latest/APIReference/API_MessageSystemAttributeValue.html)，用于承载队列中包含消息的 X-Ray 跟踪标头。即使无法通过 X-Ray SDK 进行自动检测时，也可以使用 `AWSTraceHeader`，例如在为新语言构建跟踪 SDK 时。如果同时设置了两个标头检测，则消息系统属性会覆盖 HTTP 跟踪标头。

在 Amazon EC2 上运行时，Amazon SQS 支持一次处理一条消息。这适用于在本地主机上运行时，以及当使用 Amazon Fargate、Amazon ECS 或 Amazon App Mesh 等容器服务时。

Amazon SQS 消息大小和消息属性配额中都排除了跟踪标头。启用 X-Ray 跟踪不会超过您的 Amazon SQS 配额。要了解有关 Amazon 配额的更多信息，请参阅 [Amazon SQS 配额](https://docs.amazonaws.cn/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-limits.html)。

## 发送 HTTP 跟踪标头


Amazon SQS 中的发送者组件可以通过 [https://docs.amazonaws.cn/AWSSimpleQueueService/latest/APIReference/API_SendMessageBatch.html](https://docs.amazonaws.cn/AWSSimpleQueueService/latest/APIReference/API_SendMessageBatch.html) 或 [https://docs.amazonaws.cn/AWSSimpleQueueService/latest/APIReference/API_SendMessage.html](https://docs.amazonaws.cn/AWSSimpleQueueService/latest/APIReference/API_SendMessage.html) 调用自动发送跟踪标头。检测到 Amazon SDK 客户端时，可自动通过 X-Ray SDK 支持的所有工具进行跟踪。所跟踪的 Amazon Web Services 服务以及您在这些服务中访问的资源（例如，Amazon S3 存储桶或 Amazon SQS 队列），在 X-Ray 控制台的跟踪地图上显示为下游节点。

如需了解如何使用首选语言跟踪 Amazon SDK 调用，请参阅支持的 SDK 中的以下主题：
+ Go – [使用 X-Ray Amazon SDK for Go 追踪 SDK 通话](xray-sdk-go-awssdkclients.md)
+ Java - [使用适用于 Java 的 X-Ray SD Amazon K 追踪 SDK 调用](xray-sdk-java-awssdkclients.md)
+ Node.js – [使用适用于 Node.js 的 X-Ray SD Amazon K 追踪 SDK 调用](xray-sdk-nodejs-awssdkclients.md)
+ Python – [使用 Amazon 适用于 Python 的 X-Ray 软件开发工具包追踪 SDK](xray-sdk-python-awssdkclients.md)
+ Ruby – [使用适用于 Ruby 的 X-Ray SD Amazon K 追踪 SDK 调用](xray-sdk-ruby-awssdkclients.md)
+ .NET – [使用适用于.NET 的 X-Ray SD Amazon K 追踪 SDK 调用](xray-sdk-dotnet-sdkclients.md)

## 检索跟踪标头和恢复跟踪上下文


如果您使用的是 Lambda 下游使用器，则会自动传播跟踪上下文 要继续使用其他 Amazon SQS 使用器进行上下文传播，必须手动检测向接收方组件的交接。

恢复跟踪上下文主要分为以下三个步骤：
+ 通过调用 [https://docs.amazonaws.cn/AWSSimpleQueueService/latest/APIReference/API_ReceiveMessage.html](https://docs.amazonaws.cn/AWSSimpleQueueService/latest/APIReference/API_ReceiveMessage.html) API 从 `AWSTraceHeader` 属性的队列中接收消息。
+ 从属性中检索跟踪标头。
+ 从标头中恢复跟踪 ID。（可选）向分段添加更多指标。

下面是使用 X-Ray SDK for Java 编写的示例实施。

**Example ：检索跟踪标头和恢复跟踪上下文**  

```
// Receive the message from the queue, specifying the "AWSTraceHeader"
ReceiveMessageRequest receiveMessageRequest = new ReceiveMessageRequest()
        .withQueueUrl(QUEUE_URL)
        .withAttributeNames("AWSTraceHeader");
List<Message> messages = sqs.receiveMessage(receiveMessageRequest).getMessages();

if (!messages.isEmpty()) {
    Message message = messages.get(0);
    
    // Retrieve the trace header from the AWSTraceHeader message system attribute
    String traceHeaderStr = message.getAttributes().get("AWSTraceHeader");
    if (traceHeaderStr != null) {
        TraceHeader traceHeader = TraceHeader.fromString(traceHeaderStr);

        // Recover the trace context from the trace header
        Segment segment = AWSXRay.getCurrentSegment();
        segment.setTraceId(traceHeader.getRootTraceId());
        segment.setParentId(traceHeader.getParentId());
        segment.setSampled(traceHeader.getSampled().equals(TraceHeader.SampleDecision.SAMPLED));
    }
}
```