文档

使用EventBridge和云监控订阅云助手事件

更新时间:

云助手事件包括任务状态事件和心跳事件,您可以通过事件订阅获取任务执行状态和心跳上报,以优化云资源的管理和监控。本文介绍了云助手事件的功能,以及如何使用EventBridge和云监控订阅云助手事件。

云助手事件说明

云助手任务状态事件

事件描述

用户所运行的命令/脚本往往执行需要一定时间。云助手的RunCommand/InvokeCommand接口为异步接口,调用之后,需要轮询DescribeInvocations/DescribeInvocationResults接口查询任务完成状态,直至该任务完成。

云助手任务状态事件用于加强对任务完成情况的感知,您可以利用该事件达到以下目的:

  • 在任务失败或任务处于完成状态时,获得通知,以便设置报警、处理任务等。

  • 使用轮询会占用用户的API调用额度,通过事件订阅的方式可以避免该问题。

  • 轮询的过程较长,容易被应用发布所打断。使用事件规避状态打断,可以降低用户的复杂度。

事件触发条件&限制

事件触发条件:用户使用RunCommand/InvokeCommand触发任务执行,云助手内部监听任务完成状态,处于完成态的任务则发出该事件。

事件使用限制:

  • 仅在云助手在实例上的任务执行状态(InvocationStatus)变为以下状态时,才会触发发送事件。

    • Aborted:任务下发失败

    • Success:任务执行成功

    • Failed:任务执行失败

    • Invalid:任务内容非法

    • Timeout:任务执行超时

    • Cancelled:任务执行取消

    • Terminated:任务执行被终止

  • 在OpenAPI(DescribeInvocations/DescribeInvocationResults)中,事件查询的返回数据格式为array<object>。在本事件中,上报的是一个任务在单个实例上的执行状态,而不是多个任务。

事件字段说明

字段

说明

示例值

instanceId

实例ID。

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

invokeId

命令执行ID。

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

commandId

命令ID。

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

commandName

命令名称。

ACS-ECS-ResetPassword-for-linux.sh

ownerUid

执行命令的实例归属账号。

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

playerUid

角色扮演者账号ID。

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

repeatMode

命令执行的方式。如果同时设置了InstanceId参数,则不生效。取值范围:

  • Once:立即执行命令。

  • Period:定时执行命令。

  • NextRebootOnly:当实例下一次启动时,自动执行命令。

  • EveryReboot:实例每一次启动都将自动执行命令。

Once

repeats

命令在该实例上执行的次数。

  • 若执行方式为立即执行,则值为0或1。

    • 0:命令下发失败,命令脚本未启动执行。

    • 1:命令下发成功,命令第一次在此实例上执行。

  • 若执行方式为定时执行,则值为执行过多少次。

0

invocationStatus

命令执行的状态。

  • Invalid:指定命令类型或参数错误。

  • Aborted:向实例发送命令失败。实例必须在运行中,且命令可以在1分钟内发送完成。

  • Success:

    • 单次执行的命令:命令执行完成,且退出码为0。

    • 定时执行的命令:上一次执行成功且退出码为0,且指定的执行时间已结束。

  • Failed:

    • 单次执行的命令:命令执行完成,且退出码非0。

    • 定时执行的命令:上一次执行成功且退出码非0,且指定的执行时间将中止。

  • Timeout:命令执行超时。

  • Cancelled:命令的执行动作已经取消,命令未曾启动。

  • Terminated:命令执行时被终止。

Success

exitCode

命令进程的退出码。

0

startTime

任务开始时间。

2023-12-20T06:15:55Z

finishTime

任务结束时间。

2023-12-20T06:15:59Z

errorCode

命令下发失败或执行失败原因code。

0

errorDesc

命令下发失败或执行失败的原因详情。

-

云助手首次心跳事件

事件描述

云助手的心跳是判定GuestOS(实例操作系统)状态的手段之一。其中,首次心跳可以用来判断GuestOS真正启动的时间,作为实例健康状态、下发云助手命令等场景的参考。

