CreateAlarm - API Reference| Alibaba Cloud Documentation Center

Description

If you set MetricType to custom, you must report your custom metrics to CloudMonitor before you can create event-triggered tasks by using custom metrics. For more information, see Custom monitoring event-triggered tasks.

When you create an event-triggered task, you must specify the MetricName, Dimension.N.DimensionKey, and Dimension.N.DimensionValue parameters to determine the range of statistics that you want to aggregate for the metrics of the scaling group. For example, you can specify the user_id and scaling_group dimensions for an event-triggered task to aggregate monitoring data of all Elastic Compute Service (ECS) instances in a scaling group within an Alibaba Cloud account. The following table describes the metrics that are available when MetricType is set to system.

Note

The user_id and scaling_group dimensions are automatically populated. You need to only specify the device and state dimensions. For more information, see the Dimension.N.DimensionKey and Dimension.N.DimensionValue parameters in the "Request parameters" section of this topic.
If you set MetricType to custom, the available metrics vary based on your custom metrics.


Collection source	Metric	Description	Dimension	Supported network
ECS instance	CpuUtilization	The CPU utilization. Unit: %.	user_id and scaling_group	Virtual private cloud (VPC) and classic network
ECS instance	IntranetTx	The outbound traffic over the internal network. Unit: KB/min.	user_id and scaling_group	VPC and classic network
ECS instance	IntranetRx	The inbound traffic over the internal network. Unit: KB/min.	user_id and scaling_group	VPC and classic network
ECS instance	VpcInternetTx	The outbound traffic over the Internet from the VPC. Unit: KB/min.	user_id and scaling_group	VPC
ECS instance	VpcInternetRx	The inbound traffic over the Internet to the VPC. Unit: KB/min.	user_id and scaling_group	VPC
ECS instance	ClassicInternetTx	The outbound traffic over the Internet from the classic network. Unit: KB/min.	user_id and scaling_group	Classic network
ECS instance	ClassicInternetRx	The inbound traffic over the Internet to the classic network. Unit: KB/min.	user_id and scaling_group	Classic network
ECS instance	SystemDiskReadBps	The number of bytes read from the system disk per second.	user_id and scaling_group	VPC and classic network
ECS instance	SystemDiskWriteBps	The number of bytes written to the system disk per second.	user_id and scaling_group	VPC and classic network
ECS instance	SystemDiskReadOps	The number of read operations on the system disk per second.	user_id and scaling_group	VPC and classic network
ECS instance	SystemDiskWriteOps	The number of write operations on the system disk per second.	user_id and scaling_group	VPC and classic network
CloudMonitor agent	CpuUtilizationAgent	The CPU utilization. Unit: %.	user_id and scaling_group	VPC and classic network
CloudMonitor agent	GpuUtilizationAgent	The GPU utilization. Unit: %.	user_id and scaling_group	VPC
CloudMonitor agent	GpuMemoryFreeUtilizationAgent	The percentage of idle GPU memory.	user_id and scaling_group	VPC
CloudMonitor agent	GpuMemoryUtilizationAgent	The GPU memory usage. Unit: %.	user_id and scaling_group	VPC
CloudMonitor agent	MemoryUtilization	The memory usage. Unit: %.	user_id and scaling_group	VPC and classic network
CloudMonitor agent	LoadAverage	The average system load.	user_id and scaling_group	VPC and classic network
CloudMonitor agent	TcpConnection	The total number of TCP connections.	user_id, scaling_group, and state	VPC and classic network
CloudMonitor agent	PackagesNetOut	The number of packets that are sent by the network interface controller (NIC).	user_id, scaling_group, and device	VPC and classic network
CloudMonitor agent	PackagesNetIn	The number of packets that are received by the NIC.	user_id, scaling_group, and device	VPC and classic network

Debugging

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer. OpenAPI Explorer dynamically generates the sample code of the operation for different SDKs.

Request parameters


