# 從與 Amazon SNS 直接整合的 APM 擷取警示
<a name="idr-gs-ingest-apm-sns"></a>

如果您的 APM 支援將警示傳送至 Amazon SNS 主題，您可以依照本指南將 APM 警示擷取至 AWS 事件偵測與回應。

您可以部署提供的 [CloudFormation 範本](https://dcl74d3hc5lj1.cloudfront.net/apms/ThirdPartyApmSnsIntegration.json)，或手動設定此整合。設定整合之前，請確認您的帳戶中[已建立](https://docs.aws.amazon.com/IDR/latest/userguide/idr-gs-access-prov.html) AWS 服務連結角色 (SLR) `AWSServiceRoleForHealth_EventProcessor`。

## 選項 1：使用 CloudFormation
<a name="idr-gs-apm-sns-cfn"></a>

CloudFormation 範本可用來簡化建立整合基礎結構的程序，須有此基礎結構才能從與 Amazon SNS 整合的 APM 將警示擷取至 AWS 事件偵測與回應。

**注意**  
透過此 CloudFormation 範本部署的資源會產生其他成本 (例如 Lambda 和 EventBridge)。如需這些服務定價的詳細資訊，請參閱 [AWS 定價](https://aws.amazon.com/pricing/)。
您必須在 AWS 事件偵測與回應需要從中擷取警示的每個 AWS 帳戶和區域中部署此 CloudFormation 範本。
本文件中提供的範例適用於 Grafana，但此範本可用於與 Amazon Simple Notification Service 直接整合的任何 APM。
基於安全考量，AWS 建議您從 `TransformLambdaFunction` 移除 `logger.info()` 陳述式，以防止承載記錄於 Amazon CloudWatch Logs 中。

**部署此 CloudFormation 範本的先決條件：**
+ 您必須建立 Amazon Simple Notification Service 主題，才能從 APM 接收警示事件。[在 Amazon Simple Notification Service 主控台中建立 SNS 主題](https://docs.aws.amazon.com/sns/latest/dg/sns-create-topic.html#create-topic-aws-console)。
+ 範本中的 `TransformLambdaFunction` 必須經過修改，才能根據使用的 APM 將 `["detail"]["incident-detection-response-identifier"]` 設定為所需的值。

**先決條件完成：**

1. 開啟 Amazon SNS 主控台，然後選取「主題」。複製為了接收來自 APM 的警示事件而建立的 SNS 主題 ARN。
   + 範例：`arn:aws:sns:eu-west-1:012345678912:<your-apm-name>-sns`

1. 下載並開啟 [CloudFormation 範本](https://dcl74d3hc5lj1.cloudfront.net/apms/ThirdPartyApmSnsIntegration.json)。
   + 在範本中尋找 `TransformLambdaFunction`
     + 在 `def lambda_handler(event, context)` 下，將 `event["detail"]["incident-detection-response-identifier"]` 設定為 json 路徑，其中警示名稱會出現在 SNS 記錄的 JSON 承載中。
       + 任何透過 SNS 傳送至 `TransformLambdaFunction` 的事件都有父承載結構，如 `event["Records"][n]["Sns"]["Message"]`。來自來源 (APM) 的實際承載來源會包裝在父結構內。
       + **Grafana 的範例：**`event["Records"][n]["Sns"]["Message"]["alerts"][n]["labels"]["alertname"]`

**部署 CloudFormation 範本：**

1. 在您需要設定整合的帳戶和區域中，瀏覽至 CloudFormation 主控台。

1. 導覽至 CloudFormation。
   + 選擇「建立堆疊」、「使用新資源 (標準)」
     + 選取選擇現有範本、上傳範本檔案、選擇檔案，然後上傳您儲存在本機上的 CloudFormation 範本。

1. 指定堆疊詳細資訊：
   + 輸入堆疊名稱 (*範例：*`<your-apm-name>IntegrationForIDR`)
   + 指定**先決條件完成**期間取得的參數值
     + APMNameParameter *範例：*`Grafana`
     + TriggerSNSParameter *範例：*`arn:aws:sns:eu-west-1:012345678912:<your-apm-name>-sns`
   + 選擇「下一步」。

1. 設定堆疊選項：
   + 捲動至頁面底部並確認核取方塊，以允許 CloudFormation 使用自訂名稱建立 IAM 資源。

1. 檢閱和建立：
   + 驗證參數值的設定正確無誤，然後選擇「提交」。

1. CloudFormation 堆疊會部署必要的資源，以將 APM 事件整合到 AWS 事件偵測與回應。等到 CloudFormation 堆疊狀態顯示為 **CREATE\_COMPLETE**。

1. CloudFormation 堆疊會建立下列資源，假設範例值已輸入 Grafana 的參數中，且在 EU-WEST-1 區域中執行。
   + CustomEventBus: Grafana-AWSIncidentDetectionResponse-EventBus
   + SNSSubscription: arn:aws:sns:eu-west-1:012345678912:grafana-sns:[random\_string]
   + TransformLambdaExecutionRole: IDR-TransformLambdaExecutionRole-eu-west-1
   + TransformLambdaFunction: Grafana-AWSIncidentDetectionResponse-Lambda-Transform
   + TransformLambdaPermission: GrafanaIntegrationForIDR-TransformLambdaPermission-[random\_string]

**整合測試**

成功部署 CloudFormation 堆疊後，您可以從 APM 傳送測試承載來驗證整合。從 APM 傳送測試承載後：

1. 瀏覽至 Lambda 主控台，然後選取 `APMNameParameter-AWSIncidentDetectionResponse-Lambda-Transform` 函式。接著選擇「監控」索引標籤。

1. 在指標圖中應該會看到成功的調用。

1. 選取「檢視 Amazon CloudWatch Logs」。您可以從日誌串流中的日誌事件進行驗證，以確認從 APM 傳送的測試承載是否存在，或是遇到任何錯誤。

**將您的事件匯流排 ARN 與 AWS 事件偵測與回應共用**

1. 瀏覽至 Amazon EventBridge 主控台。選取事件匯流排。

1. 記錄隨 CloudFormation 堆疊一起部署的**自訂事件匯流排**的 ARN，例如：`arn:aws:events:eu-west-1:012345678912:event-bus/Grafana-AWSIncidentDetectionResponse-EventBus`。
   + 在 [警示擷取問卷 - 概觀](idr-gs-questionnaire.md#idr-gs-alarm-questionnaire) 的「第三方 APM 警示」區段的「EventBridge 事件匯流排 ARN」欄位中，將此自訂事件匯流排的 ARN 提供給 AWS 事件偵測與回應。

1. 在上線過程中，AWS 事件偵測與回應會在此自訂事件匯流排上建立受管 EventBridge 規則，以擷取您的 APM 警示。

## 選項 2：手動整合
<a name="idr-gs-apm-sns-manual"></a>

![圖中顯示使用 Amazon SNS 的整合範例。](http://docs.aws.amazon.com/zh_tw/IDR/latest/userguide/images/example-int-sns.png)


1. 開啟 Amazon SNS 主控台並[在 Amazon Simple Notification Service 主控台中建立 SNS 主題](https://docs.aws.amazon.com/sns/latest/dg/sns-create-topic.html#create-topic-aws-console)，名為 `[apm_name]-sns`，以接收來自 APM 的警示事件。請記下所建立 SNS 主題的 ARN。

1. 執行下列其中一項：
   + (建議方法) 建立 EventBridge 自訂事件匯流排，名為 `[apm_name]-AWSIncidentDetectionResponse-EventBus`。
   + (替代方法) 使用預設 EventBridge 事件匯流排，而不使用自訂事件匯流排。

   AWS 事件偵測與回應會透過 `AWSServiceRoleForHealth_EventProcessor` SLR，在自訂或預設事件匯流排上安裝受管規則 (`AWSHealthEventProcessorEventSource-DO-NOT-DELETE`)。規則來源將是自訂或預設事件匯流排，規則目的地將是 AWS 事件偵測與回應，且規則將符合擷取第三方 APM 事件的模式。

1. 建立名為 `$YourApmName-AWSIncidentDetectionResponse-LambdaFunction` 的 [Lambda](https://docs.aws.amazon.com/lambda/latest/dg/welcome.html) 函式來轉換 SNS 承載。
   + 轉換後的事件必須符合 [使用 EventBridge 擷取 APM 警示的承載需求](idr-gs-apm-payload-requirements.md) 中所述的承載需求
   + 將 Lambda 函式的目標設定為步驟 2 中建立的自訂事件匯流排 (建議方法)，或設定為預設事件匯流排。

1. 將 SNS 主題設定為 Lambda 函式 `$YourApmName-AWSIncidentDetectionResponse-LambdaFunction` 的觸發條件。
   + 在「新增觸發」頁面中，搜尋「SNS」。
   + 新增在步驟 1 中所建立的專用 SNS 主題的 ARN。
   + 選擇「新增」。

1. 依照您的 APM 文件中所述，設定 APM 承載的 SNS 目的地，以供 AWS 事件偵測與回應擷取。

AWS 事件偵測與回應會透過 `AWSServiceRoleForHealth_EventProcessor` SLR，在自訂或預設事件匯流排上安裝受管規則 (`AWSHealthEventProcessorEventSource-DO-NOT-DELETE`)。規則來源將是自訂或預設事件匯流排，規則目的地將是 AWS 事件偵測與回應，且規則將符合擷取第三方 APM 事件的模式。