Creates an event-triggered task.

Description

CloudMonitor collects monitoring data based on the metrics specified in event-triggered tasks. You must use dimensions to specify the scope for collecting monitoring data. For example, you can specify the user_id and scaling_group dimensions for an event-triggered task to collect monitoring data about all the Elastic Compute Service (ECS) instances in a specific scaling group within a specific account.

The following table describes the dimensions that can be specified for each metric.

Metric

Description

Dimension

CpuUtilization

The CPU utilization. Unit: %.

user_id and scaling_group

ClassicInternetRx

The inbound traffic over the Internet to the classic network. Unit: KB/min.

user_id and scaling_group

ClassicInternetTx

The outbound traffic over the Internet from the classic network. Unit: KB/min.

user_id and scaling_group

VpcInternetRx

The inbound traffic over the Internet to virtual private clouds (VPCs). Unit: KB/min.

user_id and scaling_group

VpcInternetTx

The outbound traffic over the Internet from VPCs. Unit: KB/min.

user_id and scaling_group

IntranetRx

The inbound traffic over the internal network. Unit: KB/min.

user_id and scaling_group

IntranetTx

The outbound traffic over the internal network. Unit: KB/min.

user_id and scaling_group

LoadAverage

The average system load.

user_id and scaling_group

MemoryUtilization

The memory usage. Unit: %.

user_id and scaling_group

SystemDiskReadBps

The number of bytes read from the system disk per second.

user_id and scaling_group

SystemDiskWriteBps

The number of bytes written to the system disk per second.

user_id and scaling_group

SystemDiskReadOps

The number of read operations on the system disk per second.

user_id and scaling_group

SystemDiskWriteOps

The number of write operations on the system disk per second.

user_id and scaling_group

PackagesNetIn

The number of packets that are received by the network interface controller (NIC) per second.

user_id, scaling_group, and device

PackagesNetOut

The number of packets that are sent by the NIC per second.

user_id, scaling_group, and device

TcpConnection

The number of TCP connections.

user_id, scaling_group, and state

The values of user_id and scaling_group are set by the system, but the values of device and state must be manually set. For more information, see the Dimension.N.DimensionKey and Dimension.N.DimensionValue parameters in the "Request parameters" section of this topic.

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.

MetricName String Yes CpuUtilization

The name of the monitroing metric. Valid values:

  • CpuUtilization: the CPU utilization. Unit: %.
  • ClassicInternetRx: the inbound traffic over the Internet to the classic network. Unit: KB/min.
  • ClassicInternetTx: the outbound traffic over the Internet from the classic network. Unit: KB/min.
  • VpcInternetRx: the inbound traffic over the Internet to VPCs. Unit: KB/min.
  • VpcInternetTx: the outbound traffic over the Internet from VPCs. Unit: KB/min.
  • IntranetRx: the inbound traffic over the internal network. Unit: KB/min.
  • IntranetTx: the outbound traffic over the internal network. Unit: KB/min.
  • LoadAverage: the average system load.
  • MemoryUtilization: the memory usage. Unit: %.
  • SystemDiskReadBps: the number of bytes read from the system disk per second.
  • SystemDiskWriteBps: the number of bytes written to the system disk per second.
  • SystemDiskReadOps: the number of read operations on the system disk per second.
  • SystemDiskWriteOps: the number of write operations on the system disk per second.
  • PackagesNetIn: the number of packets that are received by the NIC per second.
  • PackagesNetOut: the number of packets that are sent by the NIC per second.
  • TcpConnection: the number of TCP connections.

For more information, see the "Description" section in this topic.

RegionId String Yes cn-qingdao

The ID of the region in which to create the event-triggered task.

ScalingGroupId String Yes asg-bp18p2yfxow2dloq****

The ID of the scaling group to be monitored by the event-triggered task.

Threshold Float Yes 80

The threshold of the metric. The alert condition of the event-triggered task specifies the relationship between the statistical value and the threshold of the metric. When the alert condition is met for the specified number of times, Auto Scaling triggers an alert and executes the scaling rules specified in the event-triggered task.

Name String No TestAlarmTask

The name of the event-triggered task.

Description String No Test alarm task.

The description of the event-triggered task.

AlarmAction.N RepeatList No ari:acs:ess:cn-hangzhou:1406926****:scalingrule/asr-bp163l21e07uhn****

