通过自定义集成方式接入告警 - 应用实时监控服务ARMS

ARMS告警管理提供API接入的能力，通过对接告警管理的API，可以将任意告警源产生的告警接入ARMS告警管理进行统一处理。

步骤一：创建自定义集成

登录ARMS控制台，在左侧导航栏选择告警管理 > 集成。
在告警集成页签单击自定义集成。
在新建自定义事件集成对话框输入集成名称，设置告警自动恢复时间，根据需要添加集成描述，然后单击保存并配置。
说明告警事件自动恢复时间：当告警事件在设置的时间内都没有再触发，告警事件将会自动恢复。

步骤二：配置接口链接

通过访问接口链接，将第三方告警源发送到ARMS告警管理。

在编辑集成页面的接口配置区域，复制接口和API密钥链接。

在第三方告警源访问上一步获取的接口地址并上报告警内容。

上报示例：

curl -k -H "Content-Type: application/json" -d '{
  "trigger-type": "network",
  "trigger-location": "cn-hangzhou",
  "trigger-severity": "MAX",
  "trigger-policy": "package errors > 5%",
  "trigger-event": "inbound tcp package errors is 20%",
  "trigger-check": "tcp package error percentage",
  "trigger-value": "20",
  "trigger-time": "1629702922000",
  "metadata": [
    {
      "agent": "SERVER",
      "ip": "141.219.XX.XX",
      "fqdn": "websrv1.damenport.org",
      "microServiceId": "ms-login-2251",
      "accountId": "1504000433993",
      "service": "login-0"
    },
    {
      "agent": "CONTAINER",
      "ip": "172.1.XX.XX",
      "fqdn": "websrv2.damenport.org",
      "microServiceId": "ms-login-2252",
      "accountId": "129930302939",
      "service": "login-1"
    }
  ],
  "equipments": [
    {
      "equipmentId": "112"
    },
    {
      "equipmentId": "113"
    }
  ]
}' "https://alerts.aliyuncs.com/api/v1/integrations/custom/ymQBN******"

首次执行时，命令行curl会返回如下所示的错误提示，这是正常的。

