本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# Amazon SQS 和 AWS X-Ray
<a name="xray-services-sqs"></a>

AWS X-Ray 與 Amazon Simple Queue Service (Amazon SQS) 整合，以追蹤透過 Amazon SQS 佇列傳遞的訊息。如果服務使用 X-Ray SDK 追蹤請求，Amazon SQS 可以傳送追蹤標頭，並繼續使用一致的追蹤 ID 將原始追蹤從寄件者傳播給消費者。追蹤連續性可讓使用者追蹤、分析和偵錯整個下游服務。

AWS X-Ray 支援使用 Amazon SQS 和 追蹤事件驅動型應用程式 AWS Lambda。使用 CloudWatch 主控台查看與 Amazon SQS 佇列並由下游 Lambda 函數處理之每個請求的連線檢視。來自上游訊息生產者的追蹤會自動連結至來自下游 Lambda 消費者節點的追蹤，建立end-to-end檢視。如需詳細資訊，請參閱[追蹤事件驅動的應用程式](xray-tracelinking.md)。

![\[透過 Amazon SQS 佇列從 Lambda 追蹤映射。\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/console-batch-servicemap-linkededge.png)


Amazon SQS 支援下列追蹤標頭檢測：
+ **預設 HTTP 標頭** – 當您透過 SDK 呼叫 Amazon SQS 時，X-Ray AWS SDK 會自動將追蹤標頭填入為 HTTP 標頭。預設追蹤標頭由 `X-Amzn-Trace-Id` 攜帶，並對應至 [https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_SendMessage.html](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_SendMessage.html) 或 [https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_SendMessageBatch.html](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_SendMessageBatch.html) 請求中包含的所有訊息。若要進一步了解預設 HTTP 標頭 , 請參閱 [追蹤標頭](xray-concepts.md#xray-concepts-tracingheader)。
+ **`AWSTraceHeader` 系統屬性** – `AWSTraceHeader`是 Amazon SQS 預留[的訊息系統屬性](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_MessageSystemAttributeValue.html)，用於在佇列中攜帶 X-Ray 追蹤標頭與訊息。即使未透過 X-Ray SDK 自動檢測，`AWSTraceHeader`也可以使用，例如在為新語言建置追蹤 SDK 時。同時設定這兩個標頭檢測時，訊息系統屬性會覆寫 HTTP 追蹤標頭。

在 Amazon EC2 上執行時，Amazon SQS 支援一次處理一則訊息。這適用於在內部部署主機上執行，以及使用容器服務時 AWS Fargate，例如 Amazon ECS 或 AWS App Mesh。

追蹤標頭會從 Amazon SQS 訊息大小和訊息屬性配額中排除。啟用 X-Ray 追蹤不會超過您的 Amazon SQS 配額。若要進一步了解 AWS 配額，請參閱 [Amazon SQS Quotas](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-limits.html)。

## 傳送 HTTP 追蹤標頭
<a name="xray-services-sqs-sending"></a>

Amazon SQS 中的寄件者元件可以透過 [https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_SendMessageBatch.html](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_SendMessageBatch.html)或 [https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_SendMessage.html](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_SendMessage.html)呼叫自動傳送追蹤標頭。檢測 AWS SDK 用戶端時，可以透過 X-Ray SDK 支援的所有語言自動追蹤它們。您在這些服務中存取的追蹤 AWS 服務 和資源 （例如 Amazon S3 儲存貯體或 Amazon SQS 佇列），會在 X-Ray 主控台的追蹤地圖上顯示為下游節點。

若要了解如何使用您偏好的語言追蹤 AWS SDK 呼叫，請參閱支援的 SDKs 中的下列主題：
+ Go – [使用適用於 Go 的 X-Ray AWS 開發套件追蹤 SDK 呼叫](xray-sdk-go-awssdkclients.md)
+ Java – [使用適用於 Java 的 X-Ray AWS 開發套件追蹤 SDK 呼叫](xray-sdk-java-awssdkclients.md)
+ Node.js – [使用適用於 Node.js 的 X-Ray AWS 開發套件追蹤 SDK 呼叫](xray-sdk-nodejs-awssdkclients.md)
+ Python – [使用適用於 Python 的 X-Ray AWS 開發套件追蹤 SDK 呼叫](xray-sdk-python-awssdkclients.md)
+ Ruby – [使用適用於 Ruby 的 X-Ray AWS 開發套件追蹤 SDK 呼叫](xray-sdk-ruby-awssdkclients.md)
+ .NET – [使用適用於 .NET 的 X-Ray AWS 開發套件追蹤 SDK 呼叫](xray-sdk-dotnet-sdkclients.md)

## 擷取追蹤標頭和復原追蹤內容
<a name="xray-services-sqs-retrieving"></a>

如果您使用的是 Lambda 下游消費者，則會自動進行追蹤內容傳播。若要繼續與其他 Amazon SQS 取用者進行內容傳播，您必須手動檢測接收器元件的交接。

復原追蹤內容有三個主要步驟：
+ 呼叫 [https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_ReceiveMessage.html](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_ReceiveMessage.html) API，從 `AWSTraceHeader` 屬性的佇列接收訊息。
+ 從屬性擷取追蹤標頭。
+ 從標頭復原追蹤 ID。選擇性地將更多指標新增至區段。

以下是使用適用於 Java 的 X-Ray 開發套件撰寫的範例實作。

**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));
    }
}
```