doc-exports/docs/ces/api-ref/CreateAlarmRules.html

Creating an Alarm Rule (Recommended)

Function

This API is used to create an alarm rule (recommended).

URI

POST /v2/{project_id}/alarms

Table 1 Path parameters

Parameter	Mandatory	Type	Description
project_id	Yes	String	Project ID. For details about how to obtain the project ID, see Obtaining a Project ID. Minimum: 1 Maximum: 64 Regular expression matching: ^[a-zA-Z0-9-]{1,64}$

Request Parameters

Table 2 Request header parameters

Parameter	Mandatory	Type	Description
Content-Type	Yes	String	MIME type of the request body. Default: application/json; charset=UTF-8 Minimum: 1 Maximum: 64
X-Auth-Token	No	String	User token. It is a response to the API for obtaining a user token. This API is the only one that does not require authentication. After a response is returned, the value of X-Subject-Token in the response header is the token. Minimum: 1 Maximum: 16384

Table 3 Request body parameters

Parameter	Mandatory	Type	Description
name	Yes	String	Name of an alarm rule. The name allows 1 to 128 characters and can only contain letters, digits, underscores (_), and hyphens (-).
description	No	String	Alarm rule description. The value can contain 0 to 256 characters.
namespace	Yes	String	Namespace of a service. For details about the namespace of each service, see Service Namespaces. The namespace must be in the service.item format and contain 3 to 32 characters. The values of service and item must start with a letter and can only contain letters, digits, and underscores (_). Minimum: 3 Maximum: 32
resource_group_id	No	String	Resource group ID. This parameter is mandatory when the monitoring scope is set to Resource groups.
resources	Yes	Array of arrays of Dimension objects	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. Array length: 0 to 1000
policies	No	Array of Policy objects	Alarm policies. Array length: 1 to 50 NOTE: Either policies or alarm_template_id must be set. If both are specified, the policy in the alarm template is used.
type	Yes	String	Alarm rule type. The value can be: ALL_INSTANCE: alarms for all resources RESOURCE_GROUP: alarms for resource groups MULTI_INSTANCE: alarms for specified resources EVENT.SYS: system event alarms EVENT.CUSTOM: custom event alarms
alarm_notifications	No	Array of Notification objects	Action to be triggered by the alarm. Array length: 0 to 10
ok_notifications	No	Array of Notification objects	Action to be triggered after an alarm is cleared. Array length: 0 to 10
notification_begin_time	No	String	Time when the alarm notification was enabled. Example: 12:00 Regular expression matching: ^([01][0-9]|2[0-3]):([0-5][0-9])$
notification_end_time	No	String	Time when the alarm notification was disabled. Example: 12:00 Regular expression matching: ^([1][0-9]|2[0-3]):([0-5][0-9])$
enterprise_project_id	No	String	Enterprise project ID. The value allows 36 characters. It can only contain lowercase letters, hyphens (-), and underscores (_). You can customize an enterprise project ID. The value can also be 0 (default enterprise project ID). Regular expression matching: ^((([a-z]|[0-9]){8}-([a-z]|[0-9]){4}-([a-z]|[0-9]){4}-([a-z]|[0-9]){4}-([a-z]|[0-9]){12})|0)$
enabled	Yes	Boolean	Whether to generate alarms when the alarm triggering conditions are met.
notification_enabled	Yes	Boolean	Whether to enable alarm notification.
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. Minimum: 0 Maximum: 64 Regular expression matching: ^at([0-9A-Za-z]){0,62}$ NOTE: Either policies or alarm_template_id must be set. If both are specified, the policy in the alarm template is used.
tags	No	Array of ResourceTag objects	Tenant tags. Array length: 0 to 20

Table 4 Dimension

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 Dimensions. Regular expression matching: ^([a-z]|[A-Z]){1}([a-z]|[A-Z]|[0-9]|_|-){1,32}$
value	No	String	Resource dimension value, which is an instance ID, for example, 4270ff17-aba3-4138-89fa-820594c39755. Regular expression matching: ^((([a-z]|[A-Z]|[0-9]){1}([a-z]|[A-Z]|[0-9]|_|-|\.)*)|\*){1,256}$

