Help Center > > API Reference> API Description> Alarm Rule Management> Creating an Alarm Rule

Creating an Alarm Rule

Updated at: Sep 10, 2019 20:10

Function

This API is used to create an alarm rule.

URI

POST /V1.0/{project_id}/alarms

  • Parameter description
    Table 1 Parameter description

    Parameter

    Mandatory

    Description

    project_id

    Yes

    Specifies the project ID.

    For details about how to obtain the project ID, see Obtaining a Project ID.

  • Example
    POST https://{Cloud Eye endpoint}/V1.0/{project_id}/alarms

Request

  • Request parameters
    Table 2 Request parameters

    Parameter

    Mandatory

    Type

    Description

    alarm_name

    Yes

    String

    Specifies the alarm rule name.

    The value can be a string of 1 to 128 characters that can contain only digits, lowercase letters, uppercase letters, underscores (_), and hyphens (-).

    alarm_description

    No

    String

    Alarm description. The length is 0-256.

    metric

    Yes

    Object

    Specifies the alarm metrics.

    For details, see Table 3.

    condition

    Yes

    Object

    Specifies the alarm triggering condition.

    For details, see Table 8.

    alarm_enabled

    No

    Boolean

    Specifies whether to enable the alarm.

    The default value is true.

    alarm_action_enabled

    Mandatory under certain conditions

    Boolean

    Specifies whether to enable the action to be triggered by an alarm. The default value is true.

    NOTE:

    If alarm_action_enabled is set to true, at least one of alarm_actions, insufficientdata_actions (deprecated, no need to configure), and ok_actions cannot be empty.

    If alarm_actions, insufficientdata_actions (deprecated, no need to configure), and ok_actions exist at the same time, the values of notificationList in the three parameters must be the same.

    alarm_level

    No

    Integer

    Specifies the alarm severity. The value can be 1, 2, 3 or 4, which indicates critical, major, minor, and informational, respectively.

    alarm_actions

    Mandatory under certain conditions

    Array of objects

    Specifies the action triggered by an alarm.

    An example structure is as follows:

    {

    "type": "notification","notificationList": ["urn:smn:region:68438a86d98e427e907e0097b7e35d47:sd"]

    }

    For details, see Table 5.

    ok_actions

    Mandatory under certain conditions

    Array of objects

    Specifies the action triggered by clearing an alarm.

    Its structure is:

    { "type": "notification","notificationList": ["urn:smn:region:68438a86d98e427e907e0097b7e35d47:sd"] }

    For details, see Table 6.

    insufficientdata_actions

    Mandatory under certain conditions

    Array of objects

    Specifies the action triggered by the alarm of insufficient data. (This parameter has been discarded. You are advised not to configure this parameter.)

    Its structure is:

    { "type": "notification","notificationList": ["urn:smn:region:68438a86d98e427e907e0097b7e35d47:sd"] }

    For details, see Table 7.

    Table 3 metric field data structure description

    Parameter

    Mandatory

    Type

    Description

    namespace

    Yes

    String

    Specifies the metric namespace, such as ECS Namespace. Its value must be in the service.item format and contain 3 to 32 characters.

    service and item each must be a string that starts with a letter and contains only uppercase letters, lowercase letters, digits, and underscores (_).

    dimensions

    Yes

    Array of objects

    Specifies the list of the metric dimensions.

    For details, see Table 4.

    metric_name

    Yes

    String

    Specifies the metric name.

    The value can be a string of 1 to 64 characters and must start with a letter and contain only uppercase letters, lowercase letters, digits, and underscores (_).

    For details, see the metric name queried in Querying the Metric List.

    Table 4 dimensions field data structure description

    Parameter

    Mandatory

    Type

    Description

    name

    Yes

    String

    The value can be a string of 1 to 32 characters and must start with a letter and contain only uppercase letters, lowercase letters, digits, underscores (_), and hyphens (-). Example: the Key value in ECS Dimension

    value

    Yes

    String

    The value can be a string of 1 to 256 characters and must start with a letter or a digit and contain only uppercase letters, lowercase letters, digits, underscores (_), and hyphens (-). Example: Value in the ECS Dimension

    Table 5 alarm_actions field data structure description

    Parameter

    Mandatory

    Type

    Description

    type

    Mandatory under certain conditions

    String

    Specifies the alarm notification type.
    • notification: indicates that a notification will be sent to the user.
    • autoscaling: indicates that a scaling action will be triggered.

    notificationList

    Mandatory under certain conditions

    Array of strings

    Specifies the list of objects to be notified if the alarm status changes. You can configure a maximum of 5 object IDs. The value of topicUrn can be obtained from SMN. For details, see Querying Topics.

    If type is set to notification, the value of notificationList cannot be empty. If type is set to autoscaling, the value of notificationList must be [].

    NOTE:
    • To make the Auto Scaling (AS) alarm rule take effect, you must bind the scaling policy. For details, see Creating an AS Policy.
    • If alarm_action_enabled is set to true, at least one of alarm_actions, insufficientdata_actions (deprecated, no need to configure), and ok_actions cannot be empty.
    • If alarm_actions, insufficientdata_actions (deprecated, no need to configure), and ok_actions exist at the same time, the values of notificationList in the three parameters must be the same.
    • The IDs in the list are character strings.
    Table 6 ok_actions field data structure description

    Parameter

    Mandatory

    Type

    Description

    type

    Mandatory under certain conditions

    String

    Specifies the notification type when an alarm is triggered.
    • notification: indicates that a notification will be sent to the user.
    • autoscaling: indicates that a scaling action will be triggered.

    notificationList

    Mandatory under certain conditions

    Array of objects

    Specifies the list of objects to be notified if the alarm status changes. The list contains a maximum of 5 object IDs. The value of topicUrn can be obtained from SMN. For details, see Querying Topics.

    NOTE:

    If alarm_action_enabled is set to true, at least one of alarm_actions, insufficientdata_actions (deprecated, no need to configure), and ok_actions cannot be empty.

    If alarm_actions, insufficientdata_actions (deprecated, no need to configure), and ok_actions exist at the same time, the values of notificationList in the three parameters must be the same.

    Table 7 insufficientdata_actions field data structure description

    Parameter

    Mandatory

    Type

    Description

    type

    Mandatory under certain conditions

    String

    Specifies the notification type when an alarm is triggered.
    • notification: indicates that a notification will be sent to the user.
    • autoscaling: indicates that a scaling action will be triggered.

    notificationList

    Mandatory under certain conditions

    Array of objects

    Specifies the list of objects to be notified if the alarm status changes. You can configure a maximum of 5 object IDs. The value of topicUrn can be obtained from SMN. For details, see Querying Topics.

    NOTE:
    • If alarm_action_enabled is set to true, at least one of alarm_actions, insufficientdata_actions (deprecated, no need to configure), and ok_actions cannot be empty.
    • If alarm_actions, insufficientdata_actions (deprecated, no need to configure), and ok_actions exist at the same time, the values of notificationList in the three parameters must be the same.
    • The IDs in the list are character strings.
    Table 8 condition field data structure description

    Parameter

    Mandatory

    Type

    Description

    period

    Yes

    Integer

    Specifies the alarm checking period in seconds.

    The value can be 1, 300, 1200, 3600, 14400, and 86400.

    NOTE:
    • If period is set to 1, the raw monitoring data is used to determine whether to generate an alarm.

    filter

    Yes

    String

    Specifies the data rollup method.

    The value can be Max., Min., Avg., Sum, or Variance.

    comparison_operator

    Yes

    String

    Specifies the operator.

    The value can be >, =, <, , or .

    value

    Yes

    Integer or Float

    Specifies the alarm threshold.

    The value ranges from 0 to Number. MAX_VALUE (1.7976931348623157e+108).

    For details about the thresholds, see the value range of each metric in the appendix. For example, the value of cpu_util in Metrics can be 80.

    unit

    No

    String

    Specifies the data unit. The value contains a maximum of 32 characters.

    count

    Yes

    Integer

    Specifies the number of consecutive occurrence times.

    The value ranges from 1 to 5.

  • Example request
    {
        "alarm_name": "alarm-rp0E", 
        "alarm_description": "", 
        "metric": {
            "namespace": "SYS.ECS", 
            "dimensions": [
                {
                    "name": "instance_id", 
                    "value": "33328f02-3814-422e-b688-bfdba93d4051"
                }
            ], 
            "metric_name": "network_outgoing_bytes_rate_inband"
        }, 
        "condition": {
            "period": 300, 
            "filter": "average", 
            "comparison_operator": ">=", 
            "value": 6, 
            "unit": "B/s", 
            "count": 1        
       }, 
        "alarm_enabled": true, 
        "alarm_action_enabled": true, 
        "alarm_level": 2,
        "alarm_actions": [
            {
                "type": "notification", 
                "notificationList": ["urn:smn:region:68438a86d98e427e907e0097b7e35d48:sd"]
            }
        ], 
        "ok_actions": [
            {
                "type": "notification", 
                "notificationList": ["urn:smn:region:68438a86d98e427e907e0097b7e35d48:sd"]
            }
        ],
        "insufficientdata_actions": [
            {
                "type": "notification", 
                "notificationList": ["urn:smn:region:68438a86d98e427e907e0097b7e35d48:sd"]
            }
        ]
    }

Response

  • Response parameters
    Table 9 Response parameters

    Parameter

    Type

    Description

    alarm_id

    String

    Specifies the alarm rule ID.

  • Example response
    { 
        "alarm_id":"al1450321795427dR8p5mQBo"
    }

Returned Values

  • Normal

    201

  • Abnormal

    Returned Values

    Description

    400 Bad Request

    Request error

    401 Unauthorized

    The authentication information is not provided or is incorrect.

    403 Forbidden

    You are forbidden to access the page requested.

    408 Request Timeout

    The request timed out.

    429 Too Many Requests

    Concurrent requests are excessive.

    500 Internal Server Error

    Failed to complete the request because of an internal service error.

    503 Service Unavailable

    The service is currently unavailable.

Error Code

For details, see Error Codes.

Did you find this page helpful?

Submit successfully!

Thank you for your feedback. Your feedback helps make our documentation better.

Failed to submit the feedback. Please try again later.

Which of the following issues have you encountered?







Please complete at least one feedback item.

Content most length 200 character

Content is empty.

OK Cancel