IBM Cloud Docs
使用警报 API 管理警报

使用警报 API 管理警报

您可以使用 Monitoring API 来管理 IBM Cloud Monitoring 实例中的警报。

要了解如何使用cURL, cURL命令

获取有关用户警报的详细信息

可以使用以下 cURL 命令来获取有关警报的信息:

curl -X GET <REST_API_ENDPOINT>/api/alerts/<ALERT_ID> -H "Authorization: $AUTH_TOKEN" -H "IBMInstanceID: $GUID" -H "TeamID: $TEAM_ID" -H "content-type: application/json"

Where

  • <REST_API_ENDPOINT> 指示 REST API 调用所指向的端点。 有关更多信息,请参阅 Monitoring REST API 端点。 例如,在 us-south 中可用的实例的公共端点如下所示: https://us-south.monitoring.cloud.ibm.com/api

  • 您可以使用 -H 来传递多个头。

    AuthorizationIBMInstanceID 是认证所需的头。

    TeamID 是可选的。 指定此头时,将请求限制为可用于指定团队的数据和资源。

    要获取 AUTH_TOKENGUID,请参阅 IAM 令牌的头

  • <ALERT_ID> 定义要修改的警报的标识。

例如,警报的响应主体如下所示:

{
  "alert": {
    "autoCreated": false,
    "condition": "min(min(dallas_prod)) = 0",
    "createdOn": 1551358413000,
    "enabled": false,
    "id": 23211,
    "modifiedOn": 1551634372000,
    "name": "Monitoring Uptime Alert",
    "filter": "env in (\"prod\")",
    "notificationChannelIds": [
      4
    ],
    "segmentBy": [
      "host.hostname"
    ],
    "segmentCondition": {
      "type": "ANY"
    },
    "notificationCount": 60,
    "rateOfChange": false,
    "reNotify": false,
    "severity": 0,
    "severityLabel": "HIGH",
    "teamId": 493,
    "timespan": 60000000,
    "type": "MANUAL",
    "version": 9
  }
}

创建警报

您可以使用以下cURL命令创建警报:

curl -X POST <REST_API_ENDPOINT>/api/alerts -H "Authorization: $AUTH_TOKEN" -H "IBMInstanceID: $GUID" -H "TeamID: $TEAM_ID" -H "content-type: application/json" -d @alert.json

Where

  • <REST_API_ENDPOINT> 指示 REST API 调用所指向的端点。 有关更多信息,请参阅 Monitoring REST API 端点。 例如,在 us-south 中可用的实例的公共端点如下所示: https://us-south.monitoring.cloud.ibm.com/api

  • 您可以使用 -H 来传递多个头。

    AuthorizationIBMInstanceID 是认证所需的头。

    TeamID 是可选的。 指定此头时,将请求限制为可用于指定团队的数据和资源。

    要获取 AUTH_TOKENGUID,请参阅 IAM 令牌的头

  • 您可以使用 -d 传递数据以在 alert.json 文件中创建警报。

    创建警报时,请包含以下参数:类型名称严重性时间跨度条件segmentbysegmentConditionn过滤器notificationChannelIds已启用

    有关更多信息,请参阅 警报模式

以下样本显示了可以设置以创建警报的请求主体参数:

{
  "alert": {
    "version": null,
    "name": "My Alert!",
    "description": null,
    "teamId": null,
    "enabled": false,
    "filter": null,
    "type": "MANUAL",
    "condition": "avg(timeAvg(uptime)) <= 0",
    "timespan": 600000000,
    "notificationChannelIds": [],
    "reNotify": false,
    "reNotifyMinutes": 30,
    "segmentBy": [
      "host.hostName"
    ],
    "segmentCondition": {
      "type": "ANY"
    },
    "severityLabel": "LOW"
  }
}

更新警报

要更新现有警报,您需要该警报的标识。

您可以使用以下 cURL 命令来更新警报:

curl -X PUT <REST_API_ENDPOINT>/api/alerts/<ALERT_ID> -H "Authorization: $AUTH_TOKEN" -H "IBMInstanceID: $GUID" -H "TeamID: $TEAM_ID" -H "content-type: application/json" -d @alert.json

