Use the Cloud Assistant feature to deliver task execution records - Elastic Compute Service

You can use Cloud Assistant to deliver task execution records to Object Storage Service (OSS) and Simple Log Service (SLS) for persistent storage. This topic describes how to configure delivery settings and view the delivered execution record files.

Background information

Cloud Assistant supports the retention of execution records, but limits apply to the retention period and the number of records. For more information, see Cloud Assistant limits. To retain many execution records or store them for an extended period, you can use the delivery feature. This feature lets you query records, perform security analytics, track resource changes, and conduct behavior compliance audits.

Billing overview

The Session Record Delivery feature is free of charge. However, you may be charged for the following items when you use the feature:

Billable items of Simple Log Service, such as storage space occupied by the delivered records and log index traffic.

For more information, see Billing overview.
Billable items of OSS, such as space storage occupied by the delivered records and traffic generated when you use the object management feature of OSS.

For more information, see Billing overview.

Step 1: Configure delivery for task execution records

Go to ECS console - Cloud Assistant.
In the upper-left corner of the page, select a region and resource group.

Note
Cross-region delivery is not supported. You must configure delivery for each region separately.
In the upper-right corner of the ECS Cloud Assistant page, click Settings.
In the Cloud Assistant Settings dialog box, click the Command Execution Settings tab and configure the delivery settings.
- Deliver task execution records to SLS.
  1. Select Deliver to Log Service.
  2. Select an existing SLS project and Logstore.
    
    If you have not created an SLS project and Logstore, click Log Service Console or Logstores on the right to create them. After you create the project and Logstore, return to this dialog box and click the icon to refresh the list. For more information, see Manage Projects and Manage Logstores.
  Note
  To query and analyze logs in SLS, you must enable indexing. Enabling indexing generates index traffic and consumes index storage space. For more information about billing, see SLS billing. You can decide whether to create an index for the Logstore.
- Deliver task execution records to OSS.
  1. Select Deliver to OSS.
  2. Select an existing OSS bucket and enter the root directory for storing the task execution record files.
    
    If you have not created an OSS bucket, click OSS Console on the right to create one. After you create the bucket, return to this dialog box and click the icon to refresh the list. For more information, see Create a bucket.
  Note
  OSS provides server-side encryption for data-at-rest protection. This feature is suitable for applications with high security or compliance requirements for file storage. If you configure a server-side encryption method, the delivered task execution record files (Objects) are encrypted. For more information, see Server-side encryption.
Click OK.

The first time you configure delivery settings, the system creates a service-linked role that grants Cloud Assistant access to Simple Log Service and OSS resources. This way, you can deliver session records to specific Simple Log Service Logstores or OSS buckets. If the service-linked role already exists, the system does not re-create the role. You can manage the role for Cloud Assistant based on your business requirements. For more information, see Manage the service-linked role for ECS Cloud Assistant.

Step 2: Execute a command or send a file

You can execute a command or send a file. The execution records are then automatically delivered to your specified SLS Logstore or OSS bucket.

For more information, see Create and run a command, Run a command, and Upload a file to an ECS instance using Cloud Assistant.

Step 3: View task execution records

View task execution records in SLS

This section describes how to navigate to a specific Logstore from the ECS console. Alternatively, you can log on to the SLS console and find the Logstore.

Go to ECS console - Cloud Assistant.
In the upper-left corner of the page, select a region and resource group.
In the upper-right corner of the ECS Cloud Assistant page, click Settings.
In the Cloud Assistant Settings dialog box, click the Command Execution Settings tab, and then select Deliver to Log Service.
To the right of Select a Logstore, click Logstores.
For more information about how to view logs, see Quick start for query and analysis.
The following are examples of Cloud Assistant task execution record logs. For more information about the parameters, see Task execution record parameters.
- One-time command execution
- Scheduled command execution
  
  The value of the Repeats parameter indicates the number of times the command has been executed.
- Send a file

View task execution records in OSS

This section describes how to navigate to a specific bucket from the ECS console. Alternatively, you can log on to the OSS console and find the bucket.

Go to ECS console - Cloud Assistant.
In the upper-left corner of the page, select a region and resource group.
In the upper-right corner of the ECS Cloud Assistant page, click Settings.
In the Cloud Assistant Settings dialog box, click the Command Execution Settings tab, and then select Deliver to OSS.
To the right of Bucket, click OSS Console.
Navigate to the directory where the files related to a task are stored.
After you navigate to the OSS console, the system automatically directs you to the root directory that you specified when you configured task execution record delivery. You can then navigate to the automatically generated subdirectories based on the task type:
- If the task type is Run Command, navigate to the invocationResults/<Execution ID> directory. This directory contains subdirectories named after the ECS instance IDs and the command script files, such as:
  - commandContent.bat: For running a Bat command on a Windows instance.
  - commandContent.ps1: For running a PowerShell command on a Windows instance.
  - commandContent.sh: For running a Shell command on a Linux instance.
- If the task type is Send File, navigate to the sendFileResults/<Execution ID> directory. This directory contains subdirectories named after ECS instance IDs and a file named fileContent.txt that contains the content of the sent file.
The following figure shows an example directory for running a Shell command on a Linux instance.
Navigate to the directory named after the ECS instance ID to view the record file of the task that was executed on that ECS instance.
The execution record file is in JSON format. The following are examples.
- One-time command execution
- Scheduled command execution
  
  The number in the filename indicates the number of times the command has been executed on the specified instance.
- Send a file