相比通过轮询DescribeCloudAssistantStatus的方式查看心跳是否上报,云助手首次心跳事件可以规避以下问题:

  • 轮询查询DescribeCloudAssistantStatus状态是否变为true,实现比较复杂。如果间隔不当,可能产生过多请求,造成流控或对系统造成压力。

  • 由于GuestOS真正的启动时间差别较大,部分Windows实例偶尔需要5分钟才能启动完成,轮询不容易控制总时长。

  • DescribeCloudAssistantStatus对状态的判断有一定的滞后性,从有心跳到无心跳会有2分钟的滞后,所以对于重启实例的场景,DescribeCloudAssistantStatus不容易识别。

事件触发条件&限制

事件触发条件:在云助手心跳上报时,通过内部index识别,当判定为首次心跳时触发事件,由云助手服务端发送云助手客户端启动后的首次心跳事件。

云助手版本限制:

  • Windows实例:云助手版本必须高于1.0.0.149。

  • Linux实例:云助手版本必须高于1.0.2.569。

说明

低版本云助手不会通过每分钟一次的心跳上报接口上报心跳,或不会上报index字段,因此不能准确识别出启动后的首次心跳,暂时不对这些低版本做支持。

事件字段说明

字段

说明

示例值

bizEventId

事件ID。

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

vmName

事件关联的实例ID。

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

extensions

业务扩展信息。

-

azone

可用区。

cn-shenzhen-e

region

地域。

cn-shenzhen

agentVersion

云助手Agent版本。

2.2.3.529

uptime

操作系统已启动的时间(毫秒)

19000

订阅云助手事件

  • 为了确保事件顺利订阅和接收,建议您在设置时仔细阅读各接口和服务的文档,了解最佳实践。

  • 如果遇到订阅失败或未能按预期接收事件的情况,请检查云助手的版本是否满足触发事件的条件,并检查EventBridge或云监控的配置是否正确。

  • 在使用EventBridge或云监控订阅事件时,考虑到可能的延迟和异步处理,务必设计好重试策略和异常处理机制,以便您的系统能够可靠地处理事件通知。

使用EventBridge订阅云助手事件

操作前,请确认您已开通事件总线EventBridge服务并完成授权,具体操作,请参见开通事件总线EventBridge并授权

  1. 登录事件总线EventBridge控制台,在左侧导航栏,单击事件总线
  2. 在顶部菜单栏,选择地域。
  3. 事件总线页面,单击default

  4. 事件总线页面,单击左侧导航栏的事件规则,然后单击创建规则

  5. 配置基本信息页签,在名称文本框输入规则名称,在描述文本框输入规则的描述,然后单击下一步

  6. 配置事件模式页签,完成以下配置,然后单击下一步

    1. 单击阿里云官方事件源页签。

    2. 事件源下拉列表中选择acs.ecs

    3. 事件类型下拉列表中选择需要订阅的云助手事件类型。

      1. 云助手首次心跳事件:ecs:CloudAssistant:FirstHeartbeat

      2. 云助手任务状态事件:ecs:CloudAssistant:TaskCompleted

    4. 事件模式调试中,查看订阅的事件类型的示例。

      查看云助手事件示例

      云助手任务状态事件

      {
          "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": ""
          }
      }

      云助手首次心跳事件

      {
          "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. 在示例下方,单击测试模拟事件触发。如果显示匹配通过,事件可正常被触发,表示事件可正常触发。

  7. 配置事件目标,选择不同的服务类型,设置推送场景。

    更多推送场景说明,请参见设置推送场景

使用云监控订阅云助手事件

  1. 登录云监控控制台

  2. 在左侧导航栏,选择事件中心 > 事件订阅

    说明

    您还可以通过系统事件菜单创建订阅策略,具体操作如下:

    1. 在左侧导航栏,选择事件中心 > 系统事件

    2. 欢迎体验新版事件中心区域,单击立即创建

  3. 订阅策略页签,单击创建订阅策略

  4. 创建订阅策略页面,设置订阅云助手事件的相关参数。

    本示例仅展示云助手事件的相关参数,更多参数说明,请参见订阅策略参数说明

    • 订阅类型:选择系统事件

    • 订阅范围

      • 产品:选择云服务器ECS

      • 事件类型:选择异常

      • 事件名称:选择云助手首次心跳时间云助手任务状态事件

  5. 设置完成后,单击提交

    当相关事件触发时,您会收到相关事件的通知。您也可以通过调用DescribeSystemEventAttribute查询系统事件详情。

  • 本页导读 (1)