Managing alerts by using the Alerts API

You can manage alerts in a IBM Cloud Monitoring instance by using the Monitoring API.

To learn how to use cURL, see cURL command.

Get details about a user alert

You can use the following cURL command to get information about an alert:

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> indicates the endpoint targetted by the REST API call. For more information, see Monitoring REST API endpoints. For example, the public endpoint for an instance that is available in us-south is the following: https://us-south.monitoring.cloud.ibm.com/api
You can pass multiple headers by using -H.

Authorization and IBMInstanceID are headers that are required for authentication.

TeamID is optional. When you specify this header, you limit the request to the data and resources available for the team specified.

To get an AUTH_TOKEN and the GUID see, Headers for IAM Tokens.
<ALERT_ID> defines the ID of the alert that you want to modify.

For example, the response body for an alert looks as follows:

{
  "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
  }
}

Create an alert

You can use the following cURL command to create an alert:

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> indicates the endpoint targetted by the REST API call. For more information, see Monitoring REST API endpoints. For example, the public endpoint for an instance that is available in us-south is the following: https://us-south.monitoring.cloud.ibm.com/api
You can pass multiple headers by using -H.

Authorization and IBMInstanceID are headers that are required for authentication.

TeamID is optional. When you specify this header, you limit the request to the data and resources available for the team specified.

To get an AUTH_TOKEN and the GUID see, Headers for IAM Tokens.
You can pass data to create the alert in the alert.json file by using -d.

When you create an alert, include the following parameters: type, name, severity, timespan, condition, segmentby, segmentConditionn, filter, notificationChannelIds, enabled

For more information, see Alert schema.

The following sample shows the request body parameters that you can set to create an alert:

{
  "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"
  }
}

Update an alert

To update an existing alert, you need the ID of that alert.

You can use the following cURL command to update an alert:

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> indicates the endpoint targetted by the REST API call. For more information, see Monitoring REST API endpoints. For example, the public endpoint for an instance that is available in us-south is the following: https://us-south.monitoring.cloud.ibm.com/api
You can pass multiple headers by using -H.

Authorization and IBMInstanceID are headers that are required for authentication.

TeamID is optional. When you specify this header, you limit the request to the data and resources available for the team specified.

To get an AUTH_TOKEN and the GUID see, Headers for IAM Tokens.
<ALERT_ID> defines the ID of the alert that you want to modify.
You can pass data to create the alert in the alert.json file by using -d.

For more information, see Alert schema.

The following sample shows the request body parameters that you can set to update an alert:

{
  "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
      ]
    }
}

Delete an alert

To delete an existing alert, you need the ID of that alert.

You can use the following cURL command to delete an alert:

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> indicates the endpoint targetted by the REST API call. For more information, see Monitoring REST API endpoints. For example, the public endpoint for an instance that is available in us-south is the following: https://us-south.monitoring.cloud.ibm.com/api
You can pass multiple headers by using -H.

Authorization and IBMInstanceID are headers that are required for authentication.

TeamID is optional. When you specify this header, you limit the request to the data and resources available for the team specified.

To get an AUTH_TOKEN and the GUID see, Headers for IAM Tokens.
<ALERT_ID> defines the ID of the alert that you want to delete.

Get all user alerts

You can use the following cURL command to get information about all the alerts:

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> indicates the endpoint targetted by the REST API call. For more information, see Monitoring REST API endpoints. For example, the public endpoint for an instance that is available in us-south is the following: https://us-south.monitoring.cloud.ibm.com/api
You can pass multiple headers by using -H.

Authorization and IBMInstanceID are headers that are required for authentication. To get an AUTH_TOKEN and the GUID see, Headers for IAM Tokens.
to and from are query parameters that you must define to configure the period of time for which you want information on the alerts.

For more information about the response format, see Alert schema.

Alerts schema: Request body

{
  "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 schema: Response body

{
  "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
      }
    }
  ]
}

Error response codes

The following table show common error response codes:

Table 1. RC
RC	Description
`400`	The alert configuration is not valid.
`401`	Unauthorized access.
`404`	The alert ID is not recognized.
`409`	There is a version mismatch.
`422`	The alert name is not valid. The name is already used.

Body parameters