In the Actions column of the execution record file, click Details. Then, download the file or copy the file URL to view the file content.

The following is an example of the file content for a one-time Shell command execution. For more information about the parameters, see Task execution record parameters.

{
    "RegionId":"cn-hangzhou",
    "InstanceId":"i-bp1hd5ztmab9cgc0****",
    "InvokeId":"t-hz01x7rtjfy****",
    "CommandId":"c-hz01x7cn5aj****",
    "CommandName":"cmd-hostname",
    "CommandType":"RunShellScript",
    "CommandContent":"hostname",
    "ResourceOwnerUid":160998252992****,
    "CallerUid":160998252992****,
    "CallerType":"customer",
    "Timeout":60,
    "Frequency":"",
    "Parameters":"{}",
    "Username":"",
    "RepeatMode":"Once",
    "Repeats":1,
    "InvocationStatus":"Success",
    "Dropped":0,
    "Output":"iZbp1hd5ztmab9cgc0****\n",
    "ExitCode":0,
    "CreationTime":"2021-09-26T05:47:20Z",
    "StartTime":"2021-09-26T05:47:20Z",
    "UpdateTime":"2021-09-26T05:47:20Z",
    "FinishedTime":"2021-09-26T05:47:20Z",
    "StopTime":""
}

Task execution record parameters

The following table describes the parameters in the execution records for command execution tasks. For more information about the parameters, including their possible values, see DescribeCommands and DescribeInvocationResults.

Name	Example	Description
RegionId	cn-hangzhou	The region ID of the ECS instance where the command was executed.
InstanceId	i-bp1hd5ztmab9cgc0****	The instance ID.
InvokeId	t-hz01x7rtjfy****	The command execution ID.
CommandId	c-hz01x7cn5aj****	The command ID.
CommandName	cmd-hostname	The command name.
CommandType	RunShellScript	The command type.
CommandContent	hostname	The plaintext content of the command.
ResourceOwnerUid	160998252992****	The Alibaba Cloud account ID of the user who called the command.
CallerUid	160998252992****	The account ID of the user who called the command.
CallerType	customer	The method used to call the command.
Timeout	60	The maximum timeout period for the command to be executed on the ECS instance. Unit: seconds.
Frequency	0 * 14 * * ?	The execution period for a scheduled command. This is a cron expression. For more information, see Cron expressions.
Parameters	{}	The key-value pairs of custom parameters that are passed in when the command is executed, if the command contains custom parameters.
Username	root	The username used to run the command on the ECS instance.
RepeatMode	Period	The execution mode of the command.
Repeats	2	The number of times the command has been executed on the ECS instance.
InvocationStatus	Success	The execution status of the command on a single ECS instance.
ErrorCode	InstanceNotExists	The error code returned if the command failed to be sent or executed.
ErrorInfo	the specified instance does not exists	The details of the error that occurred when the command failed to be sent or executed.
Dropped	0	The length of the text that was truncated and discarded because the Output field exceeded 24 KB.
Output	iZbp1hd5ztmab9cgc0****\n	The output of the command after it is executed.
ExitCode	0	The exit code of the command.
CreationTime	2021-09-26T05:47:20Z	The time when the command execution started.
StartTime	2021-09-26T05:47:20Z	The time when the command started to run on the ECS instance.
UpdateTime	2021-09-26T06:53:00Z	The time when the status of the command execution task was updated.
FinishedTime	2021-09-26T06:53:00Z	The time when the command execution was complete.
StopTime	2021-09-26T06:53:00Z	The time when StopInvocation was called, if it was called.

The following table describes the parameters in the execution records for file sending tasks. For more information about the parameters, including their possible values, see DescribeSendFileResults.

Name	Example	Description
RegionId	cn-hangzhou	The region ID of the ECS instance to which the file was sent.
InstanceId	i-bp1hd5ztmab9cgc0****	The instance ID.
InvokeId	f-hz01xeva44****	The execution ID.
FileName	sendfile-test.txt	The file name.
ContentType	Base64	The type of the file content.
Description	Used for test	The description of the file.
FileContent	c2VuZCBmaWxlIHRlc3Q=	The file content.
FileGroup	root	The user group of the file.
FileMode	0644	The permissions of the file.
FileOwner	root	The user of the file.
ResourceOwnerUid	16099825299****	The Alibaba Cloud account ID of the user who sent the file.
CallerUid	16099825299****	The account ID of the user who sent the file.
CallerType	customer	The invocation method for the file sender.
Overwrite	true	Specifies whether to overwrite a file with the same name if it already exists in the destination directory.
TargetDir	/root	The destination path to which the file is sent.
Timeout	60	The timeout period for sending the file. Unit: seconds.
InvocationStatus	Success	The status of the file sending task.
ErrorCode	FileAlreadyExists	The error code returned if the file failed to be sent.
ErrorInfo	File already exists: sendfile-test.txt	The details of the error that occurred when the file failed to be sent or executed.
CreationTime	2021-09-28T05:31:04Z	The time when the file sending task was created.
StartTime	2021-09-28T05:31:04Z	The time when the file sending task started to run on the ECS instance.
UpdateTime	2021-09-28T05:31:04Z	The time when the status of the file sending task was updated.
FinishTime	2021-09-28T05:31:04Z	The time when the file sending task ended.

References

You can call the DescribeCloudAssistantSettings API operation to query the service configurations of Cloud Assistant. You can also call the ModifyCloudAssistantSettings API operation to modify the service configurations.