{ "requestId":null,"traceId":"0bc3b4a********71e4aa7","code":601,"data":{},"success":false,"errorCode":"Invalid incident, labels.alertname is required","message":"Invalid incident, labels.alertname is required","httpStatusCode":601,"errorCodeParams":null,"dynamicMessage":null

您需要在下文步骤三完成映射后，再次执行时，curl命令则会返回正确的数据。

您也可以通过发送测试数据进行告警上报。首次执行时会出现如下提示，根据提示您可以在下文步骤三完成映射。

步骤三：设置告警字段映射

在事件映射区域设置第三方告警源与ARMS告警事件字段的映射。

此处操作将使用以下场景作为示例。

告警数据场景：机器网络发生TCP Package错误。

第三方告警内容：

{
  "trigger-type": "network",    //事件类型：网络。
  "trigger-location": "cn-hangzhou",    //事件发生地域。
  "trigger-severity": "MAX",    //自定义的事件等级，例如：MAX、MID、LOW。
  "trigger-policy": "package errors > 5%",     //触发策略。
  "trigger-event": "inbound tcp package errors is 20%",    //事件内容：服务入站TCP包错误率为20%。
  "trigger-check": "tcp package error percentage",    //事件检查项：TCP包错误率。
  "trigger-value": "20",    //告警样本值。
  "trigger-time": "1629702922000",    //告警开始时间。
  "metadata": [
    {
      "agent": "SERVER",    //探测端类型：服务器。
      "ip": "141.219.XX.XX",   // IP地址。
      "fqdn": "websrv1.damenport.org",    //服务域名信息。
      "microServiceId": "ms-login-2251",    //微服务ID ，"agent"为CONTAINER时，该字段条件映射到ARMS的service字段。
      "accountId": "1504000433993",    //用户ID，告警通知中不体现。
      "service": "login-0" //服务ID ，"agent"为SERVER时，该字段条件映射到ARMS的service字段。
    },
    {
      "agent": "CONTAINER",   //探测端类型：容器。
      "ip": "172.1.XX.XX",  // IP地址。
      "fqdn": "websrv2.damenport.org",    //服务域名信息。
      "microServiceId": "ms-login-2252",   //微服务ID ，"agent"为CONTAINER时，该字段条件映射到ARMS的service字段。
      "accountId": "129930302939",  //用户ID，告警通知中不体现。
      "service": "login-1"    //服务ID ，"agent"为SERVER时，该字段条件映射到ARMS的service字段。
    }
  ],
  "equipments": [  //另一个数组节点。
    {
      "equipmentId": "112"
    },
    {
      "equipmentId": "113"
    }
  ]
}

在事件映射区域左侧单击发送测试数据。
在发送测试数据对话框，输入第三方告警源的JSON格式的告警内容，然后单击发送。
说明
- 如果显示上传成功，但未生成事件，请根据原始数据配置事件映射规则!，表示告警源与ARMS告警事件的字段没有映射，实际发送数据会被保存在左侧记录框中，以便配置映射时可以直接选取对应告警源字段。
- 如果显示上传成功！，则表明对应的告警内容已上报至告警事件历史页面。更多信息，请参见查看告警事件历史。
在发送测试数据对话框单击关闭。
在事件映射区域左侧单击并展开需要建立映射的告警数据。

在事件映射区域右侧配置告警源字段与ARMS告警的映射。

可选：在选择根节点区域选择是否使用批处理。
当告警数据存在数组节点时，可以指定目标数组节点作为根节点，将对应根节点下的数据进行批处理。
选择使用批处理后，选择需要批处理的数组节点作为根节点。
说明当告警数据存在多个数组节点时，ARMS告警管理仅支持选择其中一个数组节点进行批处理。
例如：对于告警示例场景metadata数组节点下的两个service字段，选择metadata为根节点后，节点下的两个service字段将会作为同一字段映射到ARMS的指定告警字段。
- 选择为根节点：可以设置将数组中所有元素的$.metadata[*].service属性值迭代映射到ARMS的service字段。
- 不选择为根节点：可以选择将数组中的具体下标元素$.metadata[0].service或$.metadata[1].service属性值迭代映射到ARMS的service字段。
可选：选中配置告警恢复事件，然后设置恢复字段条件。
系统收到事件后会根据恢复字段查询告警事件，包含指定字段的事件会自动进行恢复。用于指定恢复事件的字段必须选择原事件中等价于告警等级的字段，且不可使用$.severity字段。例如恢复字段为{$.eventType ="resolved"}，则系统会自动恢复该集成下eventType为resolved的所有告警。

在将源字段映射到目标字段区域将告警源字段映射到ARMS告警字段上。

单击映射图标，可以修改字段映射方式。

直接：告警源指定字段直接映射为ARMS中对应的告警字段。
串联：将多个告警源字段通过指定分隔符串联为一个字段，然后将这一个字段映射为ARMS中对应的告警字段。分隔符仅支持特殊字符。
例如：可以将字段$.trigger-type和$.trigger-policy使用短下划线（_）串联为$.trigger-type_$.trigger-policy，然后映射到ARMS的alertname字段上。
条件：当告警字段值满足指定条件后，设置的字段才会映射到ARMS目标字段上。
例如，如下图所示，对于metadata数组节点下的agent字段，如果agent取值为CONTAINER，就将metadata数组节点下的microServiceId属性值映射到ARMS的service字段上，即If条件；如果agent取值为SERVER时，就将metadata数组节点下的service属性值映射到ARMS的service字段上，即Else If条件。
映射表：设置告警源的告警等级与ARMS中的告警等级的映射，仅告警等级（severity）字段需要设置映射表。

ARMS告警字段说明：


ARMS告警字段	说明	示例映射方式	示例场景映射字段
告警名称（alertname）	自定义告警的名称。	串联	`$.trigger-type`，`$.trigger-policy`
告警等级（severity）	设置告警等级的映射字段。该字段需要设置告警等级映射表，且映射方式必须设置为直接映射。	映射方式：直接（必选）映射表： MAX：P1 MID：P2 MIN：P3	`$.trigger-severity`
告警描述（message）	告警事件的详细信息，用于告警通知。最多支持15000字符。	直接	`$.trigger-event`
告警样本值（value）	监控指标的样本值。	直接	`$.trigger-value`
告警图片（imageUrl）	指标折线图URL，用于映射Grafana指标折线图。	无	无
检查项（check）	告警检查项。例如：CPU、JVM、Application Crash、Deployment。	直接	`$.trigger-check`
来源（source）	告警事件的来源。	直接	`$.metadata[*].ip`
分类（class）	告警事件的对象类型，例如：主机。	直接	`$.trigger-type`
服务（service）	与业务相关的来源服务，例如：logService。	条件	如果`$.metadata[].agent`为CONTAINER，`$.metadata[].microServiceId`映射到ARMS的`service`字段上。如果`$.metadata[].agent`为SERVER，`$.metadata[].service`映射到ARMS的`service`字段上。
开始时间（startat）	事件开始时间的时间戳。	直接	`$.trigger-time`
结束时间（endat）	事件结束时间的时间戳。	无	无
事件地址（generatorUrl）	事件详细信息地址。	无	无

步骤四：设置事件去重

为了减少重复数据，系统使用相关字段作为去重依据。ARMS告警管理支持预览事件映射区域中的历史事件数据的去重分组结果，您可根据需要调整去重字段。

说明事件去重仅针对未恢复状态下的事件。

在事件去重区域选择需要去重的字段。
当选择的字段的值相同时，对应的多个事件将会合并为一个告警通知。
例如：将ARMS的source和check字段设置为去重键，由于示例中第三方告警源的$.metadata[*].ip字段映射到ARMS的source字段，$.trigger-check字段映射到ARMS的check字段。那么IP和检查指标相同的事件将会合并为一个事件，IP不同或检查指标不同的事件仍会分为多个事件。
单击去重测试，可以预览去重后的告警分组。
说明去重测试针对的是事件映射左侧区域中上传的最近10条测试数据。
配置完成后，单击保存。

执行结果

配置完成后，在集成页面可以查看已创建的自定义集成。

管理集成

在告警管理 > 集成页面的告警集成页签，对于已经创建的集成，您可以进行以下操作：

查看集成：如果您需要查看集成的详细信息，单击目标集成所在行，在集成详情页面查看集成的详细信息。
更新密钥：如果您需要修改集成的密钥，在目标集成右侧操作列选择更多 > 更新密钥，在弹出的对话框中单击确认。
重要更新密钥后，请在步骤二上报的告警源中修改访问地址。
编辑：如果您需要修改集成信息，在目标集成右侧操作列单击编辑，在集成详情页面修改集成信息，然后单击保存。
启用或禁用：如果您需要启用或禁用目标集成，在目标集成右侧操作列单击禁用或启用。
删除：如果您需要删除集成，在目标集成右侧操作列单击删除，在弹出的对话框中单击确认。
添加事件流：如果您需要为指定集成添加对应的事件处理流，在目标集成右侧操作列单击添加事件流。具体操作，请参见事件处理流。
新建通知策略：如果您需要为指定集成添加对应的通知策略，在目标集成右侧操作列单击新建通知策略。具体操作，请参见通知策略。

后续步骤

您可以通过设置通知策略将上报的告警事件生成告警并发送告警通知，具体操作，请参见通知策略。经过通知策略分派后生成的告警可以在告警发送历史页面查看告警的详细信息，更多信息，请参见查看告警发送历史。