All Products
Search
Document Center

Elastic Compute Service:Use EventBridge and CloudMonitor to subscribe to Cloud Assistant events

Last Updated:Nov 26, 2024

Cloud Assistant events include task status events and first heartbeat events. You can subscribe to the events to facilitate the management and monitoring of cloud resources. This topic describes Cloud Assistant events and how to subscribe to the events by using EventBridge and CloudMonitor.

Cloud Assistant events

Cloud Assistant task status events

Description

After you execute a Cloud Assistant task by calling the asynchronous RunCommand or InvokeCommand operation, you need to poll the DescribeInvocations or DescribeInvocationResults operation to check whether the task is complete.

The task status events of Cloud Assistant are designed to keep you updated of the progress of Cloud Assistant tasks. The events provide the following benefits:

  • You receive notifications when Cloud Assistant tasks fail or are complete. The notifications can be used for alerts or subsequent operations.

  • Compared with polling API operations, using Cloud Assistant events can reduce the consumption of API quota.

  • The polling process is prone to interruptions by application releases. Using Cloud Assistant events instead can prevent interruptions and reduce complexity.

Triggering conditions and limitations

Triggering conditions: When you call the RunCommand or InvokeCommand operation to execute a Cloud Assistant task, Cloud Assistant monitors the status of the task and triggers a task status event when the task is complete.

Limitations:

  • A Cloud Assistant task status event is triggered only when a Cloud Assistant task enters one of the following states (InvocationStatus) on an Elastic Compute Service (ECS) instance:

    • Aborted: The task failed to be issued.

    • Success: The task is complete.

    • Failed: The task failed to be executed.

    • Invalid: The task content is invalid.

    • Timeout: The task timed out.

    • Cancelled: The task is canceled.

    • Terminated: The task is terminated before completion.

  • The DescribeInvocations and DescribeInvocationResults operations can be used to query the status of multiple Cloud Assistant tasks. However, a Cloud Assistant task status event reports the status of only a single Cloud Assistant task on a single ECS instance.

Parameters

Parameter

Description

Example

instanceId

The ID of the instance.

i-bp114***************

invokeId

The ID of the Cloud Assistant task.

t-hz045**********

commandId

The ID of the command.

c-hz045**********

commandName

The name of the command.

ACS-ECS-ResetPassword-for-linux.sh

ownerUid

The account that owns the instance where the command was run.

158*************

playerUid

The ID of the identity that assumed a Resource Access Management (RAM) role to run the command.

256***************

repeatMode

The execution mode of the command. If this parameter and the InstanceId parameter are both specified, this parameter does not take effect. Valid values:

  • Once: immediately runs the command.

  • Period: periodically runs the command based on a schedule.

  • NextRebootOnly: runs the command the next time the instance starts.

  • EveryReboot: runs the command each time the instance starts.

Once

repeats

The number of times that the command has been run on the instance.

  • If the repeatMode parameter is set to Once, the value is 0 or 1.

    • 0: The execution of the command failed to start.

    • 1: The execution of the command started.

  • If the repeatMode parameter is set to Period, the value is the number of times that the command has been run.

0

invocationStatus

The execution status of the command.

  • Invalid: The command type or the parameter value is invalid.

  • Aborted: The command failed to be sent to the instance. This is because the instance is not in the Running state or the command sending process cannot be complete within 1 minute.

  • Success:

    • If the repeatMode parameter is set to Once, the value indicates that the command task was complete and the exit code was 0.

    • If the repeatMode parameter is set to Period, the value indicates that the last command execution was complete with an exit code of 0, and the specified execution cycle ended.

  • Failed:

    • If the repeatMode parameter is set to Once, the value indicates that the command task was complete, but the exit code was not 0.

    • If the repeatMode parameter is set to Period, the value indicates that the last command execution was complete with a non-zero exit code, and the specified execution cycle was about to end.

  • Timeout: The command execution timed out.

  • Cancelled: The command execution was canceled before the start of the execution.

  • Terminated: The command execution was terminated before completion.

Success