Where

  • <REST_API_ENDPOINT> 指示 REST API 调用所指向的端点。 有关更多信息,请参阅 Monitoring REST API 端点。 例如,在 us-south 中可用的实例的公共端点如下所示: https://us-south.monitoring.cloud.ibm.com/api

  • 您可以使用 -H 来传递多个头。

    AuthorizationIBMInstanceID 是认证所需的头。

    TeamID 是可选的。 指定此头时,将请求限制为可用于指定团队的数据和资源。

    要获取 AUTH_TOKENGUID,请参阅 IAM 令牌的头

  • <ALERT_ID> 定义要修改的警报的标识。

  • 您可以使用 -d 传递数据以在 alert.json 文件中创建警报。

    有关更多信息,请参阅 警报模式

以下样本显示了可以设置以更新警报的请求主体参数:

{
  "alert": {
      "type": "MANUAL",
      "id": 23212,
      "version": 10,
      "name": "CheckNginxConnections",
      "description": "Active connections of nginx server",
      "enabled": false,
      "severity": 2,
      "timespan": 1000000,
      "condition": "avg(avg(nginx.net.connections)) > 1000",
      "segmentBy": [
          "host.hostName"
      ],
      "segmentCondition": {
          "type": "ANY"
      },
      "notificationChannelIds": [
          2
      ]
    }
}

删除警报

要删除现有警报,您需要该警报的标识。

您可以使用以下 cURL 命令来删除警报:

curl -X DELETE <REST_API_ENDPOINT>/api/alerts/<ALERT_ID> -H "Authorization: $AUTH_TOKEN" -H "IBMInstanceID: $GUID" -H "TeamID: $TEAM_ID" -H "content-type: application/json"

Where

  • <REST_API_ENDPOINT> 指示 REST API 调用所指向的端点。 有关更多信息,请参阅 Monitoring REST API 端点。 例如,在 us-south 中可用的实例的公共端点如下所示: https://us-south.monitoring.cloud.ibm.com/api

  • 您可以使用 -H 来传递多个头。

    AuthorizationIBMInstanceID 是认证所需的头。

    TeamID 是可选的。 指定此头时,将请求限制为可用于指定团队的数据和资源。

    要获取 AUTH_TOKENGUID,请参阅 IAM 令牌的头

  • <ALERT_ID> 定义了要删除的警报的 ID。

获取所有用户警报

可以使用以下 cURL 命令来获取有关所有警报的信息:

curl -X GET <REST_API_ENDPOINT>/api/alerts?from=<START_TIMESTAMP>&to=<END_TIMESTAMP> -H "Authorization: Bearer $AUTH_TOKEN" -H "IBMInstanceID: $GUID"

Where

  • <REST_API_ENDPOINT> 指示 REST API 调用所指向的端点。 有关更多信息,请参阅 Monitoring REST API 端点。 例如,在 us-south 中可用的实例的公共端点如下所示: https://us-south.monitoring.cloud.ibm.com/api

  • 您可以使用 -H 来传递多个头。

    AuthorizationIBMInstanceID 是认证所需的头。 要获取 AUTH_TOKENGUID,请参阅 IAM 令牌的头

  • tofrom 是您必须定义的查询参数,用于配置要获取有关警报的信息的时间段。

有关响应格式的更多信息,请参阅 警报模式

警报模式: 请求主体

{
  "alerts": [
    {
      "alert": {
        "version": null,
        "name": "",
        "description": null,
        "teamId": null,
        "enabled": false,
        "filter": null,
        "type": "",
        "condition": "",
        "timespan": 600000000,
        "notificationChannelIds": [],
        "reNotify": false,
        "reNotifyMinutes": 30,
        "segmentBy": [],
        "segmentCondition": {
          "type": ""
        },
        "severityLabel": ""
      }
    }
  ]
}

警报模式: 响应主体

{
  "alerts": [
    {
    "alert": {
      "autoCreated": false,
      "condition": "",
      "createdOn": 1551358413000,
      "enabled": false,
      "id": 23211,
      "modifiedOn": 1551634372000,
      "name": "",
      "filter": "",
      "notificationChannelIds": [],
      "segmentBy": [],
      "segmentCondition": {
        "type": "ANY"
      },
      "notificationCount": 60,
      "rateOfChange": false,
      "reNotify": false,
      "severity": 0,
      "severityLabel": "",
      "teamId": 493,
      "timespan": 60000000,
      "type": "",
      "version": 9
      }
    }
  ]
}

错误响应码

下表显示了常见错误响应代码:

RC
RC 描述
400 警报配置无效。
401 未经授权的访问。
404 无法识别警报标识。
409 存在版本不匹配。
422 警报名称无效。 该名称已被使用。

主体参数

标识 (整数)

警报的标识。

条件 (字符串)

定义为警报配置的阈值。 仅 "MANUAL 警报需要此参数。

例如,您可以按如下所示定义收货: avg(timeAvg(uptime)) <= 0

createdOn (整数)

定义警报的创建时间 (以毫秒为单位)。

此参数返回创建警报时的 Unix-timestamp。

描述 (字符串)

该参数用于描述警报。

当您在监视 UI 的 警报 部分中查看警报时,该描述可用,并包含在通知电子邮件中。

已启用 (布尔值)

定义警报的状态。

缺省情况下,此参数设置为 true,并在创建警报时启用警报。

过滤器 (字符串)

通过配置分段来定义警报的作用域。

当此字段为空时,将包括所有度量标准源。 作用域设置为 所有内容

例如,您可以定义类似于以下的过滤器:

kubernetes.namespace.name='production'
container.image='nginx'*.
kubernetes.namespace.name='production' and container.image='nginx'*.

name (String)

警报的名称。 必须唯一。

该名称用于在监视 UI 的 警报 部分中标识警报,并包含在通知电子邮件中。

modifiedOn (整数)

定义上次修改警报的时间 (以毫秒计)。

此参数定义上次修改警报时的 Unix-timestamp。

notificationChannelIds(数组)

列出配置为在触发警报时通知的通知通道。

有效选项包括 EMAILPAGER_DUTYWEBHOOKVICTOROPSSLACK

"notificationChannelIds": [
      "EMAIL",
      "WEBHOOK"
    ]

notificationCount (整数)

定义过去 2 周内针对警报发送的通知数。

reNotify (布尔值)

定义是否要获取后续通知,直到确认并解决警报条件为止。

缺省情况下,未启用后续通知,并且该字段设置为 false

reNotifyMinutes(整数)

定义您希望在未解决的警报上接收通知的频率。

指定发送提示前的分钟数。

严重性 (整数)

定义系统日志编码的警报严重性。

下表列出了可以设置的值:

严重程度值
严重性 参考
0 emergency
1 alert
2 critical
3 error
4 warning
5 notice
6 informational
7 debug

severityLabel (字符串)

定义警报的严重程度。 有效值为 "HIGH"、"MEDIUM"、"LOW"和 "INFO"。 数值越小,表示严重程度越高。

下表显示了必须根据严重性参数值设置的严重性状态:

严重程度值
严重性 严重性状态
0 HIGH
1 HIGH
2 MEDIUM
3 MEDIUM
4 LOW
5 LOW
6 INFO
7 INFO

segmentBy(字符串数组)

定义其他分段条件。

例如,您可以通过 ['host.mac', 'proc.name'] 对 CPU 警报进行分段,以便该警报可以报告在监视实例中获取数据的任何机器中的任何进程。

segmentCondition (字符串)

定义在segmentBy参数中指定的每个受监控实体触发警报的时间。 仅 "MANUAL 警报需要此参数。

有效值如下所示:

  • ANY: 当至少一个受监视实体满足条件时触发警报。
  • ALL: 当所有受监视实体都满足条件时触发警报。

teamId(string)

定义拥有警报的团队的 GUID。

type (String)

定义警报的类型。 有效值为MANUALBASELINEHOST_COMPARISON

对于要在发送通知时控制的警报,设置为 MANUAL。 您必须定义用于确定触发警报的时间的阈值。

对于要在检测到意外度量值时通知的警报,请设置为 BASELINE。 新的度量数据将与一段时间内收集的度量值进行比较。

对于要在组中的 1 主机报告与组中其他主机不同的度量值时通知的警报,请设置为 HOST_COMPARISON

timespan (整数)

在触发警报之前必须满足警报条件的最短时间间隔(以微秒为单位)。

最小值为 60000000 微秒,即 1 分钟。

此参数的值必须是 60000000 微秒的倍数。

版本 (整数)

警报的版本。

每次更新警报时,版本都会更改。

该版本用于乐观锁定。

查询参数

alertId (整数)

警报的标识。

从 (长整型)

定义请求有关已定义的警报的信息时使用的开始时间戳记 (以微秒为单位)。

至 (长)

定义请求有关已定义的警报的信息时使用的结束时间戳记 (以微秒为单位)。