Creates an event-triggered task.

Description

  • If you set the MetricType parameter 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.
    • If you set the MetricType parameter to custom, the valid values are your custom metrics.
    • For information about the metrics that are supported if you set the MetricType parameter to system, see Event-triggered task for system monitoring.
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.

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.

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.

MetricName String No CpuUtilization

The name of the metric. The valid values vary based on the metric type.

  • If you set the MetricType parameter to custom, the valid values are your custom metrics.
  • If you set the MetricType parameter to system, the MetricName parameter has the following valid values:
    • CpuUtilization: the CPU utilization of an ECS instance. Unit: %.
    • IntranetTx: the outbound traffic over the internal network from an ECS instance. Unit: KB/min.
    • IntranetRx: the inbound traffic over the internal network to an ECS instance. Unit: KB/min.
    • VpcInternetTx: the outbound traffic over the Internet from an ECS instance that resides in a virtual private cloud (VPC). Unit: KB/min.
    • VpcInternetRx: the inbound traffic over the Internet to an ECS instance that resides in a VPC. Unit: KB/min.
    • SystemDiskReadBps: the number of bytes read from the system disk used by an ECS instance per second.
    • SystemDiskWriteBps: the number of bytes written to the system disk used by an ECS instance per second.
    • SystemDiskReadOps: the number of read operations on the system disk used by an ECS instance per second.
    • SystemDiskWriteOps: the number of write operations on the system disk used by an ECS instance per second.
    • CpuUtilizationAgent: the CPU utilization of an agent. Unit: %.
    • GpuUtilizationAgent: the GPU utilization of an agent. Unit: %.
    • GpuMemoryFreeUtilizationAgent: the percentage of idle GPU memory of an agent.
    • GpuMemoryUtilizationAgent: the GPU memory usage of an agent. Unit: %.
    • MemoryUtilization: the memory usage of an agent. Unit: %.
    • LoadAverage: the average system load of an agent.
    • TcpConnection: the total number of TCP connections of an agent.
    • TcpConnection: the number of established TCP connections of an agent.
    • PackagesNetOut: the number of packets that are sent by the internal network interface controller (NIC) used by an agent.
    • PackagesNetIn: the number of packets that are received by the internal NIC used by an agent.
    • EciPodCpuUtilization: the CPU utilization of an elastic container instance. Unit: %.
    • EciPodMemoryUtilization: the memory usage of an elastic container instance. Unit: %.

For more information, see Event-triggered task for system monitoring.

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 If your scaling group is of the ECS type and the event-triggered task associated with your scaling group monitors CloudMonitor metrics, you can set the Period parameter to 15. Otherwise, you can set the Period parameter to 60, 120, 300, or 900. In most cases, the name of a CloudMonitor metric contains Agent.

Default value: 300.

Statistics String No Average

The method that is used to aggregate statistics about the metric. Valid values:

  • Average
  • Minimum
  • Maximum

Default value: Average.

Threshold Float No 80.0

The threshold of the metric value. If the threshold is reached N times within the specified period, a scaling rule is executed.

ComparisonOperator String No >=

The operator that is used to compare the metric value and the threshold.

  • If the metric value is greater than or equal to the threshold, set the value to >=.
  • If the metric value is less than or equal to the threshold, set the value to <=.
  • If the metric value is greater than the threshold, set the value to >.
  • If the metric value is less than the threshold, set the value to <.

Default value: >=.

EvaluationCount Integer No 3

The number of times that the threshold must be reached before a scaling rule can be executed. For example, if you set this parameter to 3, the average CPU utilization must reach or exceed 80% three times in a row before a scaling rule is triggered.

Default value: 3.

GroupId Integer No 4055401

The ID of the application group to which the custom metric belongs. If you set the MetricType parameter to custom, you must specify this parameter.

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 which:

  • 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 the MetricType parameter to custom, you can specify this parameter based on your business requirements.
  • If you set the MetricType parameter to system, this parameter has the following valid values:
    • 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 the Dimension.N.DimensionKey parameter.

  • If you set the Dimension.N.DimensionKey parameter to a custom value, you can specify this parameter based on your business requirements.
  • If the value of the Dimension.N.DimensionKey parameter is specified by the system, this parameter has the following valid values:
    • 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 that resides in a VPC.
      • For instances that reside in 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 established TCP connections.
