Help Center/ Cloud Eye/ API Reference/ API/ Alarms/ Alarm Rules/ Creating an Alarm Rule (V1)
Updated on 2026-06-11 GMT+08:00
View PDF
Share

Creating an Alarm Rule (V1)

Function

This API is used to create an alarm rule. For API V1, only an alarm rule can be configured for a single resource. You are advised to use Creating Alarm Rules (Recommended) to work with the console.

Debugging

You can debug this API through automatic authentication in API Explorer or use the SDK sample code generated by API Explorer.

Authorization Information

Each account has all the permissions required to call all APIs, but IAM users must be assigned the required permissions.

  • If you are using role/policy-based authorization, see Permissions Policies and Supported Actions for details on the required permissions.
  • If you are using identity policy-based authorization, the following identity policy-based permissions are required.

    Action

    Access Level

    Resource Type (*: required)

    Condition Key

    Alias

    Dependencies

    ces:alarms:create

    Write

    -

    • g:EnterpriseProjectId

    • g:RequestTag/<tag-key>

    • g:TagKeys

    • ces:namespace

    -

    -

URI

POST /V1.0/{project_id}/alarms

Table 1 Path Parameters

Parameter

Mandatory

Type

Description

project_id

Yes

String

Definition

Project ID. It is 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 from the API or console. For details, see Obtaining a Project ID.

Constraints

N/A

Range

1 to 64 characters.

Default Value

N/A

Request Parameters

Table 2 Request header parameters

Parameter

Mandatory

Type

Description

Content-Type

No

String

Definition

MIME type of the request body.

Constraints

N/A

Range

1 to 64 characters

Default Value

Default value application/json; charset=UTF-8 is recommended. For APIs used to upload objects or images, the MIME type varies with the flow type.

X-Auth-Token

No

String

Definition

User token.

Constraints

N/A

Range

1 to 16,384 characters

Default Value

N/A
Table 3 Request body parameters

Parameter

Mandatory

Type

Description

alarm_name

Yes

String

Definition

Alarm name.

Constraints

N/A

Range

The value allows 1 to 128 characters and can only contain digits, letters, underscores (_), and hyphens (-).

Default Value

N/A

alarm_description

No

String

Definition

Alarm description.

Constraints

N/A

Range

[0,256]

Default Value

N/A

metric

Yes

CreateAlarmMetric object

Definition

Metric information in the created rule.

Constraints

N/A

condition

Yes

Condition object

Definition

Alarm policy configured in the alarm rule.

Constraints

N/A

alarm_enabled

No

Boolean

Definition

Whether to enable the alarm rule.

Constraints

N/A

Range

A boolean value, which can be:

  • true: enable

  • false: disable

Default Value

true

alarm_action_enabled

No

Boolean

Definition

Whether to enable alarm notifications when the alarm is triggered.

Constraints

If this parameter is left blank, the default value true is used. In this case, 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.

Range

A boolean value.

  • true: enabled.

  • false: disabled.

Default Value

true

alarm_level

No

Integer

Definition

Alarm severity.

Constraints

N/A

Range

The value can only be 1 (critical), 2 (major), 3 (minor), or 4 (warning).

Default Value

2

alarm_type

No

String

Definition

Alarm type.

Constraints

For event alarms, the alarm type is EVENT.SYS (system events) or EVENT.CUSTOM (custom events).

For alarms generated for resource groups, the alarm type is RESOURCE_GROUP.

For alarms generated for specific resources, the alarm type is MULTI_INSTANCE.

Range

  • EVENT.SYS: The alarm rule is created for system events.

  • EVENT.CUSTOM: The alarm rule is created for custom events.

  • RESOURCE_GROUP: The alarm rule is created for resource groups.

  • MULTI_INSTANCE: The alarm rule is created for specific resources.

Default Value

N/A

alarm_actions

No

Array of Notification objects

Definition

Information about the notification group or topic subscription when the alarm is triggered. A structure example is as follows: { "type": "notification","notificationList":["urn:smn:southchina:68438a86d98e427e907e0097b7e35d47:sd"] }

Constraints

A maximum of 10 recipients are allowed.

insufficientdata_actions

No

Array of Notification objects

Definition

Notification group or topic subscription when an alarm notification is triggered due to insufficient data. (This parameter has been deprecated and does not need to be configured.)

Constraints

A maximum of 10 alarm actions can be configured.

ok_actions

No

Array of Notification objects

Definition

