Monitoring Commands
There are several ways to monitor the status of the commands you send with Run Command:
Configure CloudWatch Events to log status changes.
Configure Amazon SNS to send notifications for all status changes or specific statuses like Failed or TimedOut.
Click the Refresh icon on the Command History page in the Amazon EC2 console.
Call the
ListCommandorListCommandInvocationAPI using a command line tool.
This section includes information about how to automate monitoring by using CloudWatch Events and SNS notifications.
When you send a command to multiple instances at the same time, each copy of the command targeting each instance is a command invocation. For example, if you use the AWS-RunShellScript JSON document and send an ifconfig command to 20 instances, that command has 20 invocations. Run Command monitoring options enable you to examine the details of each invocation, which can help you troubleshoot problems if a command fails.
Command Status
Each command invocation individually reports status. Furthermore, each SSM document consists of one or more code-execution blocks called plugins. The plugins for a given command invocation individually report status as well. The following table describes Run Command execution statuses.
For more information about plugins, see SSM Plugins in the Amazon EC2 Simple Systems Manager API Reference.
| Status | Details |
|---|---|
| Pending | The command was not yet received by the SSM agent. If the command is not received by the agent before the value specified by the Timeout (seconds) parameter is reached, then the status changes to Timed Out. |
| In Progress | The command was received by the SSM agent, or the command started executing on the instance. Depending on the result of all command plugins, the status will change to Success, Failed, or Timed Out. If the SSM agent is not available on the instance, the command status will show In Progress until the agent is available again. The status will then change to a terminal state. |
| Success | The command, including all plugins, finished executing on the instance. |
| Failed |
One or more plugins failed to execute. To help you identify and troubleshoot problems with a command, if a plugin fails, the entire invocation status is changed to Failed. |
| Timed Out | The command did not reach the SSM agent on the instance before the value specified by the Timeout (seconds) parameter was reached. Or, the command execution ran longer than the allowable execution time. The amount of time a command execution can run varies by plugin. Default values range from two hours to eight hours. |
| Cancelling | You sent the command to cancel a command invocation. The command has not reached a terminal state (Success, Failed, or Timed Out). If the SSM agent responds within the time-frame specified by the Timeout (seconds) parameter, then the status will change to reflect a terminal state. Otherwise the status will change to Timed Out. |
| Cancelled | The command was successfully cancelled. |
Note
In the Amazon EC2 console, click the Refresh symbol in the upper-right corner to monitor command status as command execution progresses.
