Use the Operation Content and Result Delivery feature of Cloud Assistant - Elastic Compute Service

The Operation Content and Result Delivery feature provided by Cloud Assistant allows you to deliver task execution records to Object Storage Service (OSS) or Simple Log Service for persistent storage. This topic describes how to configure delivery settings to deliver task execution records to specific OSS buckets or Simple Log Service Logstores and how to query the delivered execution records.

Background information

Cloud Assistant allows execution records to be retained but puts limits on the maximum number of execution records retained and their retention periods. For more information, see the Cloud Assistant limits section of the "Limits" topic. If you want to retain a large number of execution records or retain execution records for an extended period of time, we recommend that you use the Operation Content and Result Delivery feature. The Operation Content and Result Delivery feature allows you to deliver and query execution records and perform operations on the records, such as security analysis, resource change tracking, and behavioral compliance auditing.

Billing

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 the Operation Content and Result Delivery feature

Log on to the ECS console.
In the left-side navigation pane, choose Maintenance & Monitoring > Cloud Assistant.
In the upper-left corner of the top navigation bar, select a region.
Note
Task execution records cannot be delivered across regions. To deliver task execution records in multiple regions, configure delivery settings for each of the regions.
In the upper-right corner of the ECS Cloud Assistant page, click Configure.
In the Cloud Assistant Settings dialog box, click the Command Execution Settings tab to configure the delivery settings.
- Deliver task execution records to Simple Log Service.
  1. 1. Select Deliver to Log Service.
    2. Select an existing Simple Log Service project and Logstore.
      - If you do not have Simple Log Service projects or Logstores in the selected region, click Log Service Console or Logstores to create projects or Logstores in the Simple Log Service console. After you create projects or Logstores, go back to the Cloud Assistant Settings dialog box in the ECS console and click the icon to obtain the most recent list of Simple Log Service projects or Logstores. For information about how to create a Simple Log Service project and how to create a Simple Log Service Logstore, see Manage a project and Manage a Logstore.
      - To query or analyze logs in Simple Log Service, you must enable indexing. For more information, see Create indexes.
      - (Optional) Specify a server-side encryption method for the Logstore. Session records delivered to the Logstore are encrypted by using the encryption method. For more information, see Encrypt data.
- Deliver task execution records to OSS.
  - 1. Click Deliver to OSS.
    2. Select an existing OSS bucket and enter a root directory in which you want to store session records.
      If you do not have OSS buckets in the selected region, click OSS Console to create buckets in the OSS console. After you create buckets, go back to the dialog box in the ECS console and click the icon to obtain the most recent list of OSS buckets. For information about how to create an OSS bucket, see Create buckets.
    3. (Optional) Click the icon next to Advanced Options to specify a server-side encryption method.
      Note
      OSS provides a server-side encryption mechanism to protect static data. You can use the mechanism in scenarios that require high security or compliance. If you specify a server-side encryption method, the objects that contain the session records are encrypted by using the method. For more information, see Server-side encryption.
Click Determine.
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: Run commands or send files

After you run commands or send files, the corresponding task execution records are automatically delivered to the specified Simple Log Service Logstore or OSS bucket.

For more information, see Use the immediate execution feature, Run a command, and Upload on-premises files to ECS instances.

Step 3: View task execution records

View task execution records in the Simple Log Service console

This section describes how to access a Logstore from the Elastic Compute Service (ECS) console to view the logs of task execution records that are delivered to the Logstore. Alternatively, you can log on to the Simple Log Service console to access the Logstore.

Log on to the ECS console.
In the left-side navigation pane, choose Maintenance & Monitoring > Cloud Assistant.
In the upper-left corner of the top navigation bar, select a region.
In the upper-right corner of the ECS Cloud Assistant page, click Configure.
In the Cloud Assistant Settings dialog box, click the Command Execution Settings tab and select Deliver to Log Service.
Click Logstores to the right of the Project field.
For information about how to query and analyze logs, see Query and analyze logs.
The following figures show the sample logs of task execution records. For information about the parameters in the logs, see the Parameters in task execution records section of this topic.
- Sample log of one-time command execution records
- Sample log of scheduled command execution records
  The value of the Repeats parameter indicates the number of times that the command was run.
- Sample log of file sending records

View task execution records in the OSS console

This section describes how to access an OSS bucket from the ECS console to view the objects of task execution records that are delivered to the bucket. Alternatively, you can log on to the OSS console to access the bucket.

Log on to the ECS console.
In the left-side navigation pane, choose Maintenance & Monitoring > Cloud Assistant.
In the upper-left corner of the top navigation bar, select a region.
In the upper-right corner of the ECS Cloud Assistant page, click Configure.
In the Cloud Assistant Settings dialog box, click the Command Execution Settings tab and select Deliver to OSS.
Click OSS Console to the right of the Bucket field.
Go to the directory in which the object that contains the execution records of a task is stored.
After you log on to the OSS console, you are automatically directed to the root directory that you specified when you configured delivery settings to deliver task execution records. You can access the subdirectories that are automatically generated based on the task type.
- For a command task, go to the invocationResults/<Task ID> subdirectory. In this subdirectory, directories that are named after ECS instance IDs and the script of the command are displayed. The script may have one of the following names:
  - commandContent.bat: A batch command, which can run on Windows ECS instances.
  - commandContent.ps1: A PowerShell command, which can run on Windows ECS instances.
  - commandContent.sh: A shell command, which can run on Linux ECS instances.