exitCode

The exit code of the command task.

0

startTime

The start time of the command task.

2023-12-20T06:15:55Z

finishTime

The end time of the command task.

2023-12-20T06:15:59Z

errorCode

The error code for the failure to send or run the command.

0

errorDesc

The description of the failure to send or run the command.

-

Cloud Assistant first heartbeat events

Description

Cloud Assistant uses heartbeats to determine the status of the operating system on an ECS instance. The first heartbeat of Cloud Assistant can be used to determine the point in time at which the operating system of the ECS instance was started. You can use the first heartbeat of Cloud Assistant to check the health status of your ECS instance or determine whether you can issue Cloud Assistant tasks.

Compared with polling the DescribeCloudAssistantStatus operation, using Cloud Assistant first heartbeat events resolves the following issues:

  • Polling the DescribeCloudAssistantStatus operation to query the status of Cloud Assistant on instances is a complex process. An inappropriate interval may cause a surge of requests, which may trigger throttling or overwhelm the system.

  • The operating system of an ECS instance may require an extended period of time to complete the boot process. For example, a Windows instance may require 5 minutes to boot. The amount of time required by the polling process to complete varies.

  • The results returned by the DescribeCloudAssistantStatus operation may lag 2 minutes behind. This leads to inaccuracies in scenarios such as instance restart.DescribeCloudAssistantStatus

Triggering conditions and limitations

Triggering conditions: When Cloud Assistant reports heartbeats, it checks its indexes under the hood and triggers a first heartbeat event for the first heartbeat. Then, the event is sent to Cloud Assistant Agent from the Cloud Assistant server.

Limitations: The version of Cloud Assistant must meet the following requirements:

  • Windows: The version of Cloud Assistant must be later than 1.0.0.149.

  • Linux: The version of Cloud Assistant must be later than 1.0.2.569.

Note

Cloud Assistant of earlier versions does not report heartbeats at a 1-minute interval or report fields in indexes. As a result, Cloud Assistant of earlier versions cannot identify the first heartbeat after startup and does not support Cloud Assistant first heartbeat events.

Parameters

Parameter

Description

Example

bizEventId

The ID of the event.

ea33c3e2-aaf0-****-****-5d49b1ecce99

vmName

The ID of the ECS instance associated with the event.

i-bp19****************

extensions

The additional business information.

-

azone

The zone.

cn-shenzhen-e

region

The region.

cn-shenzhen

agentVersion

The Cloud Assistant Agent version.

2.2.3.529

uptime

The amount of time that elapsed since the start of the operating system. Unit: milliseconds.

19000

Subscribe to Cloud Assistant events

  • To ensure successful subscription and reception of events, we recommend that you familiarize yourself with the documentation of the API operations and services.

  • If the subscription failed or you did not receive the events as expected, check whether the version of Cloud Assistant meets the requirements or whether EventBridge or CloudMonitor is properly configured.

  • Make sure that you have retry policies and exception handling mechanisms in place to ensure that your system can properly process the event notifications.

Use EventBridge to subscribe to Cloud Assistant events

