本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# Amazon SNS 中的主動追蹤
使用 AWS X-Ray 追蹤和分析使用者透過 Amazon SNS 主題傳遞至 [Amazon Data Firehose](sns-firehose-as-subscriber.md)、、[Amazon SQS](https://docs.aws.amazon.com/xray/latest/devguide/xray-services-sqs.html) 和 HTTP/S [AWS Lambda](https://docs.aws.amazon.com/xray/latest/devguide/xray-services-lambda.html)端點訂閱的請求。
使用 X-Ray，您可以取得每個請求的end-to-end檢視，讓您：
+ 識別呼叫 Amazon SNS 主題的內容，以及訂閱下游的服務。
+ 分析延遲，例如：
+ 處理之前在 Amazon SNS 主題中花費的時間。
+ 每個訂閱端點的交付時間。
**重要**
具有眾多訂閱的 Amazon SNS 主題可能達到大小限制，而且無法完全追蹤。如需追蹤文件大小限制的資訊，請參閱《 AWS 一般參考》中的 [X-ray 服務配額](https://docs.aws.amazon.com/general/latest/gr/xray.html#limits_xray)。
如果您從已被追蹤的服務呼叫 Amazon SNS API，即使 API 上未啟用 X-Ray 追蹤，Amazon SNS 也會傳遞追蹤。
Amazon SNS 支援標準和 FIFO 主題的 X-Ray 追蹤。您可以使用 [Amazon SNS 主控台](https://console.aws.amazon.com/sns/v3/home)、[Amazon SNS `SetTopicAttributes` API](https://docs.aws.amazon.com/sns/latest/api/API_SetTopicAttributes.html)、[Amazon Simple Notification Service CLI 參考](https://docs.aws.amazon.com/cli/latest/reference/sns/)，或 [CloudFormation](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-sns-topic.html) 為 Amazon SNS 主題啟用 X-Ray。
要進一步了解將 Amazon SNS 與 X-Ray 搭配使用的更多資訊，請參閱《 AWS X-Ray 開發人員指南》中的 [Amazon SNS 和 AWS X-Ray](https://docs.aws.amazon.com/xray/latest/devguide/xray-services-sns.html)。
## 主動追蹤許可
使用 Amazon SNS 主控台時，Amazon SNS 會嘗試為 Amazon SNS 主題建立必要的許可以呼叫 X-Ray。如果您沒有足夠的許可以使用 Amazon SNS 主控台，則可以拒絕該嘗試。如需詳細資訊，請參閱[Amazon SNS 中的 Identity and Access Management](security-iam.md)及[Amazon SNS 存取控制的範例案例](sns-access-policy-use-cases.md)。
使用 CLI 時，您必須手動設定許可。這些許可是使用資源策略設定的。有關在 X-Ray 中使用所需許可的詳細資訊，請參閱 [Amazon SNS 和 AWS X-Ray](https://docs.aws.amazon.com/xray/latest/devguide/xray-services-sns.html)。
## 使用 AWS 主控台在 Amazon SNS 主題上啟用主動追蹤
在 Amazon SNS 主題上啟用主動追蹤時，它會讀取追蹤 ID、根據追蹤 ID 將資料傳送給客戶，然後將追蹤 ID 傳播至下游服務。
1. 登入 [Amazon SNS 主控台](https://console.aws.amazon.com/sns/home)。
1. 選擇主題或建立新主題。如需建立主題的詳細資訊，請參閱[建立 Amazon SNS 主題](sns-create-topic.md)。
1. 在**建立主題**頁面的**詳細資訊**區段中，選擇主題類型：**FIFO** 或**標準**。
1. 輸入新主題的 **名稱** (Name)。
1. (選用) 為主題輸入 **Display name** (顯示名稱)。
1. 展開 **Active tracing** (主動追蹤)，然後選擇 **Use active tracing** (使用主動追蹤)。
在為您的 Amazon SNS 主題啟用 X-Ray 後，您可以使用 [X-Ray 服務映射](https://docs.aws.amazon.com/xray/latest/devguide/xray-services-sns.html)檢視該主題的端到端追蹤和服務映射。
## 使用 AWS SDK 在 Amazon SNS 主題上啟用主動追蹤
下列程式碼範例示範如何使用適用於 Java 的 AWS 開發套件，在 Amazon SNS 主題上啟用主動追蹤。
```
public static void enableActiveTracing(SnsClient snsClient, String topicArn) {
try {
SetTopicAttributesRequest request = SetTopicAttributesRequest.builder()
.attributeName("TracingConfig")
.attributeValue("Active")
.topicArn(topicArn)
.build();
SetTopicAttributesResponse result = snsClient.setTopicAttributes(request);
System.out.println("\n\nStatus was " + result.sdkHttpResponse().statusCode() + "\n\nTopic " + request.topicArn()
+ " updated " + request.attributeName() + " to " + request.attributeValue());
} catch (SnsException e) {
System.err.println(e.awsErrorDetails().errorMessage());
}
}
```
## 使用 CLI 在 Amazon SNS AWS 主題上啟用主動追蹤
下列程式碼範例示範如何使用 CLI 在 Amazon SNS AWS 主題上啟用主動追蹤。
```
aws sns set-topic-attributes \
--topic-arn arn:aws:sns:us-west-2:123456789012:MyTopic \
--attribute-name TracingConfig \
--attribute-value Active
```
## 使用 在 Amazon SNS 主題上啟用主動追蹤 CloudFormation
下列 CloudFormation 堆疊顯示如何在 Amazon SNS 主題上啟用主動追蹤。
```
AWSTemplateFormatVersion: 2010-09-09
Resources:
MyTopicResource:
Type: 'AWS::SNS::Topic'
Properties:
TopicName: 'MyTopic'
TracingConfig: 'Active'
```
## 確認您的主題已啟用主動追蹤
您可以使用 Amazon SNS 主控台來驗證是否為您的主題啟用主動跟蹤，或者何時無法新增資源政策。
1. 登入 [Amazon SNS 主控台](https://console.aws.amazon.com/sns/home)。
1. 在左側導覽窗格中，選擇 **Topics** (主題)。
1. 在 **Topics** (主題) 頁面上，選擇一個主題。
1. 選擇 **Integrations** (整合) 索引標籤。
啟用主動追蹤後，會顯示綠色的 **Active** (作用中) 圖示。
1. 如果您已啟用主動追蹤，但沒有看到資源策略已新增，請選擇 **Create policy** (建立原則) 以新增其他必要許可。
![\[螢幕擷取畫面顯示 中名為「SampleTopic」之 Amazon SNS 主題的詳細資訊 AWS 管理主控台。它表示已啟用此主題的 AWS X-Ray 主動追蹤，但缺少允許 Amazon SNS 傳送追蹤資料的資源政策。提供「建立政策」按鈕來解決此問題。\]](http://docs.aws.amazon.com/zh_tw/sns/latest/dg/images/xray.png)
## 測試主動追蹤
1. 登入 [Amazon SNS 主控台](https://console.aws.amazon.com/sns/home)。
1. 建立 Amazon SNS 主題。如需詳細作法，請參閱[使用 建立主題 AWS 管理主控台](sns-create-topic.md#create-topic-aws-console)。
1. 展開 **Active tracing** (主動追蹤)，然後選擇 **Use active tracing** (使用主動追蹤)。
1. 發佈訊息至 Amazon SNS 主題。如需詳細作法，請參閱[使用 將訊息發佈至 Amazon SNS 主題 AWS 管理主控台](sns-publishing.md#sns-publishing-messages)。
1. 使用 [X-Ray 服務映射](https://docs.aws.amazon.com/xray/latest/devguide/xray-services-sns.html) 來檢視主題的端對端追蹤和服務映射。
![\[顯示 AWS X-Ray 服務映射，顯示從用戶端流向名為「」之 Amazon SNS 主題的請求追蹤xray-topic。 從那裡，訊息會分發到各種下游服務，包括 Amazon SQS 佇列、Lambda 函數、Kinesis Firehose 和遠端服務。每個連線都會顯示延遲 （毫秒） 和每分鐘交易速率 (t/min) 等指標，協助分析效能並識別訊息傳遞過程中的任何延遲問題。\]](http://docs.aws.amazon.com/zh_tw/sns/latest/dg/images/xray-troubleshooting.png)