id (integer)

ID of an alert.

condition (string)

Defines the threshold that is configured for the alert. This parameter is required for MANUAL alerts only.

For example, you can defines a consition as follows: avg(timeAvg(uptime)) <= 0

createdOn (integer)

Defines the creation time of an alert in milliseconds.

This parameter returns the Unix-timestamp when the alert was created.

description (string)

This parameter describes the alert.

The description is available when you view an alert in the Alerts section of the monitoring UI, and it is included in notification emails.

enabled (boolean)

Defines the status of an alert.

By default, this parameter is set to true and the alert is enabled when it is created.

filter (string)

Defines the scope of the alert by configuring segments.

When this field is empty, all the metric sources are included. The scope is set to Everything.

For example, you can define filters like the following ones:

kubernetes.namespace.name='production'

container.image='nginx'*.

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

name (string)

Name of the alert. Must be unique.

The name is used to identify the alert in the Alerts section of the monitoring UI, and it is included in notification emails.

modifiedOn (integer)

Defines when an alert was last modified in milliseconds.

This parameter defines the Unix-timestamp when the alert was last modified.

notificationChannelIds (array)

Lists the notification channels that are configured to notify when an alert is triggered.

Valid options are EMAIL, PAGER_DUTY, WEBHOOK, VICTOROPS, and SLACK.

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

notificationCount (integer)

Defines the number of notifications that are sent for the alert during the past 2 weeks.

reNotify (boolean)

Defines whether you want to get follow up notifications until the alert condition is acknowledged and resolved.

By default, follow up notifications are not enabled and the field is set to false.

reNotifyMinutes (integer)

Defines how often do you want to receive notifications on an alert that is not resolved.

You specify the number of minutes before a reminder is sent.

severity (integer)

Defines the syslog-encoded alert severity.

The following table lists the values that you can set:

Table 2. Severity values
Severity	Info
`0`	`emergency`
`1`	`alert`
`2`	`critical`
`3`	`error`
`4`	`warning`
`5`	`notice`
`6`	`informational`
`7`	`debug`

severityLabel (string)

Defines the criticality of an alert. Valid values are HIGH, MEDIUM, LOW, and INFO. A lesser value indicates a higher severity.

The following table shows the severity status that must be set depending on the severity parameter value:

Table 3. Severity level values
Severity	Severity status
`0`	`HIGH`
`1`	`HIGH`
`2`	`MEDIUM`
`3`	`MEDIUM`
`4`	`LOW`
`5`	`LOW`
`6`	`INFO`
`7`	`INFO`

segmentBy (array of strings)

Defines additional segmentation criteria.

For example, you can segment a CPU alert by ['host.mac', 'proc.name'] so the alert can report on any process in any machine for which you get data in the monitoring instance.

segmentCondition (string)

Defines when the alert is triggered for each monitored entity that is specified in the segmentBy parameter. This parameter is required for MANUAL alerts only.

Valid values are the following:

ANY: The alert is triggered when at least one of the monitored entities satisfies the condition.
ALL: The alert is triggered when all of the monitored entities satisfy the condition.

teamId (string)

Defines the GUID of the team that owns the alert.

type (string)

Defines the type of alert. Valid values are MANUAL, BASELINE, and HOST_COMPARISON.

Set to MANUAL for alerts that you want to control when a notification is sent. You must define the threshold that determines when the alert is triggered.

Set to BASELINE for alerts that you want to notify when unexpected metric values are detected. New metric data is compared with metric values that are collected over time.

Set to HOST_COMPARISON for alerts that you want to notify when 1 host in a group reports metrics values that are different from the other hosts in the group.

timespan (integer)

Minimum time interval, in microseconds, for which the alert condition must be met before the alert is triggered.

The minimum value is 60000000 microseconds, that is, 1 minute.

The value of this parameter must be a multiple of 60000000 microseconds.

version (integer)

Version of an alert.

The version changes every time you update an alert.

The version is used for optimistic locking.

Query parameters

alertId (integer)

ID of an alert.

from (long)

Defines the start timestamp, in microseconds, that is used when you request information about alerts that are defined.

to (long)

Defines the end timestamp, in microseconds, that is used when you request information about alerts that are defined.