Creating an Alarm Rule (Recommended)
Function
This API is used to create alarm rules.
Debugging
You can debug this API through automatic authentication in API Explorer or use the SDK sample code generated by API Explorer.
URI
POST /v2/{project_id}/alarms
Parameter |
Mandatory |
Type |
Description |
---|---|---|---|
project_id |
Yes |
String |
Definition Tenant ID. Constraints: None Value range: Project ID, used to specify the project that an asset belongs to. You can query the assets of a project by project ID. You can obtain the project ID by calling an API or on the console. For details, see Obtaining a Project ID. The value must contain of 1 to 64 characters. Default value: None |
Request Parameters
Parameter |
Mandatory |
Type |
Description |
---|---|---|---|
Content-Type |
No |
String |
Definition MIME type of the request body. Constraints: None Value range: The value can contain 1 to 64 characters. Default value: The default type is application/json; charset=UTF-8. Default value: application/json; charset=UTF-8 |
X-Auth-Token |
No |
String |
Definition User token. Constraints: None Value range: The value can contain 1 to 16,384 characters. Default value: None |
Parameter |
Mandatory |
Type |
Description |
---|---|---|---|
name |
Yes |
String |
Name of an alarm rule. The name can contain 1 to 128 characters, including only letters, digits, underscores (_), and hyphens (-). |
description |
No |
String |
Alarm rule description. The description can contain 0 to 256 characters. |
namespace |
Yes |
String |
Query the namespace of a service. For details about the namespace of each service, see [Service Name] (ces_03_0059.xml). |
resource_group_id |
No |
String |
Resource group ID, which starts with rg and is followed by 22 characters, including letters and digits. |
resources |
Yes |
Array<Array<Dimension>> |
Resource list. If an alarm rule is created for all resources or resources in a resource group, leave the resource dimension blank. If the alarm rule is created for specified resources, the resource dimension value is mandatory, and you can specify multiple resources to be monitored at a time. |
policies |
No |
Array of Policy objects |
Alarm policy. This parameter is mandatory when alarm_template_id is left blank. |
type |
Yes |
String |
Definition: Alarm rule type. Constraints: None Value range: Enumerated value. ALL_INSTANCE indicates alarm rules for metrics of all resources. RESOURCE_GROUP indicates alarm rules for metrics of resources in a resource group. MULTI_INSTANCE indicates alarm rules for metrics of specified resources. EVENT.SYS indicates alarm rules for system events. EVENT.CUSTOM indicates alarm rules for custom events. DNSHealthCheck indicates alarm rules for health checks. Default value: None Enumeration values:
|
alarm_notifications |
No |
Array of Notification objects |
Action to be triggered by the alarm. |
ok_notifications |
No |
Array of Notification objects |
Action to be triggered after an alarm is cleared. |
notification_begin_time |
No |
String |
Time when the alarm notification was enabled. |
notification_end_time |
No |
String |
Time when the alarm notification was disabled. |
effective_timezone |
No |
String |
Time zone, for example, GMT-08:00, GMT+08:00, or GMT+0:00. |
enterprise_project_id |
No |
String |
Enterprise project ID |
enabled |
Yes |
Boolean |
Whether to enable the alarm rule. true: enabled; false: disabled. |
notification_enabled |
Yes |
Boolean |
Whether to enable alarm notification. true: enabled; false: disabled. |
alarm_template_id |
No |
String |
ID of an alarm template associated with an alarm rule. If this parameter is specified, the policy associated with the alarm rule changes accordingly with the alarm template policy. |
tags |
No |
Array of ResourceTag objects |
Tenant tags. |
product_name |
No |
String |
Product name. It needs to be specified when product alarm rules with multiple dimensions are created. Generally, the value format is Service namespace,First-level dimension of the service, for example, SYS.ECS,instance_id. Regex Pattern: ^(([a-z]|[A-Z]){1}([a-z]|[A-Z]|[0-9]|_|-|\.){0,31}(,([a-z]|[A-Z]){1}([a-z]|[A-Z]|[0-9]|_|-|\.){0,31}){0,3}|)$ |
resource_level |
No |
String |
Product alarm rules with multiple dimensions need to be specified as product-level rules during creation. If the value of resource_level is product, cloud product alarm rules with multiple dimensions are used. If the value of resource_level is dimension or not specified, the original rule type is used. Enumeration values:
|
Parameter |
Mandatory |
Type |
Description |
---|---|---|---|
name |
Yes |
String |
Dimension of a resource. For example, the dimension of an ECS can be instance_id. A maximum of four dimensions are supported. For the metric dimension of each resource, see Service metric dimension. Regex Pattern: ^([a-z]|[A-Z]){1}([a-z]|[A-Z]|[0-9]|_|-)*$ |
value |
No |
String |
Value of a resource dimension, which is the resource ID, for example, 4270ff17-aba3-4138-89fa-820594c39755. Regex Pattern: ^((([a-z]|[A-Z]|[0-9]|\*|_|/|#|\(|\)){1}([a-z]|[A-Z]|[0-9]|_|-|\.|\*|/|#|\(|\))*))$ |
Parameter |
Mandatory |
Type |
Description |
---|---|---|---|
metric_name |
Yes |
String |
Metric name of a resource. The name must start with a letter and contain only digits, letters, and underscores. The length ranges from 1 to 64 characters. For example, cpu_util of an ECS indicates the CPU usage of the ECS. mongo001_command_ps in DDS indicates the command execution frequency. For details about the metric name of each service, see Service metric name. |
period |
Yes |
Integer |
Monitoring period of a metric, in seconds. The default value is 0. For an event alarm, set this parameter to 0. 1 indicates the original rollup period of a metric. For example, if the original rollup period of an RDS metric is 60s, its data point is calculated every 60 seconds. For details about the original rollup period of each cloud service metric, see Services Interconnected with Cloud Eye. 300 indicates that the metric rollup period is 5 minutes. Value range: 0-86400 Enumeration values:
|
filter |
Yes |
String |
Aggregation mode. average: average value; variance: variance; min: minimum value; max: maximum value; sum: sum; tp99: 99 percentile; tp95: 95 percentile; tp90: 90 percentile |
comparison_operator |
Yes |
String |
Threshold symbol. The value can be >, <, >=, <=, =, !=, cycle_decrease, cycle_increase, or cycle_wave. cycle_decrease indicates the decrease compared with the last period, cycle_increase indicates the increase compared with the last period, and cycle_wave indicates the increase or decrease compared with the last period. All of them can be used in alarm rules for metrics. >, <, >=, <=, =, and != can be used for alarm rules for events. |
value |
No |
Number |
Alarm threshold If there is only one threshold, value and alarm_level are used in pairs. If there are both hierarchical_value and value, hierarchical_value is used. For detailed thresholds, see the value range of each metric in the appendix. For example, you can set ECS cpu_util to 80. For detailed thresholds, see the value range of each metric in the appendix. For example, you can set ECS cpu_util to 80 in Services Interconnected with Cloud Eye. |
hierarchical_value |
No |
HierarchicalValue object |
Multi-level alarm threshold. If there are both hierarchical_value and value, hierarchical_value prevails. When you create or modify an alarm rule, you can set only one threshold in the following scenarios:
|
unit |
No |
String |
Data unit. |
count |
Yes |
Integer |
Number of consecutive alarm triggering times. For event alarms, the value ranges from 1 to 180. For metric and website alarms, the value can be 1, 2, 3, 4, 5, 10, 15, 30, 60, 90, 120, or 180. |
suppress_duration |
No |
Integer |
Alarm suppression time, in seconds. This parameter corresponds to the last field in the alarm policy when an alarm rule is created on the Cloud Eye console. This field is used to avoid frequent alarms. 0 indicates that the alarm is not suppressed and alarms are generated as long as the conditions are met. 300 indicates that an alarm is generated every 5 minutes as long as the alarm triggering conditions are met. Value range: 0-86400 Enumeration values:
|
level |
No |
Integer |
Alarm severity, which can be 1 (critical), ** 2** (major), 3 (minor), or 4 (informational). The default value is 2. |
namespace |
No |
String |
namespace and dimension_name need to be specified for product-level rules. For details about the namespace of each service, see Service namespace. Regex Pattern: ^((([a-z]|[A-Z]){1}([a-z]|[A-Z]|[0-9]|_)*\.([a-z]|[A-Z]){1}([a-z]|[A-Z]|[0-9]|_)*)|)$ |
dimension_name |
No |
String |
The namespace and dimension_name parameters are added to the product-level rule to specify the policy to which the product belongs. Currently, a maximum of four dimensions are supported. For details about the metric dimension name of each service resource, see [Service dimension name] (ces_03_0059.xml). Example: instance_id in the single-dimension scenario; instance_id,disk in the multi-dimension scenario Regex Pattern: ^(([a-z]|[A-Z]){1}([a-z]|[A-Z]|[0-9]|_|-|\.){0,31}(,([a-z]|[A-Z]){1}([a-z]|[A-Z]|[0-9]|_|-|\.){0,31}){0,3}|)$ |
Parameter |
Mandatory |
Type |
Description |
---|---|---|---|
critical |
No |
Double |
Threshold for critical alarms. Value range: -1.7976931348623156E108-1.7976931348623156E108 |
major |
No |
Double |
Threshold for major alarms. Value range: -1.7976931348623156E108-1.7976931348623156E108 |
minor |
No |
Double |
Threshold for minor alarms. Value range: -1.7976931348623156E108-1.7976931348623156E108 |
info |
No |
Double |
Threshold for informational alarms. Value range: -1.7976931348623156E108-1.7976931348623156E108 |
Parameter |
Mandatory |
Type |
Description |
---|---|---|---|
type |
Yes |
String |
Notification type. The value can be notification (SMN notifications), contact (account contacts), contactGroup (notification groups), or autoscaling (AS notifications). autoscaling is used only in AS and is not recommended. groupwatch, ecsRecovery, and iecAction are no longer used. Enumeration values:
|
notification_list |
Yes |
Array of strings |
List of objects to be notified if the alarm status changes. The value of topicUrn can be obtained from SMN. For details, see section "Querying Topics". If type is set to notification, the value of notificationList cannot be left blank. If type is set to autoscaling, the value of notification_list must be left blank. Note: If alarm_action_enabled is set to true, alarm_actions, ok_actions, or both of them must be specified. If both alarm_actions and ok_actions are specified, their notification_list values must be the same. |
Parameter |
Mandatory |
Type |
Description |
---|---|---|---|
key |
Yes |
String |
Tag key. The value can contain up to 128 Unicode characters. Regex Pattern: ^((?!\s)(?!_sys_)[\p{L}\p{Z}\p{N}_.:=+\-@]*)(?<!\s)$ |
value |
Yes |
String |
Value. Each tag value can contain a maximum of 255 Unicode characters. Regex Pattern: ^([\p{L}\p{Z}\p{N}_.:\/=+\-@]*)$ |
Response Parameters
Status code: 201
Parameter |
Type |
Description |
---|---|---|
alarm_id |
String |
ID of an alarm rule, which starts with al and is followed by 22 characters, including letters and digits. |
Status code: 400
Parameter |
Type |
Description |
---|---|---|
error_code |
String |
Status codes customized by each cloud service when a request error occurs. |
error_msg |
String |
Request error message. |
request_id |
String |
Request ID. |
Status code: 500
Parameter |
Type |
Description |
---|---|---|
error_code |
String |
Status codes customized by each cloud service when a request error occurs. |
error_msg |
String |
Request error message. |
request_id |
String |
Request ID. |
Example Requests
Creating an alarm rule whose name is alarm-lxy-rg-RDS, type is RESOURCE_GROUP, ** suppress_duration** is 86400, and level is 2.
{ "name" : "alarm-lxy-rg-RDS", "description" : "", "namespace" : "SYS.RDS", "type" : "RESOURCE_GROUP", "resources" : [ [ { "name" : "rds_cluster_id" } ] ], "policies" : [ { "metric_name" : "rds001_cpu_util", "period" : 1, "filter" : "average", "comparison_operator" : ">=", "value" : 0, "unit" : "%", "count" : 1, "suppress_duration" : 86400, "level" : 2 } ], "enabled" : true, "notification_enabled" : false, "resource_group_id" : "rg1623429506587NbRweoa3J", "enterprise_project_id" : "a9d919b7-0456-4bb8-b470-6a23b64f4f7e", "alarm_template_id" : "at1628592157541dB1klWgY6" }
Example Responses
Status code: 201
Alarm rule created.
{ "alarm_id" : "alCzk8o9dtSQHtiDgb44Eepw" }
Status Codes
Status Code |
Description |
---|---|
201 |
Alarm rule created. |
400 |
Parameter verification failed. |
500 |
Internal system error. |
Error Codes
See Error Codes.
Feedback
Was this page helpful?
Provide feedbackThank you very much for your feedback. We will continue working to improve the documentation.See the reply and handling status in My Cloud VOC.
For any further questions, feel free to contact us through the chatbot.
Chatbot