The unique identifier of scaling rule N to be associated with the event-triggered task.

MetricType String No system

The type of the metric. Valid values:

  • system: the built-in metric of CloudMonitor
  • custom: the custom metric that is used to report relevant data of ECS instances to CloudMonitor.
Period Integer No 300

The period for collecting the statistical value of the metric. Unit: seconds. Valid values:

  • 60
  • 120
  • 300
  • 900

Default value: 300.

Statistics String No Average

The type of the statistical value that is collected for the metric. Valid values:

  • Average: the average value
  • Minimum: the minimum value
  • Maximum: the maximum value

Default value: Average.

ComparisonOperator String No >=

The operator for comparison between the collected metric value and the threshold. This parameter is used to specify the relationship between the metric value and the threshold that meets the alert condition. Valid values:

  • >=: The metric value is greater than or equal to the threshold.
  • <=: The metric value is less than or equal to the threshold.
  • >: The metric value is greater than the threshold.
  • <: The metric value is less than the threshold.

Default value: >=.

EvaluationCount Integer No 3

The number of times that the alert condition must be met to trigger an alert and execute scaling rules. For example, if this parameter is set to 3, an alert is triggered when the average CPU utilization is greater than or equal to 80% for three times.

Default value: 3.

Dimension.N.DimensionKey String No device

The key of dimension N to be associated with a metric. Valid values:

  • user_id: the ID of your account.
  • scaling_group: the scaling group to be monitored
  • device: the type of the NIC
  • state: specifies whether to count the total number of TCP connections or the number of TCP connections that have been established and are available.
Dimension.N.DimensionValue String No eth0

The value of the dimension that is associated with the metric. The value of this parameter depends on the DimensionKey parameter.

user_id: automatically filled by the system.

scaling_group: automatically filled by the system.

Valid values of device:

  • eth0: For instances of the classic network type, eth0 indicates the internal NIC. For each instance of the VPC type, only one eth0 NIC exists.
  • eth1: For instances of the classic network type, eth1 indicates the public NIC.

Valid values of state:

  • TCP_TOTAL: the total number of TCP connections
  • ESTABLISHED: the number of TCP connections that have been established
GroupId Integer No 4055401

The ID of the application group to which the custom metric belongs. This parameter is valid only when the MetricType parameter is set to custom.

Effective String No TZ=+00 * * 1-2 * * ?

Specifies the effective period of the even-triggered task. By default, the event-triggered task is effective all the time.

This parameter follows the cron expression format. The default format is X X X X X ?. The following section describes the meaning of the format:

  • X indicates a placeholder in a field, which represents seconds, minutes, hours, day of month, and months in sequence. X can be a definite value or a special character that has logical meaning. For information about the value range of X, see Cron expression.
  • ? indicates that no value is specified.
Note By default, this parameter value 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 * * ? indicates that the event-triggered task is effective between 01:00 and 02:59 (UTC) every day.

The following section describes the example values and their meanings:

  • * * * * * ? : The event-triggered task is effective all the time.
  • * * 17-18 * * ? : The event-triggered task is effective between 17:00 and 18:59 (UTC+8) every day.
  • TZ=+00 * * 1-2 * * ?: The event-triggered task is effective between 01:00 and 02:59 (UTC) every day.

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

https://ess.aliyuncs.com/?Action=CreateAlarm
&RegionId=cn-qingdao
&ScalingGroupId=asg-bp18p2yfxow2dloq****
&MetricName=CpuUtilization
&Threshold=80
&AlarmAction.1=ari:acs:ess:cn-hangzhou:1406926****:scalingrule/asr-bp163l21e07uhn****
&<Common request parameters>|

Sample success responses

XML format

<CreateAlarmResponse>
    <AlarmTaskId>asg-bp1hvbnmkl10vll5****_f95ce797-dc2e-4bad-9618-14fee7d1****</AlarmTaskId>
    <RequestId>ADD82C07-7A7C-4DD4-907F-1D114742****</RequestId>
</CreateAlarmResponse>

JSON format

{
    "AlarmTaskId":"asg-bp1hvbnmkl10vll5****_f95ce797-dc2e-4bad-9618-14fee7d1****",
    "RequestId":"ADD82C07-7A7C-4DD4-907F-1D114742****"
}

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 specified "%s" parameter is invalid.