Parameter	Type	Required	Example	Description
Action	String	Yes	CreateAlarm	The operation that you want to perform. Set the value to CreateAlarm.
RegionId	String	Yes	cn-hangzhou	The region ID of the scaling group with which the event-triggered task is associated.
Name	String	No	TestAlarmTask	The name of the event-triggered task.
Description	String	No	Test alarm task.	The description of the event-triggered task.
ScalingGroupId	String	Yes	asg-bp18p2yfxow2dloq****	The ID of the scaling group with which the event-triggered task is associated.
MetricName	String	Yes	CpuUtilization	The name of the metric. The valid values vary based on the metric type. If you set MetricType to custom, the valid values are your custom metrics. If you set MetricType to system, the MetricName parameter has the following valid values: CpuUtilization: (ECS) the CPU utilization. Unit: %. IntranetTx: (ECS) the outbound traffic over the internal network. Unit: KB/min. IntranetRx: (ECS) the inbound traffic over the internal network. Unit: KB/min. VpcInternetTx: (ECS) the outbound traffic over the Internet from the VPC. Unit: KB/min. VpcInternetRx: (ECS) the inbound traffic over the Internet to the VPC. Unit: KB/min. ClassicInternetTx: (ECS) the outbound traffic over the Internet from the classic network. Unit: KB/min. ClassicInternetRx: (ECS) the inbound traffic over the Internet to the classic network. Unit: KB/min. SystemDiskReadBps: (ECS) the number of bytes read from the system disk per second. SystemDiskWriteBps: (ECS) the number of bytes written to the system disk per second. SystemDiskReadOps: (ECS) the number of read operations on the system disk per second. SystemDiskWriteOps: (ECS) the number of write operations on the system disk per second. CpuUtilizationAgent: (Agent) the CPU utilization. Unit: %. GpuUtilizationAgent: (Agent) the GPU utilization. Unit: %. GpuMemoryFreeUtilizationAgent: (Agent) the percentage of idle GPU memory. GpuMemoryUtilizationAgent: (Agent) the GPU memory usage. Unit: %. MemoryUtilization: (Agent) the memory usage. Unit: %. LoadAverage: (Agent) the average system load. TcpConnection: (Agent) the total number of TCP connections. PackagesNetOut: (Agent) the number of packets that are sent by the NIC. PackagesNetIn: (Agent) the number of packets that are received by the NIC. For more information, see the Description in this topic.
MetricType	String	No	system	The type of the metric. Valid values: system: system metrics of CloudMonitor custom: custom metrics that are reported to CloudMonitor
Period	Integer	No	300	The period during which the statistical value of the metric is collected. Unit: seconds. Valid values: 15 60 120 300 900 Note The statistical period of 15 seconds can be applied only to the `CpuUtilizationAgent` metric. For other metrics, we recommend that you set the Period parameter to 60, 120, 300, or 900. Default value: 300.
Statistics	String	No	Average	The method that is used to aggregate statistics for the metric. Valid values: Average Minimum Maximum Default value: Average.
Threshold	Float	Yes	80	The threshold of the metric value. If the threshold is reached N times, a scaling rule is triggered.
ComparisonOperator	String	No	>=	The operator that is used to compare the metric value and the threshold. Valid value if the metric value is greater than or equal to the threshold: >= Valid value if the metric value is less than or equal to the threshold: <= Valid value if the metric value is greater than the threshold: > Valid value if the metric value is less than the threshold: < Default value: >=.
EvaluationCount	Integer	No	3	The number of times that the threshold must be reached to trigger a scaling rule. For example, if you set this parameter to 3, the average CPU utilization must reach 80% three times to trigger a scaling rule. Default value: 3.
GroupId	Integer	No	4055401	The ID of the application group to which the custom metric belongs. This parameter is required only if you set MetricType to custom.
Effective	String	No	TZ=+00 * * 1-2 * * ?	The effective period of the event-triggered task. By default, the event-triggered task is in effect all the time. This parameter follows the cron expression format. The default format is `X X X X X ?`. In the format: X: a placeholder for a field, which represents seconds, minutes, hours, days, and months in sequence. X can be a definite value or a special character that has logical meaning. For information about the valid values of X, see Cron expression. ?: No value is specified. Note By default, the value of this parameter is specified in UTC+8. You can specify the time zone before a cron expression in the `TZ=+yy` format. y indicates the time zone. For example, `TZ=+00 * * 1-2 * * ?` specifies that the event-triggered task is in effect between 01:00 and 02:59 (UTC+0) every day. Sample values: `* * * * * ?` : The event-triggered task is in effect all the time. `* * 17-18 * * ?` : The event-triggered task is in effect between 17:00 and 18:59 (UTC+8) every day. `TZ=+00 * * 1-2 * * ?`: The event-triggered task is in effect between 01:00 and 02:59 (UTC+0) every day.
AlarmAction.N	String	No	ari:acs:ess:cn-hangzhou:1406926**:scalingrule/asr-bp163l21e07uhn**	The unique identifier of scaling rule N that is associated with the event-triggered task.
Dimension.N.DimensionKey	String	No	device	The key of dimension N that is associated with the metric. The valid values vary based on the metric type. If you set MetricType to custom, you can specify this parameter based on your business requirements. If you set MetricType to system, the following values are valid: user_id: the ID of your Alibaba Cloud account scaling_group: the scaling group that you want to monitor device: the type of the NIC state: the status of the TCP connection
Dimension.N.DimensionValue	String	No	eth0	The value of dimension N that is associated with the metric. The valid values vary based on the value of Dimension.N.DimensionKey. If you set Dimension.N.DimensionKey to a custom value, you can specify this parameter based on your business requirements. If the value of Dimension.N.DimensionKey is specified by the system, the following values are valid: user_id: The system specifies the value. scaling_group: The system specifies the value. device: You can set this parameter to eth0 or eth1. For instances of the classic network type, eth0 specifies the internal NIC. Only one eth0 NIC exists on each instance of the VPC type. For instances of the classic network type, eth1 specifies the public NIC. state: You can set this parameter to TCP_TOTAL or ESTABLISHED. TCP_TOTAL specifies the total number of TCP connections. ESTABLISHED specifies the number of TCP connections that are established.

