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

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

Amazon SQS 和 Amazon X-Ray

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 使用者节点的跟踪，从而创建应用程序的端到端视图。有关更多信息，请参阅跟踪事件驱动型应用程序。

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

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

  • 默认 HTTP 标头 – 当您通过 Amazon SDK 调用 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 跟踪标头。

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

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

发送 HTTP 跟踪标头

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

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

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

如果您使用的是 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));
    }
}