Table 5 Policy

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 Names. Regular expression matching: ^([A-Za-z]){1}([0-9A-Za-z]|_|-)*$
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 aggregation period of a metric. For example, if the original aggregation period of an RDS metric is 60s, its data point is calculated every 60 seconds. For details about the original aggregation period of each cloud service metric, see Services Interconnected with Cloud Eye. 300 indicates that the metric aggregation period is 5 minutes. Minimum: 0 Maximum: 86400 The value can be: 0 1 300 1200 3600 14400 86400
filter	Yes	String	Data aggregation method. The value can be: average: average value of metric data within an aggregation period. max: maximum value of metric data within an aggregation period. min: minimum value of metric data within an aggregation period. sum: sum of metric data within an aggregation period. variance: variance value of metric data within an aggregation period.
comparison_operator	Yes	String	Operator of an alarm threshold. Regular expression matching: ^(>|<|>=|<=|=|!=)$
value	No	Number	Alarm threshold. Supported range: 0 to Number.MAX_VALUE (1.7976931348623157e+108) For detailed thresholds, see the value range of each metric in the appendix. For example, you can set ECS cpu_util to 80. Minimum: 0 Maximum: 1.7976931348623157e+108
unit	No	String	Data unit. The value can contain a maximum of 32 characters. You can set this parameter based on your service needs. Minimum: 0 Maximum: 32
count	Yes	Integer	Number of times that the alarm triggering conditions are met. 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. Minimum: 0 Maximum: 86400 The value can be: 0 300 600 900 1800 3600 10800 21600 43200 86400
level	No	Integer	Alarm severity, which can be 1 (critical), 2 (major), 3 (minor), or 4 (informational). The default value is 2.

Table 6 Notification

Parameter	Mandatory	Type	Description
type	Yes	String	Notification type. The value can be: notification: topic subscriptions. Notifications are sent using SMN topics. contact: cloud account contact. Notifications are sent to the mobile number and email address registered for your account.
notification_list	Yes	Array of strings	List of objects to be notified of alarm status changes. The value of topicUrn can be obtained from SMN. For details, see section "Querying Topics." When type is set to notification, notification_list cannot be left blank. If you set alarm_action_enabled to true, you must specify either alarm_actions or ok_actions. If alarm_actions and ok_actions coexist, their notification_list must be the same. Array length: 0 to 20

Table 7 ResourceTag

Parameter	Mandatory	Type	Description
key	Yes	String	Tag key. A tag key can contain a maximum of 128 Unicode characters. Minimum: 1 Maximum: 128 Regular expression matching: ^((?!\s)(?!_sys_)[\p{L}\p{Z}\p{N}_.:=+\-@]*)(?<!\s)$
value	Yes	String	Tag value. Each tag value can contain a maximum of 255 Unicode characters. Minimum: 0 Maximum: 255 Regular expression matching: ^([\p{L}\p{Z}\p{N}_.:\/=+\-@]*)$

Response Parameters

Status code: 201

Table 8 Response body parameters

Parameter	Type	Description
alarm_id	String	ID of an alarm rule, which starts with al and is followed by 22 characters of letters, digits, or a combination of both.

Status code: 400

Table 9 Response body parameters

Parameter	Type	Description
error_code	String	Status code customized by each cloud service when a request error occurs. Minimum: 0 Maximum: 256
error_msg	String	Request error message. Minimum: 0 Maximum: 256
request_id	String	Request ID. Minimum: 0 Maximum: 256

Status code: 500

Table 10 Response body parameters

Parameter	Type	Description
error_code	String	Status code customized by each cloud service when a request error occurs. Minimum: 0 Maximum: 256
error_msg	String	Request error message. Minimum: 0 Maximum: 256
request_id	String	Request ID. Minimum: 0 Maximum: 256

Example Requests

Create 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",
    "value" : "rdsxxx"
  } ] ],
  "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"
}

Create an alarm rule whose name is alarm-event-tes-05, type is EVENT.SYS, suppress_duration is 0, and level is 2.

{
  "name" : "alarm-event-test-05",
  "namespace" : "SYS.ECS",
  "resources" : [ [ {
    "name" : "resource_id",
    "value" : "2ffxxx"
  } ] ],
  "policies" : [ {
    "metric_name" : "instance_resize_executing",
    "period" : 0,
    "filter" : "average",
    "comparison_operator" : ">=",
    "unit" : "count",
    "count" : 1,
    "suppress_duration" : 0,
    "level" : 2
  } ],
  "type" : "EVENT.SYS",
  "enabled" : true,
  "notification_enabled" : false
}

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	Failed to complete the request because of an internal server error.

Error Codes

See Error Codes.

Parent topic: Alarm Rules