Make sure that you have activated EventBridge and completed authorization. For more information, see Activate EventBridge and grant permissions to a RAM user.

  1. Log on to the EventBridge console. In the left-side navigation pane, click Event Buses.

  2. In the top navigation bar, select a region.

  3. On the Event Buses page, find the default event bus and click the name of the event bus.

  4. In the left-side navigation pane of the details page of the default event bus, click Event Rules and then click Create Rule.

  5. In the Configure Basic Info step of the wizard, enter a name for the rule in the Name field, enter a description for the rule in the Description field, and then click Next Step.

  6. In the Configure Event Pattern step of the wizard, configure the parameters and click Next Step.

    1. Select Alibaba Cloud Service Event Sources for the Event Source Type parameter.

    2. In the Event Source drop-down list, select acs.ecs.

    3. In the Event Type drop-down list, select the types of Cloud Assistant events to which you want to subscribe.

      1. Cloud Assistant first heartbeat event: ecs:CloudAssistant:FirstHeartbeat

      2. Cloud Assistant task status event: ecs:CloudAssistant:TaskCompleted

    4. In the Event Pattern Debugging section, view the sample code of the subscribed event types.

      View the sample code of Cloud Assistant events

      Cloud Assistant task status event

      {
          "id": "45ef4dewdwe1-7c35-447a-bd93-fab****",
          "source": "acs.ecs",
          "specversion": "1.0",
          "subject": "acs.ecs:cn-hangzhou:123456789098****:215672",
          "time": "2020-11-19T21:04:41+08:00",
          "type": "ecs:CloudAssistant:TaskCompleted",
          "aliyunaccountid": "123456789098****",
          "aliyunpublishtime": "2020-11-19T21:04:42Z",
          "aliyuneventbusname": "default",
          "aliyunregionid": "cn-hangzhou",
          "aliyunpublishaddr": "172.25.XX.XX",
          "data": {
              "commandId": "c-hz045**********",
              "commandName": "hello-linux.sh",
              "exitCode": "0",
              "finishTime": "2023-12-14T07:39:48Z",
              "instanceId": "i-bp114***************",
              "invocationStatus": "Success",
              "invokeId": "t-hz045**********",
              "ownerId": "158*************",
              "playerUid": "256***************",
              "repeatMode": "Once",
              "repeats": "1",
              "startTime": "2023-12-14T07:39:48Z",
              "errorCode": "0",
              "errorDesc": ""
          }
      }

      Cloud Assistant first heartbeat event

      {
          "id": "45ef4dewdwe1-7c35-447a-bd93-fab****",
          "source": "acs.ecs",
          "specversion": "1.0",
          "subject": "acs.ecs:cn-hangzhou:123456789098****:215672",
          "time": "2020-11-19T21:04:41+08:00",
          "type": "ecs:CloudAssistant:FirstHeartbeat",
          "aliyunaccountid": "123456789098****",
          "aliyunpublishtime": "2020-11-19T21:04:42Z",
          "aliyuneventbusname": "default",
          "aliyunregionid": "cn-hangzhou",
          "aliyunpublishaddr": "172.25.XX.XX",
          "data": {
              "bizEventId": "ea33c3e2-aaf0-****-****-5d49b1ecce99",
              "extensions": {
                  "agentVersion": "2.2.3.529",
                  "region": "cn-hangzhou",
                  "azone": "cn-hangzhou-k",
                  "uptime": "19000"
              },
              "impact": "Alert",
              "opsCode": "InstanceStatusChange",
              "vmName": "i-bp19****************"
          }
      }

    5. Click Test below the code block to simulate the triggering of an event. If Match succeeded. The event can be triggered as expected. is displayed, the event can be triggered as expected.

  7. In the Configure Targets step, select the service types and configure the push scenarios.

    For information about the push scenarios, see Use EventBridge to quickly subscribe to ECS events.

Use CloudMonitor to subscribe to Cloud Assistant events

  1. Log on to the CloudMonitor console.

  2. In the left-side navigation pane, choose Event Center > Event Subscription.

    Note

    You can also perform the following steps to create a subscription policy by using the System Event menu:

    1. In the left-side navigation pane, choose Event Center > System Event.

    2. In the Welcome to the New Event Center section, click Create Immediately to create a subscription policy.

  3. On the Subscription Policy tab, click Create Subscription Policy.

  4. On the Create Subscription Policy page, configure the parameters.

    This section describes only the parameters related to Cloud Assistant events. For information about the other parameters, see the Subscription policy parameters section of the "Manage event subscription policies (recommended)" topic.

    • Subscription Type: Select System events.

    • Subscription Scope:

      • Products: Select Elastic Compute Service (ECS) from the drop-down list.

      • Event Type: Select Notifications.

      • Event name: Select CloudAssistant:FirstHeartbeator CloudAssistant:TaskCompleted.

  5. Click Submit.

    You are notified when relevant events are triggered. You can also call the DescribeSystemEventAttribute operation to query the details of system events.