Information about the notification group or topic subscription when the alarm is cleared. A structure example is as follows: { "type": "notification","notificationList":["urn:smn:southchina:68438a86d98e427e907e0097b7e35d47:sd"] }

Constraints

A maximum of 10 recipients are allowed.

enterprise_project_id

No

String

Definition

Enterprise project ID. For details about how to query the enterprise project ID, see Obtaining a Project ID.

Constraints

N/A

Range

0 or 32 characters.

Default Value

0 (default enterprise project)

alarm_action_begin_time

No

String

Definition

Time when alarm notifications were enabled.

Constraints

N/A

Range

The value allows 1 to 64 characters and can only contain digits and colons (:).

Default Value

N/A

alarm_action_end_time

No

String

Definition

Time when alarm notifications were disabled.

Constraints

N/A

Range

The value allows 1 to 64 characters and can only contain digits and colons (:).

Default Value

N/A
Table 4 CreateAlarmMetric

Parameter

Mandatory

Type

Description

namespace

Yes

String

Definition

Metric namespace. For example, the ECS namespace is SYS.ECS , and the DDS namespace is SYS.DDS . For details, see Services Interconnected with Cloud Eye.

Constraints

When alarm_typeis set to EVENT.SYS or EVENT.CUSTOM, you can leave this parameter empty.

Range

The value is in the service.item format and allows 3 to 32 characters. The values of service and item must start with a letter and contain only letters, digits, and underscores (_).

Default Value

N/A

metric_name

Yes

String

Definition

Metric name of the resource. For example, the ECS metric cpu_util indicates the CPU usage of an ECS. The DDS metric mongo001_command_ps indicates the command execution frequency. For details about the metric names of each service, see their documentation. You can navigate there from Services Interconnected with Cloud Eye.

Constraints

N/A

Range

The value must start with a letter and allow 1 to 96 characters. It can only contain letters, digits, and underscores (_).

Default Value

N/A

dimensions

No

Array of CreateMetricDimension objects

Definition

Metric dimension.

Constraints

A maximum of four dimensions can be added. If resource_group_id is not required, dimensions is mandatory.

resource_group_id

No

String

Definition

ID of the resource group selected during the alarm rule creation.

Constraints

If you create alarm rules for resource groups, you must specify resource_group_id and name, enter at least one dimension for dimensions, and set alarm_type to RESOURCE_GROUP, for example, rg1603786526428bWbVmk4rP.

Range

The value allows 0 to 64 characters and can only contain letters, digits, underscores (_), and hyphens (-).

Default Value

N/A
Table 5 CreateMetricDimension

Parameter

Mandatory

Type

Description

name

Yes

String

Definition

Monitoring dimension name. For example, the dimension of an ECS is instance_id . For details about the dimension names of each resource, see their service documentation. You can navigate there from Services Interconnected with Cloud Eye.

Constraints

N/A

Range

The value must start with a letter and can only contain letters, digits, underscores (_), and hyphens (-). 1 to 32 characters.

Default Value

N/A

value

No

String

Definition

Mandatory. Monitoring dimension value, for example, the ECS ID.

Constraints

N/A

Range

0 to 256 characters.

Default Value

N/A
Table 6 Condition

Parameter

Mandatory

Type

Description

comparison_operator

Yes

String

Definition

Threshold symbol.

Constraints

The threshold symbols for metric alarms are >, >=, <, <=, =, !=, cycle_decrease, cycle_increase, and cycle_wave. The threshold symbols for event alarms are >, >=, <, <=, =, and !=.

Range

The value can be >, <, >=, <=, =, !=, cycle_decrease, cycle_increase, or cycle_wave. cycle_decrease indicates the decrease relative to the last period. cycle_increase indicates the increase relative to the last period. cycle_wave indicates the increase or decrease relative to the last period.

count

Yes

Integer

Definition

Number of consecutive times that an alarm is triggered.

Constraints

N/A

Range

An integer ranging from 1 to 5.

Default Value

N/A

filter

Yes

String

Definition

Data aggregation method.

Constraints

When period is set to 1 (original value), the filter field does not take effect. The default value of filter is average. The filter parameter takes effect only when period is greater than 1.

Range

The value can be:

  • average

  • variance

  • min: minimum value.

  • max: maximum value.

  • sum

Default Value

N/A

period

Yes

Integer

Definition

Metric period, in seconds. For details about the original metric period for each cloud service, see Services Interconnected with Cloud Eye.