Expression.N.MetricName String No CpuUtilization

The names of the metrics that are specified in the multi-metric alert rule. The valid values vary based on the metric type.

  • If you set the MetricType parameter to custom, the valid values are your custom metrics.
  • If you set the MetricType parameter to system, this parameter has the following valid values:
    • CpuUtilization: the CPU utilization of an ECS instance. Unit: %.
    • IntranetTx: the outbound traffic over the internal network from an ECS instance. Unit: KB/min.
    • IntranetRx: the inbound traffic over the internal network to an ECS instance. Unit: KB/min.
    • VpcInternetTx: the outbound traffic over the Internet from an ECS instance that resides in a virtual private cloud (VPC). Unit: KB/min.
    • VpcInternetRx: the inbound traffic over the Internet to an ECS instance that resides in a VPC. Unit: KB/min.
    • SystemDiskReadBps: the number of bytes read from the system disk used by an ECS instance per second.
    • SystemDiskWriteBps: the number of bytes written to the system disk used by an ECS instance per second.
    • SystemDiskReadOps: the number of read operations on the system disk used by an ECS instance per second.
    • SystemDiskWriteOps: the number of write operations on the system disk used by an ECS instance per second.
    • CpuUtilizationAgent: the CPU utilization of an agent. Unit: %.
    • GpuUtilizationAgent: the GPU utilization of an agent. Unit: %.
    • GpuMemoryFreeUtilizationAgent: the percentage of idle GPU memory of an agent.
    • GpuMemoryUtilizationAgent: the GPU memory usage of an agent. Unit: %.
    • MemoryUtilization: the memory usage of an agent. Unit: %.
    • LoadAverage: the average system load of an agent.
    • TcpConnection: the total number of TCP connections of an agent.
    • TcpConnection: the number of established TCP connections of an agent.
    • PackagesNetOut: the number of packets that are sent by the internal NIC used by an agent.
    • PackagesNetIn: the number of packets that are received by the internal NIC used by an agent.
    • EciPodCpuUtilization: the CPU utilization of an elastic container instance. Unit: %.
    • EciPodMemoryUtilization: the memory usage of an elastic container instance. Unit: %.

For more information, see Event-triggered task for system monitoring.

Expression.N.ComparisonOperator String No >=

The operator that is used to compare the metric value and the threshold.

  • If the metric value is greater than or equal to the threshold, set the value to >=.
  • If the metric value is less than or equal to the threshold, set the value to <=.
  • If the metric value is greater than the threshold, set the value to >.
  • If the metric value is less than the threshold, set the value to <.

Default value: >=.

Expression.N.Period Integer No 900

The period during which the statistical values of the metrics that are specified in the multi-metric alert rule are collected. Unit: seconds. Valid values:

  • 15
  • 60
  • 120
  • 300
  • 900
Note If your scaling group is of the ECS type and uses CloudMonitor metrics, you can set the Period parameter to 15. Otherwise, you can set the Period parameter to 60, 120, 300, or 900. In most cases, the name of a CloudMonitor metric contains Agent.

Default value: 300.

Expression.N.Statistics String No Average

The method that is used to aggregate statistics about the metrics that are specified in the multi-metric alert rule. Valid values:

  • Average
  • Minimum
  • Maximum

Default value: Average.

Expression.N.Threshold Float No 40.0

The thresholds of the metric values. If the thresholds are reached N times within the specified period, a scaling rule is executed.

ExpressionsLogicOperator String No &&

The relationship between the trigger conditions in the multi-metric alert rule. Valid values:

  • &&: An alert is triggered only if all metrics in the multi-metric alert rule meet the trigger conditions. In this case, an alert is triggered only if the results of all trigger conditions that are specified in the multi-metric alert rule are true.
  • ||: An alert is triggered if one of the metrics in the multi-metric alert rule meets the trigger condition.

Default value: &&.

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"}]
&Expression=[{"MetricName":"CpuUtilization","ComparisonOperator":">=","Period":900,"Statistics":"Average","Threshold":40.0}]
&ExpressionsLogicOperator=&&
&<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.