Creates an event-triggered task.

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.