ConstraintsThe value can be:

  • 0: The alarm is triggered immediately. This value applies only to event scenarios.

  • 1: original metric period. For example, if the original period of an RDS metric is 60s, the metric data is collected and calculated every 60s.

  • 300: The metric data is collected and calculated every 5 minutes.

  • 1200: The metric data is collected and calculated every 20 minutes.

  • 3600: The metric data is collected and calculated every hour.

  • 14400: The metric data is collected and calculated every 4 hours.

  • 86400: The metric data is collected and calculated every day.

Default Value

N/A

Range

N/A

unit

No

String

Definition

Data unit.

Constraints

N/A

Range

0 to 32 characters

Default Value

N/A

value

Yes

Number

Definition

Alarm threshold. For detailed thresholds, see the value range of each metric in the appendix. For example, you can set ECS cpu_util in Services Interconnected with Cloud Eye to 80 .

Constraints

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.

Range

-1.7976931348623157e+108 to 1.7976931348623157e+108

Default Value

N/A

suppress_duration

No

Integer

Definition

Alarm suppression duration, in seconds. This parameter corresponds to the last field in the alarm policy when you create an alarm rule. This field is used to mitigate frequent alarm occurrences.

Constraints

N/A

Range

The value can be:

  • 0: A metric alarm is generated only once. An event alarm is not suppressed in the immediate triggering scenario, and is generated only once in the accumulated triggering scenario.

  • 300: An alarm is generated every 5 minutes once the alarm triggering condition is met.

  • 600: An alarm is generated every 10 minutes once the alarm triggering condition is met.

  • 900: An alarm is generated every 15 minutes once the alarm triggering condition is met.

  • 1800: An alarm is generated every 30 minutes once the alarm triggering condition is met.

  • 3600: An alarm is generated every 60 minutes once the alarm triggering condition is met.

  • 10800: An alarm is generated every 3 hours once the alarm triggering condition is met.

  • 21600: An alarm is generated every 6 hours once the alarm triggering condition is met.

  • 43200: An alarm is generated every 12 hours once the alarm triggering condition is met.

  • 86400: An alarm is generated once every day once the alarm triggering condition is met.

Default Value

N/A
Table 7 Notification

Parameter

Mandatory

Type

Description

type

Yes

String

Definition

Alarm notification type.

Constraints

N/A

Range

The value can be:

  • notification: notification groups or topic subscriptions.

  • autoscaling: AS notifications. This value is used only for AS.

Default Value

N/A

notificationList

Yes

Array of strings

Definition

Recipients to be notified of the alarm status changes.

Constraints

A maximum of 20 recipients can be configured.

The value of topicUrn can be obtained from SMN. For details, see section "Querying Topics."

Note: If alarm_action_enabled is set to true, alarm_actions, ok_actions, or both of them must be specified. If alarm_actions and ok_actions coexist, their notificationList values must be the same.

Response Parameters

Status code: 201

Table 8 Response body parameters

Parameter

Type

Description

alarm_id

String

Alarm rule ID.

Status code: 400

Table 9 Response body parameters

Parameter

Type

Description

-

String

Request error.

Status code: 401

Table 10 Response body parameters

Parameter

Type

Description

-

String

The authentication information is not provided or is incorrect.

Status code: 403

Table 11 Response body parameters

Parameter

Type

Description

-

String

Access to the requested page is forbidden.

Status code: 408

Table 12 Response body parameters

Parameter

Type

Description

-

String

The request timed out.

Status code: 429

Table 13 Response body parameters

Parameter

Type

Description

-

String

Too many requests.

Status code: 500

Table 14 Response body parameters

Parameter

Type

Description

-

String

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

Status code: 503

Table 15 Response body parameters

Parameter

Type

Description

-

String

The system is currently unavailable.

Example Requests

{
  "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:southchina:68438a86d98e427e907e0097b7e35d48:sd" ]
  } ],
  "ok_actions" : [ {
    "type" : "notification",
    "notificationList" : [ "urn:smn:southchina:68438a86d98e427e907e0097b7e35d48:sd" ]
  } ],
  "insufficientdata_actions" : [ {
    "type" : "notification",
    "notificationList" : [ "urn:smn:southchina:68438a86d98e427e907e0097b7e35d48:sd" ]
  } ]
}

Example Responses

Status code: 201

Created

{
  "alarm_id" : "al1604473956229Ym1m1Wx6e"
}

Status Codes

Status Code

Description

201

Created

400

Bad Request

401

Unauthorized

403

Forbidden

408

Request Timeout

429

Too Many Requests

500

Internal Server Error

503

Service Unavailable

Error Codes

See Error Codes.

Parent topic: Alarm Rules