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

Creating an Alarm Rule

Updated at: May 23, 2019 10:11

Function

This API is used to create an alarm rule.

URI

POST /V1.0/{project_id}/alarms

  • Parameter description
    Table 1 Parameter description

    Parameter

    Description

    project_id

    Indicates the project ID.

  • Example

    /V1.0/{project_id}/alarms

Request

  • Request parameters
    Table 2 Request parameters

    Parameter

    Mandatory

    Type

    Description

    alarm_name

    Yes

    String

    Indicates 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

    The value can be a string of 0 to 256 characters.

    metric

    Yes

    JSON object

    Indicates the alarm metrics.

    namespace

    Yes

    String

    Indicates 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 (_).

    metric_name

    Yes

    String

    Indicates 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 section Querying the Metric List.

    dimensions

    Yes

    JSON array

    Indicates the dimension list, such as ECS Dimension. Currently, the maximum list of metrics dimensions that are supported is 3.

    Indicates the list of the metric dimensions.

    Each dimension is a JSON object, and its structure is as follows:

    dimension.name: indicates the dimension name. 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 (-). For example, the key value of an ECS.

    dimension.value: indicates the dimension value, such as value of ECS Dimension.

    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 (-).

    condition

    Yes

    JSON object

    Indicates the alarm triggering condition.

    period

    Yes

    Integer

    Indicates 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

    Indicates the data rollup method.

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

    comparison_operator

    Yes

    String

    Indicates the operator.

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

    value

    Yes

    Number

    Indicates 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

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

    count

    Yes

    Integer

    Indicates the number of consecutive occurrence times.

    The value ranges from 1 to 5.

    alarm_actions

    Mandatory under certain conditions

    JSON array

    Indicates the action triggered by an alarm.

    An example structure is as follows:

    {

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

    }

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

    notificationList: indicates the list of objects to be notified if the alarm status changes. 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 enable the AS alarm rules take effect, you must bind scaling policies. For details, see the Auto Scaling API Reference.
    • 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.

    type

    Yes

    String

    Indicates the type of action triggered by an alarm.

    The value can be notification or autoscaling.

    notificationList

    Yes

    String array

    Indicates the topicUrn list of the target notification objects.

    The maximum length is 5.

    The topicUrn list can be obtained from Simple Message Notification (SMN) and in the following format: urn: smn:([a-z]|[A-Z]|[0-9]|\-){1,32}:([a-z]|[A-Z]|[0-9]){32}:([a-z]|[A-Z]|[0-9]|\-|\_){1,256}.

    insufficientdata_actions

    Mandatory under certain conditions

    JSON array

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

    type value:

    • notification: indicates that a notification will be sent to the user.
    • notificationList: indicates the list of objects to be notified if the alarm status changes.
      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.

    ok_actions

    Mandatory under certain conditions

    JSON array

    Indicates the action triggered by the clearing of an alarm.

    Its structure is:

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

    type value:

    • notification: indicates that a notification will be sent to the user.
    • notificationList: indicates the list of objects to be notified if the alarm status changes.
      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_enabled

    No

    Boolean

    Indicates whether to enable the alarm.

    The default value is true.

    alarm_level

    No

    Integer

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

    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.

  • 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 3 Response parameters

    Parameter

    Type

    Description

    alarm_id

    String

    Indicates 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