Response parameters


Parameter	Type	Example	Description
AlarmTaskId	String	asg-bp1hvbnmkl10vll5**_f95ce797-dc2e-4bad-9618-14fee7d1**	The ID of the event-triggered task.
RequestId	String	473469C7-AA6F-4DC5-B3DB-A3DC0DE3****	The ID of the request.

Examples

Sample requests

http(s)://ess.aliyuncs.com/?Action=CreateAlarm
&RegionId=cn-hangzhou
&Name=TestAlarmTask
&Description=Test alarm task.
&ScalingGroupId=asg-bp18p2yfxow2dloq****
&MetricName=CpuUtilization
&MetricType=system
&Period=300
&Statistics=Average
&Threshold=80.0
&ComparisonOperator=>=
&EvaluationCount=3
&GroupId=4055401
&Effective=TZ=+00 * * 1-2 * * ?
&AlarmAction=["ari:acs:ess:cn-hangzhou:1406926****:scalingrule/asr-bp163l21e07uhn****"]
&Dimension=[{"DimensionKey":"device","DimensionValue":"eth0"}]
&<Common request parameters>

Sample success responses

XML format

HTTP/1.1 200 OK
Content-Type:application/xml

<CreateAlarmResponse>
    <AlarmTaskId>asg-bp1hvbnmkl10vll5****_f95ce797-dc2e-4bad-9618-14fee7d1****</AlarmTaskId>
    <RequestId>473469C7-AA6F-4DC5-B3DB-A3DC0DE3****</RequestId>
</CreateAlarmResponse>

JSON format

HTTP/1.1 200 OK
Content-Type:application/json

{
  "AlarmTaskId" : "asg-bp1hvbnmkl10vll5****_f95ce797-dc2e-4bad-9618-14fee7d1****",
  "RequestId" : "473469C7-AA6F-4DC5-B3DB-A3DC0DE3****"
}

Error codes

For a list of error codes, visit the API Error Center.


HTTP status code	Error code	Error message	Description
404	InvalidParameter	The specified value of parameter "%s" is not valid.	The error message returned because the value that you specified for the "%s" parameter is invalid.