# 从与 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/)。
此 CloudFormation 模板必须部署在 AWS 事件检测及响应服务需要从中摄取警报的每个 AWS 账户和区域中。
本文档中提供的示例适用于 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)。
+ 必须根据所使用的 APM 来修改模板中的 `TransformLambdaFunction`，以便将 `["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. 假设示例值已输入到 Grafana 的参数中并在 EU-WEST-1 区域中执行，CloudFormation 堆栈会创建以下资源。
   + 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 发送的测试有效载荷是否存在，或者是否遇到了任何错误。

**与 AWS 事件检测及响应服务共享您的事件总线 ARN**

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_cn/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. 执行下列操作之一：
   + （建议）创建名为 `[apm_name]-AWSIncidentDetectionResponse-EventBus` 的 EventBridge 自定义事件总线。
   + （替代）使用默认的 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 文档，为需要由 AWS 事件检测及响应服务摄取的 APM 有效载荷设置 SNS 目标。

AWS 事件检测及响应服务将通过 `AWSServiceRoleForHealth_EventProcessor` SLR，在自定义或默认事件总线上安装托管式规则 (`AWSHealthEventProcessorEventSource-DO-NOT-DELETE`)。规则源将是自定义或默认事件总线，规则目标将是 AWS 事件检测及响应服务，而规则将与用于摄取第三方 APM 事件的模式相匹配。