亚马逊 SQS 和 Amazon X-Ray - Amazon X-Ray
发送 HTTP 跟踪标头检索跟踪标头和恢复跟踪上下文
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

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

亚马逊 SQS 和 Amazon X-Ray

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

Amazon X-Ray 支持使用 Amazon SQS 和跟踪事件驱动的应用程序。 Amazon Lambda使用 CloudWatch 控制台查看每个请求在 Amazon SQS 中排队并由下游 Lambda 函数处理的连接视图。来自上游消息生成者的跟踪会自动链接到来自下游 Lambda 使用者节点的跟踪，从而创建 end-to-end应用程序视图。有关更多信息，请参阅跟踪事件驱动型应用程序。

通过 Amazon SQS 队列来自 Lambda 的跟踪地图。

Amazon SQS 支持以下跟踪标头检测：

  • 默认 HTTP 标头 — 当您通过 Amazon 软件开发工具包调用亚马逊 SQS 时，X-Ray SDK 会自动将跟踪标头填充为 HTTP 标头。默认跟踪标头由 X-Amzn-Trace-Id 承载，对于包含在 SendMessage 或 SendMessageBatch 请求中的所有消息。请参阅 跟踪标头，详细了解有关默认 HTTP 标头的信息。

  • AWSTraceHeader 系统属性 - AWSTraceHeader 是 Amazon SQS 保留的消息系统属性，用于承载队列中包含消息的 X-Ray 跟踪标头。即使无法通过 X-Ray SDK 进行自动检测时，也可以使用 AWSTraceHeader，例如在为新语言构建跟踪 SDK 时。如果同时设置了两个标头检测，则消息系统属性会覆盖 HTTP 跟踪标头。

在亚马逊上运行时 EC2，Amazon SQS 支持一次处理一条消息。这适用于在本地主机上运行以及使用容器服务（例如 Amazon ECS 或） Amazon App Mesh。 Amazon Fargate

Amazon SQS 消息大小和消息属性配额中都排除了跟踪标头。启用 X-Ray 跟踪不会超过您的 Amazon SQS 配额。要了解有关 Amazon 配额的更多信息，请参阅 Amazon SQS 配额。

发送 HTTP 跟踪标头

Amazon SQS 中的发送者组件可以通过 SendMessageBatch 或 SendMessage 调用自动发送跟踪标头。在对 Amazon SDK 客户端进行检测时，可以通过 X-Ray SDK 支持的所有语言自动跟踪这些客户端。在这些服务（例如，Amazon S3 存储桶或 Amazon SQS 队列）中追踪的资源 Amazon Web Services 服务 和访问的资源在 X-Ray 控制台的跟踪地图上显示为下游节点。

要了解如何使用您的首选语言跟踪 Amazon SDK 调用，请参阅支持的以下主题 SDKs：

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

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

恢复跟踪上下文主要分为以下三个步骤：

  • 通过调用 ReceiveMessage API 从 AWSTraceHeader 属性的队列中接收消息。

  • 从属性中检索跟踪标头。

  • 从标头中恢复跟踪 ID。（可选）向分段添加更多指标。

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

例 ：检索跟踪标头和恢复跟踪上下文
// 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));
    }
}