- For a file-sending task, go to the sendFileResults/<Task ID> subdirectory. In this subdirectory, directories that are named after ECS instance IDs and the fileContent.txt file are displayed. The file contains the sent content.
The following figure shows a sample subdirectory generated for a task that runs a shell command on a Linux ECS instance.
Go to the directory that is named after the ID of an ECS instance to query the object that contains the execution records of tasks run on the instance.
The following figures show sample JSON-formatted objects that contain task execution records.
- Sample object that contains one-time command execution records
- Sample object that contains scheduled command execution records
  The number in each object name indicates the number of times that the command was run on the specified instance.
- Sample object that contains file sending records

Click View Details in the Actions column corresponding to an object that contains task execution records. Then, download the object or copy the object URL and view the object content.

The following code shows a sample object that contains the one-time execution records of a shell command. For information about parameters contained in the execution records, see the Parameters in task execution records section of this topic.

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

Parameters in task execution records

The following table describes parameters that are contained in task execution records. For more information about how to use the parameters, such as valid values, see DescribeCommands and DescribeInvocationResults.

Parameter	Example	Description
RegionId	cn-hangzhou	The region ID of the ECS instance on which the command was run.
InstanceId	i-bp1hd5ztmab9cgc0****	The ID of the instance
InvokeId	t-hz01x7rtjfy****	The ID of the command task.
CommandId	c-hz01x7cn5aj****	The script ID.
CommandName	cmd-hostname	The name of the command.
CommandType	RunShellScript	The type of the command.
CommandContent	hostname	The plaintext content of the command.
ResourceOwnerUid	160998252992****	The Alibaba Cloud account ID of the command caller.
CallerUid	160998252992****	The account ID of the command caller.
CallerType	customer	The call mode of the command caller.
Timeout	60	The timeout period for the command task. Unit: seconds.
Frequency	0 * 14 * * ?	The schedule on which the command is run. The value of this parameter is a cron expression. For more information, see Cron expressions.
Parameters	{}	The key-value pairs of custom parameters that are passed in when custom parameters are included in the command.
Username	root	The username used to run the command on ECS instances.
RepeatMode	Period	Indicates how the command was run.
Repeats	2	The number of times that the command was run on the ECS instance.
InvocationStatus	Success	The command status on a single ECS instance.
ErrorCode	InstanceNotExists	The error code returned when the command cannot be sent or run.
ErrorInfo	the specified instance does not exists	The error message returned when the command cannot be sent or run.
Dropped	0	The size of the text that was truncated and discarded when the value of the Output response parameter exceeded 24 KB in size.
Output	iZbp1hd5ztmab9cgc0****\n	The command output.
ExitCode	0	The exit code of the command.
CreationTime	2021-09-26T05:47:20Z	The time when the command task was created.
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 task was updated.
FinishedTime	2021-09-26T06:53:00Z	The time when the command task was completed.
StopTime	2021-09-26T06:53:00Z	The time when the command stopped running on the ECS instance. If you called the StopInvocation operation to manually stop the execution, the value is the time when the operation was called.

The following table describes parameters that are contained in file sending records. For more information about how to use the parameters, such as valid values, see DescribeSendFileResults.

Parameter	Example	Description
RegionId	cn-hangzhou	The region ID of the ECS instance to which the file was sent.
InstanceId	i-bp1hd5ztmab9cgc0****	The ID of the instance
InvokeId	f-hz01xeva44****	The ID of the file sending task.
FileName	sendfile-test.txt	The name of the file
ContentType	Base64	The content type of the file.
Description	Used for test	The description of the file.
FileContent	c2VuZCBmaWxlIHRlc3Q=	The content of the file.
FileGroup	root	The group of the file.
FileMode	0644	The permissions on the remote file.
FileOwner	root	The owner of the remote file.
ResourceOwnerUid	16099825299****	The Alibaba Cloud account ID of the file sender.
CallerUid	16099825299****	The account ID of the file sender.
CallerType	customer	The call mode of the file sender.
Overwrite	true	Indicates whether a file was overwritten in the destination directory if the file has the same name as the sent file.
TargetDir	/root	The destination directory to which the file was sent.
Timeout	60	The timeout period of the file sending task. Unit: seconds.
InvocationStatus	Success	The status of the file sending task.
ErrorCode	FileAlreadyExists	The error code returned when the file failed to be sent to the ECS instance
ErrorInfo	File already exists: sendfile-test.txt	The error message returned when the file failed to be sent to the ECS instance or when the file sending task failed to be executed on the ECS instance.
CreationTime	2021-09-28T05:31:04Z	The creation time of the file sending task.
StartTime	2021-09-28T05:31:04Z	The time when the file sending task started to be executed 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 was completed.