• The AWS Systems Manager CloudWatch Dashboard will no longer be available after April 30, 2026. Customers can continue to use Amazon CloudWatch console to view, create, and manage their Amazon CloudWatch dashboards, just as they do today. For more information, see [Amazon CloudWatch Dashboard documentation](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Dashboards.html). # Logging and monitoring in AWS Systems Manager Monitoring is an important part of maintaining the reliability, availability, and performance of AWS Systems Manager and your AWS solutions. You should collect monitoring data from all parts of your AWS solution so that you can debug a multipoint failure if one occurs. But before you start monitoring Systems Manager, create a monitoring plan that includes answers to the following questions: + What are your monitoring goals? + What resources will you monitor? + How often will you monitor these resources? + What monitoring tools will you use? + Who performs the monitoring tasks? + Who should be notified when something goes wrong? After you have defined your monitoring goals and have created your monitoring plan, the next step is to establish a baseline for normal Systems Manager performance in your environment. You should measure Systems Manager performance at various times and under different load conditions. As you monitor Systems Manager, you should store a history of monitoring data that you've collected. You can compare current Systems Manager performance to this historical data to help you to identify normal performance patterns and performance anomalies, and create methods to address them. For example, you can monitor the success or failure of operations such as Automation workflows, the application of patch baselines, maintenance window events, and configuration compliance. Automation is a tool in AWS Systems Manager. You can also monitor CPU utilization, disk I/O, and network utilization of your managed nodes. When performance falls outside your established baseline, you might need to reconfigure or optimize the node to reduce CPU utilization, improve disk I/O, or reduce network traffic. For more information about monitoring EC2 instances, see [Monitor Amazon EC2](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/monitoring_ec2.html) in the *Amazon EC2 User Guide*. **Topics** + [Monitoring tools](#monitoring-tools) + [Sending node logs to unified CloudWatch Logs (CloudWatch agent)](monitoring-cloudwatch-agent.md) + [Sending SSM Agent logs to CloudWatch Logs](monitoring-ssm-agent.md) + [Monitoring your change request events](monitoring-change-request-events.md) + [Monitoring your automations](monitoring-automation-metrics.md) + [Monitoring Run Command metrics using Amazon CloudWatch](monitoring-cloudwatch-metrics.md) + [Logging AWS Systems Manager API calls with AWS CloudTrail](monitoring-cloudtrail-logs.md) + [Logging Automation action output with CloudWatch Logs](automation-action-logging.md) + [Configuring Amazon CloudWatch Logs for Run Command](sysman-rc-setting-up-cwlogs.md) + [Monitoring Systems Manager events with Amazon EventBridge](monitoring-eventbridge-events.md) + [Monitoring Systems Manager status changes using Amazon SNS notifications](monitoring-sns-notifications.md) ## Monitoring tools The content in this chapter provides information for using tools available for monitoring your Systems Manager and other AWS resources. For a more complete list of tools, see [Logging and monitoring in AWS Systems Manager](logging-and-monitoring.md). # Sending node logs to unified CloudWatch Logs (CloudWatch agent) You can configure and use the Amazon CloudWatch agent to collect metrics and logs from your nodes instead of using AWS Systems Manager Agent (SSM Agent) for these tasks. The CloudWatch agent allows you to gather more metrics on EC2 instances than are available using SSM Agent. In addition, you can gather metrics from on-premises servers using the CloudWatch agent. You can also store agent configuration settings in the Systems Manager Parameter Store for use with the CloudWatch agent. Parameter Store is a tool in AWS Systems Manager. **Note** AWS Systems Manager supports migrating from SSM Agent to the unified CloudWatch agent for collecting logs and metrics on 64-bit versions of Windows only. For information about setting up the unified CloudWatch agent on other operating systems, and for complete information about using the CloudWatch agent, see [Collecting metrics and logs from Amazon EC2 instances and on-premises servers with the CloudWatch agent](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Install-CloudWatch-Agent.html) in the *[Amazon CloudWatch User Guide](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/)*. You can use the CloudWatch agent on other supported operating systems, but you won't be able to use Systems Manager to perform a tool migration. SSM Agent writes information about executions, scheduled actions, errors, and health statuses to log files on each node. Manually connecting to a node to view log files and troubleshoot an issue with SSM Agent is time-consuming. For more efficient node monitoring, you can configure either SSM Agent itself or the CloudWatch agent to send this log data to Amazon CloudWatch Logs. **Important** The unified CloudWatch agent has replaced SSM Agent as the tool for sending log data to Amazon CloudWatch Logs. The SSM Agent aws:cloudWatch plugin is not supported. We recommend using only the unified CloudWatch agent for your log collection processes. For more information, see the following topics: [Sending node logs to unified CloudWatch Logs (CloudWatch agent)](#monitoring-cloudwatch-agent) [Migrate Windows Server node log collection to the CloudWatch agent](#monitoring-cloudwatch-agent-migrate) [Collecting metrics, logs, and traces with the CloudWatch agent](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Install-CloudWatch-Agent.html) in the *Amazon CloudWatch User Guide*. Using CloudWatch Logs, you can monitor log data in real time, search and filter log data by creating one or more metric filters, and archive and retrieve historical data when you need it. For more information about CloudWatch Logs, see the *[Amazon CloudWatch Logs User Guide](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/)*. Configuring an agent to send log data to Amazon CloudWatch Logs provides the following benefits: + Centralized log file storage for all SSM Agent log files. + Quicker access to files to investigate errors. + Indefinite log file retention (configurable). + Logs can be maintained and accessed regardless of the status of the node. + Access to other CloudWatch features such as metrics and alarms. For information about monitoring Session Manager activity, see [Logging session activity](session-manager-auditing.md) and [Enabling and disabling session logging](session-manager-logging.md). ## Migrate Windows Server node log collection to the CloudWatch agent If you're using SSM Agent on supported Windows Server nodes to send SSM Agent log files to Amazon CloudWatch Logs, you can use Systems Manager to migrate from SSM Agent to the CloudWatch agent as your log collection tool, and migrate your configuration settings. The CloudWatch agent isn't supported on 32-bit versions of Windows Server. For 64-bit EC2 instances for Windows Server, you can perform the migration to the CloudWatch agent automatically or manually. For on-premises servers and virtual machines, the process must be performed manually. **Note** During the migration process, the data sent to CloudWatch might be interrupted or duplicated. Your metrics and log data will be recorded accurately again in CloudWatch after the migration is completed. We recommend testing the migration on a limited number of nodes before migrating an entire fleet to the CloudWatch agent. After migration, if you prefer log collection with SSM Agent, you can return to using it instead. **Important** In the following cases, you won’t be able to migrate to the CloudWatch agent using the steps described in this topic: The existing configuration for SSM Agent specifies multiple Regions. The existing configuration for SSM Agent specifies multiple sets of access/secret key credentials. In these cases, it will be necessary to turn off log collection in SSM Agent and install the CloudWatch agent without a migration process. For more information, see the following topics in the *Amazon CloudWatch User Guide*: [Installing the CloudWatch agent](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/install-CloudWatch-Agent-on-EC2-Instance.html) [Installing the CloudWatch agent on on-premises servers](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/install-CloudWatch-Agent-on-premise.html) **Before you begin** Before you begin a migration to the CloudWatch agent for log collection, ensure that the nodes on which you will perform the migration meet these requirements: + The OS is a 64-bit version of Windows Server. + SSM Agent 2.2.93.0 or later is installed on the node. + SSM Agent is configured for monitoring on the node. **Topics** + [Automatically migrating to the CloudWatch agent](#monitoring-cloudwatch-agent-migrate-auto) + [Manually migrating to the CloudWatch agent](#monitoring-cloudwatch-agent-migrate-manual) ### Automatically migrating to the CloudWatch agent For EC2 instances for Windows Server only, you can use the AWS Systems Manager console or the AWS Command Line Interface (AWS CLI) to automatically migrate to the CloudWatch agent as your log collection tool. **Note** AWS Systems Manager supports migrating from SSM Agent to the unified CloudWatch agent for collecting logs and metrics on 64-bit versions of Windows only. For information about setting up the unified CloudWatch agent on other operating systems, and for complete information about using the CloudWatch agent, see [Collecting metrics and logs from Amazon EC2 instances and on-premises servers with the CloudWatch agent](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Install-CloudWatch-Agent.html) in the *[Amazon CloudWatch User Guide](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/)*. You can use the CloudWatch agent on other supported operating systems, but you won't be able to use Systems Manager to perform a tool migration. After the migration succeeds, check your results in CloudWatch to ensure you're receiving the metrics, logs, or Windows event logs you expect. If you're satisfied with the results, you can optionally [Store CloudWatch agent configuration settings in Parameter Store](#monitoring-cloudwatch-agent-store-config). If the migration isn't successful or the results aren't as expected, you can try [Rolling back to log collection with SSM Agent](#monitoring-cloudwatch-agent-roll-back). **Note** If you want to migrate a source configuration file that includes a `{hostname}` entry, then be aware that the `{hostname}` entry can change the value of the field after the migration is complete. For example, say that the following `"LogStream": "{hostname}"` entry maps to a server named *MyLogServer001*. ``` { "Id": "CloudWatchIISLogs", "FullName": "AWS.EC2.Windows.CloudWatch.CloudWatchLogsOutput,AWS.EC2.Windows.CloudWatch", "Parameters": { "AccessKey": "", "SecretKey": "", "Region": "us-east-1", "LogGroup": "Production-Windows-IIS", "LogStream": "{hostname}" } } ``` After the migration, this entry maps to a domain, such as ip-11-1-1-11.production. ExampleCompany.com. To retain the local hostname value, specify `{local_hostname}` instead of `{hostname}`. **To automatically migrate to the CloudWatch agent (console)** 1. Open the AWS Systems Manager console at [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/). 1. In the navigation pane, choose **Run Command**, and then choose **Run command**. 1. In the **Command document** list, choose `AmazonCloudWatch-MigrateCloudWatchAgent`. 1. For **Status**, choose **Enabled**. 1. In the **Targets** section, choose the managed nodes on which you want to run this operation by specifying tags, selecting instances or edge devices manually, or specifying a resource group. **Tip** If a managed node you expect to see isn't listed, see [Troubleshooting managed node availability](fleet-manager-troubleshooting-managed-nodes.md) for troubleshooting tips. 1. For **Rate control**: + For **Concurrency**, specify either a number or a percentage of managed nodes on which to run the command at the same time. **Note** If you selected targets by specifying tags applied to managed nodes or by specifying AWS resource groups, and you aren't certain how many managed nodes are targeted, then restrict the number of targets that can run the document at the same time by specifying a percentage. + For **Error threshold**, specify when to stop running the command on other managed nodes after it fails on either a number or a percentage of nodes. For example, if you specify three errors, then Systems Manager stops sending the command when the fourth error is received. Managed nodes still processing the command might also send errors. 1. (Optional) For **Output options**, to save the command output to a file, select the **Write command output to an S3 bucket** box. Enter the bucket and prefix (folder) names in the boxes. **Note** The S3 permissions that grant the ability to write the data to an S3 bucket are those of the instance profile (for EC2 instances) or IAM service role (hybrid-activated machines) assigned to the instance, not those of the IAM user performing this task. For more information, see [Configure instance permissions required for Systems Manager](setup-instance-permissions.md) or [Create an IAM service role for a hybrid environment](hybrid-multicloud-service-role.md). In addition, if the specified S3 bucket is in a different AWS account, make sure that the instance profile or IAM service role associated with the managed node has the necessary permissions to write to that bucket. 1. In the **SNS notifications** section, if you want notifications sent about the status of the command execution, select the **Enable SNS notifications** check box. For more information about configuring Amazon SNS notifications for Run Command, see [Monitoring Systems Manager status changes using Amazon SNS notifications](monitoring-sns-notifications.md). 1. Choose **Run**. **To automatically migrate to the CloudWatch agent (AWS CLI)** + Run the following command. ``` aws ssm send-command --document-name AmazonCloudWatch-MigrateCloudWatchAgent --targets Key=instanceids,Values=ID1,ID2,ID3 ``` *ID1*, *ID2*, and *ID3* represent the IDs of nodes you want to update, such as *i-02573cafcfEXAMPLE*. ### Manually migrating to the CloudWatch agent For on-premises Windows Server nodes or EC2 instances for Windows Server, follow these steps to manually migrate log collection to the Amazon CloudWatch agent. **Note** If you want to migrate a source configuration file that includes a `{hostname}` entry, then be aware that the `{hostname}` entry can change the value of the field after the migration is complete. For example, say that the following `"LogStream": "{hostname}"` entry maps to a server named *MyLogServer001*. ``` { "Id": "CloudWatchIISLogs", "FullName": "AWS.EC2.Windows.CloudWatch.CloudWatchLogsOutput,AWS.EC2.Windows.CloudWatch", "Parameters": { "AccessKey": "", "SecretKey": "", "Region": "us-east-1", "LogGroup": "Production-Windows-IIS", "LogStream": "{hostname}" } } ``` After the migration, this entry maps to a domain, such as ip-11-1-1-11.production.ExampleCompany.com. To retain the local hostname value, specify `{local_hostname}` instead of `{hostname}`. **One: To install the CloudWatch agent (console)** 1. Open the AWS Systems Manager console at [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/). 1. In the navigation pane, choose **Run Command**, and then choose **Run command**. 1. In the **Command document** list, choose `AWS-ConfigureAWSPackage`. 1. For **Action**, choose `Install`. 1. For **Name**, enter **AmazonCloudWatchAgent**. 1. For **Version**, enter **latest** if it isn't already provided by default. 1. In the **Targets** section, choose the managed nodes on which you want to run this operation by specifying tags, selecting instances or edge devices manually, or specifying a resource group. **Tip** If a managed node you expect to see isn't listed, see [Troubleshooting managed node availability](fleet-manager-troubleshooting-managed-nodes.md) for troubleshooting tips. 1. For **Rate control**: + For **Concurrency**, specify either a number or a percentage of managed nodes on which to run the command at the same time. **Note** If you selected targets by specifying tags applied to managed nodes or by specifying AWS resource groups, and you aren't certain how many managed nodes are targeted, then restrict the number of targets that can run the document at the same time by specifying a percentage. + For **Error threshold**, specify when to stop running the command on other managed nodes after it fails on either a number or a percentage of nodes. For example, if you specify three errors, then Systems Manager stops sending the command when the fourth error is received. Managed nodes still processing the command might also send errors. 1. (Optional) For **Output options**, to save the command output to a file, select the **Write command output to an S3 bucket** box. Enter the bucket and prefix (folder) names in the boxes. **Note** The S3 permissions that grant the ability to write the data to an S3 bucket are those of the instance profile (for EC2 instances) or IAM service role (hybrid-activated machines) assigned to the instance, not those of the IAM user performing this task. For more information, see [Configure instance permissions required for Systems Manager](setup-instance-permissions.md) or [Create an IAM service role for a hybrid environment](hybrid-multicloud-service-role.md). In addition, if the specified S3 bucket is in a different AWS account, make sure that the instance profile or IAM service role associated with the managed node has the necessary permissions to write to that bucket. 1. In the **SNS notifications** section, if you want notifications sent about the status of the command execution, select the **Enable SNS notifications** check box. For more information about configuring Amazon SNS notifications for Run Command, see [Monitoring Systems Manager status changes using Amazon SNS notifications](monitoring-sns-notifications.md). 1. Choose **Run**. **Two: To update config data JSON format** + To update the JSON formatting of the existing config settings for the CloudWatch agent, use **Run Command**, a tool in AWS Systems Manager, or log in to the node directly with an RDP connection to run the following Windows PowerShell commands on the node, one at a time. ``` cd ${Env:ProgramFiles}\\Amazon\\AmazonCloudWatchAgent ``` ``` .\\amazon-cloudwatch-agent-config-wizard.exe --isNonInteractiveWindowsMigration ``` *\$1Env:ProgramFiles\$1* represents the location where the Amazon directory containing the CloudWatch agent can be found, typically `C:\Program Files`. **Three: To configure and start the CloudWatch agent (console)** 1. Open the AWS Systems Manager console at [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/). 1. In the navigation pane, choose **Run Command**, and then choose **Run command**. 1. In the **Command document** list, choose `AWS-RunPowerShellScript`. 1. For **Commands**, enter the following two commands. ``` cd ${Env:ProgramFiles}\Amazon\AmazonCloudWatchAgent ``` ``` .\amazon-cloudwatch-agent-ctl.ps1 -a fetch-config -m ec2 -c file:config.json -s ``` *\$1Env:ProgramFiles\$1* represents the location where the Amazon directory containing the CloudWatch agent can be found, typically `C:\Program Files`. 1. In the **Targets** section, choose the managed nodes on which you want to run this operation by specifying tags, selecting instances or edge devices manually, or specifying a resource group. **Tip** If a managed node you expect to see isn't listed, see [Troubleshooting managed node availability](fleet-manager-troubleshooting-managed-nodes.md) for troubleshooting tips. 1. For **Rate control**: + For **Concurrency**, specify either a number or a percentage of managed nodes on which to run the command at the same time. **Note** If you selected targets by specifying tags applied to managed nodes or by specifying AWS resource groups, and you aren't certain how many managed nodes are targeted, then restrict the number of targets that can run the document at the same time by specifying a percentage. + For **Error threshold**, specify when to stop running the command on other managed nodes after it fails on either a number or a percentage of nodes. For example, if you specify three errors, then Systems Manager stops sending the command when the fourth error is received. Managed nodes still processing the command might also send errors. 1. (Optional) For **Output options**, to save the command output to a file, select the **Write command output to an S3 bucket** box. Enter the bucket and prefix (folder) names in the boxes. **Note** The S3 permissions that grant the ability to write the data to an S3 bucket are those of the instance profile (for EC2 instances) or IAM service role (hybrid-activated machines) assigned to the instance, not those of the IAM user performing this task. For more information, see [Configure instance permissions required for Systems Manager](setup-instance-permissions.md) or [Create an IAM service role for a hybrid environment](hybrid-multicloud-service-role.md). In addition, if the specified S3 bucket is in a different AWS account, make sure that the instance profile or IAM service role associated with the managed node has the necessary permissions to write to that bucket. 1. In the **SNS notifications** section, if you want notifications sent about the status of the command execution, select the **Enable SNS notifications** check box. For more information about configuring Amazon SNS notifications for Run Command, see [Monitoring Systems Manager status changes using Amazon SNS notifications](monitoring-sns-notifications.md). 1. Choose **Run**. **Four: To turn off log collection in SSM Agent (console)** 1. Open the AWS Systems Manager console at [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/). 1. In the navigation pane, choose **Run Command**, and then choose **Run command**. 1. In the **Command document** list, choose `AWS-ConfigureCloudWatch`. 1. For **Status**, choose **Disabled**. 1. In the **Targets** section, choose the managed nodes on which you want to run this operation by specifying tags, selecting instances or edge devices manually, or specifying a resource group. **Tip** If a managed node you expect to see isn't listed, see [Troubleshooting managed node availability](fleet-manager-troubleshooting-managed-nodes.md) for troubleshooting tips. 1. For **Status**, choose `Disabled`. 1. For **Rate control**: + For **Concurrency**, specify either a number or a percentage of managed nodes on which to run the command at the same time. **Note** If you selected targets by specifying tags applied to managed nodes or by specifying AWS resource groups, and you aren't certain how many managed nodes are targeted, then restrict the number of targets that can run the document at the same time by specifying a percentage. + For **Error threshold**, specify when to stop running the command on other managed nodes after it fails on either a number or a percentage of nodes. For example, if you specify three errors, then Systems Manager stops sending the command when the fourth error is received. Managed nodes still processing the command might also send errors. 1. (Optional) For **Output options**, to save the command output to a file, select the **Write command output to an S3 bucket** box. Enter the bucket and prefix (folder) names in the boxes. **Note** The S3 permissions that grant the ability to write the data to an S3 bucket are those of the instance profile (for EC2 instances) or IAM service role (hybrid-activated machines) assigned to the instance, not those of the IAM user performing this task. For more information, see [Configure instance permissions required for Systems Manager](setup-instance-permissions.md) or [Create an IAM service role for a hybrid environment](hybrid-multicloud-service-role.md). In addition, if the specified S3 bucket is in a different AWS account, make sure that the instance profile or IAM service role associated with the managed node has the necessary permissions to write to that bucket. 1. In the **SNS notifications** section, if you want notifications sent about the status of the command execution, select the **Enable SNS notifications** check box. For more information about configuring Amazon SNS notifications for Run Command, see [Monitoring Systems Manager status changes using Amazon SNS notifications](monitoring-sns-notifications.md). 1. Choose **Run**. After completing these steps, check your logs in CloudWatch to verify you are receiving the metrics, logs, or Windows event logs you expect. If the results are satisfactory, you can optionally [Store CloudWatch agent configuration settings in Parameter Store](#monitoring-cloudwatch-agent-store-config). If the migration isn't successful or the results aren't as expected, you can [Rolling back to log collection with SSM Agent](#monitoring-cloudwatch-agent-roll-back). ## Store CloudWatch agent configuration settings in Parameter Store You can store the contents of an CloudWatch agent configuration file in Parameter Store. By maintaining this configuration data in a parameter, multiple nodes can derive their configuration settings from it, and you avoid having to create or manually update configuration files on your nodes. For example, you can use Run Command to write the contents of the parameter to configuration files on multiple nodes, or use State Manager, a tool in AWS Systems Manager, to help avoid configuration drift in the CloudWatch agent configuration settings across a fleet of nodes. When you run the CloudWatch agent configuration wizard, you can choose to let the wizard save your configuration settings as a new parameter in Parameter Store. For information about running the CloudWatch agent configuration wizard, see [Create the CloudWatch agent configuration file with the wizard](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/create-cloudwatch-agent-configuration-file-wizard.html) in the *Amazon CloudWatch User Guide*. If you ran the wizard but didn't choose the option to save the settings as a parameter, or you created the CloudWatch agent configuration file manually, you can retrieve the data to save as a parameter on your node in the following file. ``` ${Env:ProgramFiles}\Amazon\AmazonCloudWatchAgent\config.json ``` *\$1Env:ProgramFiles\$1* represents the location where the Amazon directory containing the CloudWatch agent can be found, typically `C:\Program Files`. We recommend keeping a backup of the JSON in this file on a location other than the node itself. For information about creating a parameter, see [Creating Parameter Store parameters in Systems Manager](sysman-paramstore-su-create.md). For more information about the CloudWatch agent, see [Collecting metrics and logs from Amazon EC2 instances and on-premises servers with the CloudWatch agent](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Install-CloudWatch-Agent.html) in the *Amazon CloudWatch User Guide*. ## Rolling back to log collection with SSM Agent If you want to return to using SSM Agent for log collection, follow these steps. **One: To retrieve config data from SSM Agent** 1. On the node where you want to return to collecting logs with the SSM Agent, locate the contents of the SSM Agent config file. This JSON file is typically found in the following location: `${Env:ProgramFiles}\\Amazon\\SSM\\Plugins\\awsCloudWatch\\AWS.EC2.Windows.CloudWatch.json` *\$1Env:ProgramFiles\$1* represents the location where the `Amazon` directory can be found, typically `C:\Program Files`. 1. Copy this data into a text file for use in a later step. We recommend storing a backup of the JSON on a location other than the node itself. **Two: To uninstall the CloudWatch agent (console)** 1. Open the AWS Systems Manager console at [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/). 1. In the navigation pane, choose **Run Command**, and then choose **Run command**. 1. In the **Command document** list, choose `AWS-ConfigureAWSPackage`. 1. For **Action**, choose **Uninstall**. 1. For **Name**, enter **AmazonCloudWatchAgent**. 1. In the **Targets** section, choose the managed nodes on which you want to run this operation by specifying tags, selecting instances or edge devices manually, or specifying a resource group. **Tip** If a managed node you expect to see isn't listed, see [Troubleshooting managed node availability](fleet-manager-troubleshooting-managed-nodes.md) for troubleshooting tips. 1. For **Rate control**: + For **Concurrency**, specify either a number or a percentage of managed nodes on which to run the command at the same time. **Note** If you selected targets by specifying tags applied to managed nodes or by specifying AWS resource groups, and you aren't certain how many managed nodes are targeted, then restrict the number of targets that can run the document at the same time by specifying a percentage. + For **Error threshold**, specify when to stop running the command on other managed nodes after it fails on either a number or a percentage of nodes. For example, if you specify three errors, then Systems Manager stops sending the command when the fourth error is received. Managed nodes still processing the command might also send errors. 1. (Optional) For **Output options**, to save the command output to a file, select the **Write command output to an S3 bucket** box. Enter the bucket and prefix (folder) names in the boxes. **Note** The S3 permissions that grant the ability to write the data to an S3 bucket are those of the instance profile (for EC2 instances) or IAM service role (hybrid-activated machines) assigned to the instance, not those of the IAM user performing this task. For more information, see [Configure instance permissions required for Systems Manager](setup-instance-permissions.md) or [Create an IAM service role for a hybrid environment](hybrid-multicloud-service-role.md). In addition, if the specified S3 bucket is in a different AWS account, make sure that the instance profile or IAM service role associated with the managed node has the necessary permissions to write to that bucket. 1. In the **SNS notifications** section, if you want notifications sent about the status of the command execution, select the **Enable SNS notifications** check box. For more information about configuring Amazon SNS notifications for Run Command, see [Monitoring Systems Manager status changes using Amazon SNS notifications](monitoring-sns-notifications.md). 1. Choose **Run**. **Three: To turn log collection back on in SSM Agent (console)** 1. Open the AWS Systems Manager console at [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/). 1. In the navigation pane, choose **Run Command**, and then choose **Run command**. 1. In the **Command document** list, choose `AWS-ConfigureCloudWatch`. 1. For **Status**, choose `Enabled`. 1. For **Properties**, paste the contents of the old config data you saved to the text file. 1. In the **Targets** section, choose the managed nodes on which you want to run this operation by specifying tags, selecting instances or edge devices manually, or specifying a resource group. **Tip** If a managed node you expect to see isn't listed, see [Troubleshooting managed node availability](fleet-manager-troubleshooting-managed-nodes.md) for troubleshooting tips. 1. For **Rate control**: + For **Concurrency**, specify either a number or a percentage of managed nodes on which to run the command at the same time. **Note** If you selected targets by specifying tags applied to managed nodes or by specifying AWS resource groups, and you aren't certain how many managed nodes are targeted, then restrict the number of targets that can run the document at the same time by specifying a percentage. + For **Error threshold**, specify when to stop running the command on other managed nodes after it fails on either a number or a percentage of nodes. For example, if you specify three errors, then Systems Manager stops sending the command when the fourth error is received. Managed nodes still processing the command might also send errors. 1. (Optional) For **Output options**, to save the command output to a file, select the **Write command output to an S3 bucket** box. Enter the bucket and prefix (folder) names in the boxes. **Note** The S3 permissions that grant the ability to write the data to an S3 bucket are those of the instance profile (for EC2 instances) or IAM service role (hybrid-activated machines) assigned to the instance, not those of the IAM user performing this task. For more information, see [Configure instance permissions required for Systems Manager](setup-instance-permissions.md) or [Create an IAM service role for a hybrid environment](hybrid-multicloud-service-role.md). In addition, if the specified S3 bucket is in a different AWS account, make sure that the instance profile or IAM service role associated with the managed node has the necessary permissions to write to that bucket. 1. In the **SNS notifications** section, if you want notifications sent about the status of the command execution, select the **Enable SNS notifications** check box. For more information about configuring Amazon SNS notifications for Run Command, see [Monitoring Systems Manager status changes using Amazon SNS notifications](monitoring-sns-notifications.md). 1. Choose **Run**. # Sending SSM Agent logs to CloudWatch Logs AWS Systems Manager Agent (SSM Agent) is Amazon software that runs on your EC2 instances, edge devices, on-premises servers, and virtual machines (VMs) that are configured for Systems Manager. SSM Agent processes requests from the Systems Manager service in the cloud and configures your machine as specified in the request. For more information about SSM Agent, see [Working with SSM Agent](ssm-agent.md). In addition, using the following steps, you can configure SSM Agent to send log data to Amazon CloudWatch Logs. **Before you begin** Create a log group in CloudWatch Logs. For more information, see [Getting started with CloudWatch Logs](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CWL_GettingStarted.html) in the *Amazon CloudWatch Logs User Guide*. **To configure SSM Agent to send logs to CloudWatch** 1. Log into a node and locate the following file: **Linux** On most Linux node types: `/etc/amazon/ssm/seelog.xml.template`. On Ubuntu Server 20.04, 18.04, and 16.04 LTS: `/snap/amazon-ssm-agent/current/seelog.xml.template` **macOS** `/opt/aws/ssm/seelog.xml.template` **Windows** `%ProgramFiles%\Amazon\SSM\seelog.xml.template` 1. Change the file name from `seelog.xml.template` to `seelog.xml` **Note** On Ubuntu Server 20.04, 18.04, and 16.04 LTS, the file `seelog.xml` must be created in the directory `/etc/amazon/ssm/`. You can create this directory and file by running the following commands. ``` sudo mkdir -p /etc/amazon/ssm ``` ``` sudo cp -pr /snap/amazon-ssm-agent/current/* /etc/amazon/ssm ``` ``` sudo cp -p /etc/amazon/ssm/seelog.xml.template /etc/amazon/ssm/seelog.xml ``` 1. Open the `seelog.xml` file in a text editor, and locate the following section. ------ #### [ Linux and macOS ] ``` ``` ------ #### [ Windows ] ``` ``` ------ 1. Edit the file, and add a *custom name* element after the closing tag. In the following example, the custom name as been specified as `cloudwatch_receiver`. ------ #### [ Linux and macOS ] ``` ``` ------ #### [ Windows ] ``` ``` ------ 1. Save your changes, and then restart SSM Agent or the node. 1. Open the CloudWatch console at [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/). 1. In the navigation pane, choose **Log groups**, and then choose the name of your log group. **Tip** The log stream for SSM Agent log file data is organized by node ID. # Monitoring your change request events **Change Manager availability change** AWS Systems Manager Change Manager will no longer be open to new customers starting November 7, 2025. If you would like to use Change Manager, sign up prior to that date. Existing customers can continue to use the service as normal. For more information, see [AWS Systems Manager Change Manager availability change](https://docs.aws.amazon.com/systems-manager/latest/userguide/change-manager-availability-change.html). After turning on integration with AWS CloudTrail Lake and creating an event data store, you can view auditable details about the change requests that are run in your account or organization. This includes details such as the following: + The identity of the user that initiated the change request + The AWS Regions where the changes were made + The source IP address for the request + The AWS access key used for the request + The API actions run for the change request + The request parameters included for those actions + The resources updated during the process The following are samples of event details you can view for a change request after creating the event data store in AWS CloudTrail Lake. ------ #### [ Details ] The following image shows the high-level information about a change request available on the **Details** tab. These details include information such as the time the change request operation began, the ID of the user that initiated the change request, the impacted AWS Region, and the event ID and request ID associated with the request. ![\[Details of a change request from CloudTrail Lake.\]](http://docs.aws.amazon.com/systems-manager/latest/userguide/images/cm-event-details.png) ------ #### [ Event record ] The following image shows the structure of the JSON content provided by CloudTrail Lake for a change request event. This data is provided on the **Event record** tab in a change request. ![\[JSON record of a change request from CloudTrail Lake.\]](http://docs.aws.amazon.com/systems-manager/latest/userguide/images/cm-event-record.png) ------ **Important** If you're using Change Manager for an organization, you can complete the following procedure while signed in to either the management account or the delegated administrator account for Change Manager. However, to use the delegated administrator account to complete these steps, the same delegated administrator account must be specified for both CloudTrail and Change Manager. When you sign in to the management account for Change Manager, you can add or change the delegated administrator account for CloudTrail on the CloudTrail [Settings](https://console.aws.amazon.com/cloudtrailv2/home#/settings) page. This must be done before the delegated administrator account can create an event data store for use by the entire organization. **To turn on CloudTrail Lake event tracking from Change Manager** 1. Open the AWS Systems Manager console at [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/). 1. In the navigation pane, choose **Change Manager**. 1. Choose the **Requests** tab. 1. Choose any existing change request, and then choose the **Associated events** tab. 1. Choose **Enable CloudTrail Lake**. 1. Follow the steps in [Create an event data store for CloudTrail events](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/query-event-data-store-cloudtrail.html) in the *AWS CloudTrail User Guide*. To ensure that event data for your change requests is stored, make the following selections as you complete the procedure: + For **Event type**, leave the defaults **AWS events** and **CloudTrail events** selected. + If you're using Change Manager with an organization, select **Enable for all accounts in my organization**. + For **Management events**, do not clear the **Write** check box. Other options you choose when creating your event data store don't affect the storage of event data for your change requests. # Monitoring your automations *Metrics* are the fundamental concept in Amazon CloudWatch. A metric represents a time-ordered set of data points that are published to CloudWatch. Think of a metric as a variable to monitor and the data points as representing the values of that variable over time. Automation is a tool in AWS Systems Manager. Systems Manager publishes metrics about Automation usage to CloudWatch. This allows you to set alarms based on those metrics. **To view Automation metrics in the CloudWatch console** 1. Open the CloudWatch console at [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/). 1. In the navigation pane, choose **Metrics**. 1. Choose **SSM**. 1. On the **Metrics** tab, choose **Usage**, and then choose **By AWS Resource**. 1. In the search box near the list of metrics, enter **SSM**. **To view Automation metrics using the AWS CLI** Open a command prompt, and use the following command. ``` aws cloudwatch list-metrics \ --namespace "AWS/Usage" ``` ## Automation metrics Systems Manager sends the following Automation metrics to CloudWatch. | Metric | Description | | --- | --- | | ConcurrentAutomationUsage | The number of automations running at the same time in the current AWS account and AWS Region. | | QueuedAutomationUsage | The number of automations currently queued that have not started and have a status of Pending. | For more information about working with CloudWatch metrics, see the following topics in the *Amazon CloudWatch User Guide*: + [Metrics](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/cloudwatch_concepts.html#Metric) + [Using Amazon CloudWatch metrics](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/working_with_metrics.html) + [Using Amazon CloudWatch alarms](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/AlarmThatSendsEmail.html) # Monitoring Run Command metrics using Amazon CloudWatch *Metrics* are the fundamental concept in Amazon CloudWatch. A metric represents a time-ordered set of data points that are published to CloudWatch. Think of a metric as a variable to monitor, and the data points as representing the values of that variable over time. AWS Systems Manager publishes metrics about the status of Run Command commands to CloudWatch, allowing you to set alarms based on those metrics. Run Command is a tool in AWS Systems Manager. These statistics are recorded for an extended period so you can access historical information and gain a better perspective on the success rate of commands run in your AWS account. The terminal status values for commands for which you can track metrics include `Success`, `Failed`, and `Delivery Timed Out`. For example, for an SSM Command document set to run every hour, you can configure an alarm to notify you when a status of `Success` isn't reported for any of those hours. For more information about command status values, see [Understanding command statuses](monitor-commands.md). **To view metrics in the CloudWatch console** 1. Open the CloudWatch console at [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/). 1. In the navigation pane, choose **Metrics**. 1. In the **Alarms by AWS service** area, for **Services**, choose **SSM-Run Command**. **To view metrics using the AWS CLI** Open a command prompt, and use the following command. ``` aws cloudwatch list-metrics --namespace "AWS/SSM-RunCommand" ``` To list all available metrics, use the following command. ``` aws cloudwatch list-metrics ``` ## Systems Manager Run Command metrics and dimensions Systems Manager sends Run Command command metrics to CloudWatch one time every minute. Systems Manager sends the following command metrics to CloudWatch. **Note** These metrics use `Count` as the unit, so `Sum` and `SampleCount` are the most useful statistics. | Metric | Description | | --- | --- | | CommandsDeliveryTimedOut | The number of commands that have a terminal status of Delivery Timed Out. | | CommandsFailed | The number of commands that have a terminal status of Failed. | | CommandsSucceeded | The number of commands that have a terminal status of Success. | For more information about working with CloudWatch metrics, see the following topics in the *Amazon CloudWatch User Guide*: + [Metrics](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/cloudwatch_concepts.html#Metric) + [Using Amazon CloudWatch metrics](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/working_with_metrics.html) + [Using Amazon CloudWatch alarms](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/AlarmThatSendsEmail.html) # Logging AWS Systems Manager API calls with AWS CloudTrail AWS Systems Manager is integrated with [AWS CloudTrail](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-user-guide.html), a service that provides a record of actions taken by a user, role, or an AWS service. CloudTrail captures all API calls for Systems Manager as events. The calls captured include calls from the Systems Manager console and code calls to the Systems Manager API operations. Using the information collected by CloudTrail, you can determine the request that was made to Systems Manager, the IP address from which the request was made, when it was made, and additional details. Every event or log entry contains information about who generated the request. The identity information helps you determine the following: + Whether the request was made with root user or user credentials. + Whether the request was made on behalf of an IAM Identity Center user. + Whether the request was made with temporary security credentials for a role or federated user. + Whether the request was made by another AWS service. CloudTrail is active in your AWS account when you create the account and you automatically have access to the CloudTrail **Event history**. The CloudTrail **Event history** provides a viewable, searchable, downloadable, and immutable record of the past 90 days of recorded management events in an AWS Region. For more information, see [Working with CloudTrail Event history](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/view-cloudtrail-events.html) in the *AWS CloudTrail User Guide*. There are no CloudTrail charges for viewing the **Event history**. For an ongoing record of events in your AWS account past 90 days, create a trail or a [CloudTrail Lake](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-lake.html) event data store. **CloudTrail trails** A *trail* enables CloudTrail to deliver log files to an Amazon S3 bucket. All trails created using the AWS Management Console are multi-Region. You can create a single-Region or a multi-Region trail by using the AWS CLI. Creating a multi-Region trail is recommended because you capture activity in all AWS Regions in your account. If you create a single-Region trail, you can view only the events logged in the trail's AWS Region. For more information about trails, see [Creating a trail for your AWS account](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-create-and-update-a-trail.html) and [Creating a trail for an organization](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/creating-trail-organization.html) in the *AWS CloudTrail User Guide*. You can deliver one copy of your ongoing management events to your Amazon S3 bucket at no charge from CloudTrail by creating a trail, however, there are Amazon S3 storage charges. For more information about CloudTrail pricing, see [AWS CloudTrail Pricing](https://aws.amazon.com/cloudtrail/pricing/). For information about Amazon S3 pricing, see [Amazon S3 Pricing](https://aws.amazon.com/s3/pricing/). **CloudTrail Lake event data stores** *CloudTrail Lake* lets you run SQL-based queries on your events. CloudTrail Lake converts existing events in row-based JSON format to [ Apache ORC](https://orc.apache.org/) format. ORC is a columnar storage format that is optimized for fast retrieval of data. Events are aggregated into *event data stores*, which are immutable collections of events based on criteria that you select by applying [advanced event selectors](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-lake-concepts.html#adv-event-selectors). The selectors that you apply to an event data store control which events persist and are available for you to query. For more information about CloudTrail Lake, see [Working with AWS CloudTrail Lake](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-lake.html) in the *AWS CloudTrail User Guide*. CloudTrail Lake event data stores and queries incur costs. When you create an event data store, you choose the [pricing option](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-lake-manage-costs.html#cloudtrail-lake-manage-costs-pricing-option) you want to use for the event data store. The pricing option determines the cost for ingesting and storing events, and the default and maximum retention period for the event data store. For more information about CloudTrail pricing, see [AWS CloudTrail Pricing](https://aws.amazon.com/cloudtrail/pricing/). ## Systems Manager data events in CloudTrail [Data events](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/logging-data-events-with-cloudtrail.html#logging-data-events) provide information about the resource operations performed on or in a resource (for example, creating or opening a control channel). These are also known as data plane operations. Data events are often high-volume activities. By default, CloudTrail doesn’t log data events. The CloudTrail **Event history** doesn't record data events. Additional charges apply for data events. For more information about CloudTrail pricing, see [AWS CloudTrail Pricing](https://aws.amazon.com/cloudtrail/pricing/). You can log data events for the Systems Manager resource types by using the CloudTrail console, AWS CLI, or CloudTrail API operations. For more information about how to log data events, see [Logging data events with the AWS Management Console](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/logging-data-events-with-cloudtrail.html#logging-data-events-console) and [Logging data events with the AWS Command Line Interface](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/logging-data-events-with-cloudtrail.html#creating-data-event-selectors-with-the-AWS-CLI) in the *AWS CloudTrail User Guide*. The following table lists the Systems Manager resource types for which you can log data events. The **Data event type (console)** column shows the value to choose from the **Data event type** list on the CloudTrail console. The **resources.type value** column shows the `resources.type` value, which you would specify when configuring advanced event selectors using the AWS CLI or CloudTrail APIs. The **Data APIs logged to CloudTrail** column shows the API calls logged to CloudTrail for the resource type. | Data event type (console) | resources.type value | Data APIs logged to CloudTrail | | --- | --- | --- | | Systems Manager | AWS::SSMMessages::ControlChannel | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/systems-manager/latest/userguide/monitoring-cloudtrail-logs.html) For more information about these operations, see [ Actions defined by Amazon Message Gateway Service](https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazonmessagegatewayservice.html#amazonmessagegatewayservice-actions-as-permissions) in the *Service Authorization Reference*. | | Systems Manager managed node | AWS::SSM::ManagedNode | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/systems-manager/latest/userguide/monitoring-cloudtrail-logs.html)For more information about the `RequestManagedInstanceRoleToken` operation, see [Validating hybrid-activated machines using a hardware fingerprint](ssm-agent-technical-details.md#fingerprint-validation) | You can configure advanced event selectors to filter on the `eventName`, `readOnly`, and `resources.ARN` fields to log only those events that are important to you. For more information about these fields, see [https://docs.aws.amazon.com/awscloudtrail/latest/APIReference/API_AdvancedFieldSelector.html](https://docs.aws.amazon.com/awscloudtrail/latest/APIReference/API_AdvancedFieldSelector.html) in the *AWS CloudTrail API Reference*. ## Systems Manager management events in CloudTrail [Management events](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/logging-management-events-with-cloudtrail.html#logging-management-events) provide information about management operations that are performed on resources in your AWS account. These are also known as control plane operations. By default, CloudTrail logs management events. Systems Manager logs all control plane operations to CloudTrail as management events. Systems Manager API operations are documented in the [AWS Systems Manager API Reference](https://docs.aws.amazon.com/systems-manager/latest/APIReference/Welcome.html). For example, calls to the `CreateMaintenanceWindows`, `PutInventory`, `SendCommand`, and `StartSession` actions generate entries in the CloudTrail log files. For an example of setting up CloudTrail to monitor a Systems Manager API call, see [Monitoring session activity using Amazon EventBridge (console)](session-manager-auditing.md#session-manager-auditing-eventbridge-events). ## Systems Manager event examples An event represents a single request from any source and includes information about the requested API operation, the date and time of the operation, request parameters, and so on. CloudTrail log files aren't an ordered stack trace of the public API calls, so events don't appear in any specific order. **Topics** + [Management event examples](#monitoring-cloudtrail-logs-log-entries-example-mgmt) + [Data event examples](#monitoring-cloudtrail-logs-log-entries-example-data) ### Management event examples **Example 1: `DeleteDocument`** The following example shows a CloudTrail event that demonstrates the `DeleteDocument` operation on a document named `example-Document` in the US East (Ohio) Region (us-east-2). ``` { "eventVersion": "1.04", "userIdentity": { "type": "AssumedRole", "principalId": "AKIAI44QH8DHBEXAMPLE:203.0.113.11", "arn": "arn:aws:sts::123456789012:assumed-role/example-role/203.0.113.11", "accountId": "123456789012", "accessKeyId": "AKIAIOSFODNN7EXAMPLE", "sessionContext": { "attributes": { "mfaAuthenticated": "false", "creationDate": "2018-03-06T20:19:16Z" }, "sessionIssuer": { "type": "Role", "principalId": "AKIAI44QH8DHBEXAMPLE", "arn": "arn:aws:iam::123456789012:role/example-role", "accountId": "123456789012", "userName": "example-role" } } }, "eventTime": "2018-03-06T20:30:12Z", "eventSource": "ssm.amazonaws.com", "eventName": "DeleteDocument", "awsRegion": "us-east-2", "sourceIPAddress": "203.0.113.11", "userAgent": "example-user-agent-string", "requestParameters": { "name": "example-Document" }, "responseElements": null, "requestID": "86168559-75e9-11e4-8cf8-75d18EXAMPLE", "eventID": "832b82d5-d474-44e8-a51d-093ccEXAMPLE", "resources": [ { "ARN": "arn:aws:ssm:us-east-2:123456789012:document/example-Document", "accountId": "123456789012" } ], "eventType": "AwsApiCall", "recipientAccountId": "123456789012", "eventCategory": "Management" } ``` **Example 2: `StartConnection`** The following example shows a CloudTrail event for a user who starts an RDP connection using Fleet Manager in the US East (Ohio) Region (us-east-2). The underlying API action is `StartConnection`. ``` { "eventVersion": "1.08", "userIdentity": { "type": "AssumedRole", "principalId": "AKIAI44QH8DHBEXAMPLE", "arn": "arn:aws:sts::123456789012:assumed-role/exampleRole", "accountId": "123456789012", "accessKeyId": "AKIAIOSFODNN7EXAMPLE", "sessionContext": { "sessionIssuer": { "type": "Role", "principalId": "AKIAI44QH8DHBEXAMPLE", "arn": "arn:aws:sts::123456789012:assumed-role/exampleRole", "accountId": "123456789012", "userName": "exampleRole" }, "webIdFederationData": {}, "attributes": { "creationDate": "2021-12-13T14:57:05Z", "mfaAuthenticated": "false" } } }, "eventTime": "2021-12-13T16:50:41Z", "eventSource": "ssm-guiconnect.amazonaws.com", "eventName": "StartConnection", "awsRegion": "us-east-2", "sourceIPAddress": "34.230.45.60", "userAgent": "example-user-agent-string", "requestParameters": { "AuthType": "Credentials", "Protocol": "RDP", "ConnectionType": "SessionManager", "InstanceId": "i-02573cafcfEXAMPLE" }, "responseElements": { "ConnectionArn": "arn:aws:ssm-guiconnect:us-east-2:123456789012:connection/fcb810cd-241f-4aae-9ee4-02d59EXAMPLE", "ConnectionKey": "71f9629f-0f9a-4b35-92f2-2d253EXAMPLE", "ClientToken": "49af0f92-d637-4d47-9c54-ea51aEXAMPLE", "requestId": "d466710f-2adf-4e87-9464-055b2EXAMPLE" }, "requestID": "d466710f-2adf-4e87-9464-055b2EXAMPLE", "eventID": "fc514f57-ba19-4e8b-9079-c2913EXAMPLE", "readOnly": false, "eventType": "AwsApiCall", "managementEvent": true, "recipientAccountId": "123456789012", "eventCategory": "Management" } ``` ### Data event examples **Example 1: `CreateControlChannel`** The following example shows a CloudTrail event that demonstrates the `CreateControlChannel` operation. ``` { "eventVersion":"1.08", "userIdentity":{ "type":"AssumedRole", "principalId":"AKIAI44QH8DHBEXAMPLE", "arn":"arn:aws:sts::123456789012:assumed-role/exampleRole", "accountId":"123456789012", "accessKeyId":"AKIAI44QH8DHBEXAMPLE", "sessionContext":{ "sessionIssuer":{ "type":"Role", "principalId":"AKIAI44QH8DHBEXAMPLE", "arn":"arn:aws:iam::123456789012:role/exampleRole", "accountId":"123456789012", "userName":"exampleRole" }, "attributes":{ "creationDate":"2023-05-04T23:14:50Z", "mfaAuthenticated":"false" } } }, "eventTime":"2023-05-04T23:53:55Z", "eventSource":"ssm.amazonaws.com", "eventName":"CreateControlChannel", "awsRegion":"us-east-1", "sourceIPAddress":"192.0.2.0", "userAgent":"example-agent", "requestParameters":{ "channelId":"44295c1f-49d2-48b6-b218-96823EXAMPLE", "messageSchemaVersion":"1.0", "requestId":"54993150-0e8f-4142-aa54-3438EXAMPLE", "userAgent":"example-agent" }, "responseElements":{ "messageSchemaVersion":"1.0", "tokenValue":"Value hidden due to security reasons.", "url":"example-url" }, "requestID":"54993150-0e8f-4142-aa54-3438EXAMPLE", "eventID":"a48a28de-7996-4ca1-a3a0-a51fEXAMPLE", "readOnly":false, "resources":[ { "accountId":"123456789012", "type":"AWS::SSMMessages::ControlChannel", "ARN":"arn:aws:ssmmessages:us-east-1:123456789012:control-channel/44295c1f-49d2-48b6-b218-96823EXAMPLE" } ], "eventType":"AwsApiCall", "managementEvent":false, "recipientAccountId":"123456789012", "eventCategory":"Data" } ``` **Example 2: `RequestManagedInstanceRoleToken`** The following example shows a CloudTrail event that demonstrates the `RequestManagedInstanceRoleToken` operation. ``` { "eventVersion": "1.08", "userIdentity": { "type": "AssumedRole", "principalId": "123456789012:aws:ec2-instance:i-02854e4bEXAMPLE", "arn": "arn:aws:sts::123456789012:assumed-role/aws:ec2-instance/i-02854e4bEXAMPLE", "accountId": "123456789012", "accessKeyId": "AKIAI44QH8DHBEXAMPLE", "sessionContext": { "sessionIssuer": { "type": "Role", "principalId": "123456789012:aws:ec2-instance", "arn": "arn:aws:iam::123456789012:role/aws:ec2-instance", "accountId": "123456789012", "userName": "aws:ec2-instance" }, "attributes": { "creationDate": "2023-08-27T03:34:46Z", "mfaAuthenticated": "false" }, "ec2RoleDelivery": "2.0" } }, "eventTime": "2023-08-27T03:37:15Z", "eventSource": "ssm.amazonaws.com", "eventName": "RequestManagedInstanceRoleToken", "awsRegion": "us-east-1", "sourceIPAddress": "192.0.2.0", "userAgent": "Apache-HttpClient/UNAVAILABLE (Java/1.8.0_362)", "requestParameters": { "fingerprint": "i-02854e4bf85EXAMPLE" }, "responseElements": null, "requestID": "2582cced-455b-4189-9b82-7b48EXAMPLE", "eventID": "7f200508-e547-4c27-982d-4da0EXAMLE", "readOnly": true, "resources": [ { "accountId": "123456789012", "type": "AWS::SSM::ManagedNode", "ARN": "arn:aws:ec2:us-east-1:123456789012:instance/i-02854e4bEXAMPLE" } ], "eventType": "AwsApiCall", "managementEvent": false, "recipientAccountId": "123456789012", "eventCategory": "Data" } ``` For information about CloudTrail record contents, see [CloudTrail record contents](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-event-reference-record-contents.html) in the *AWS CloudTrail User Guide*. # Logging Automation action output with CloudWatch Logs Automation, a tool in AWS Systems Manager, integrates with Amazon CloudWatch Logs. You can send the output from `aws:executeScript` actions in your runbooks to the log group you specify. Systems Manager doesn't create a log group or any log streams for documents that don't use `aws:executeScript` actions. If the document does use `aws:executeScript`, the output sent to CloudWatch Logs only pertains to those actions. You can use the `aws:executeScript` action output stored in your CloudWatch Logs log group for debugging and troubleshooting purposes. If you choose a log group that is encrypted, the `aws:executeScript` action output is also encrypted. Logging output from `aws:executeScript` actions is an account-level setting. To send action output to CloudWatch Logs for Amazon owned runbooks, the user or role that runs the automation must have permissions for the following operations: + `logs:CreateLogGroup` + `logs:CreateLogStream` + `logs:DescribeLogGroups` + `logs:DescribeLogStreams` + `logs:PutLogEvents` For runbooks that you own, the same permissions must be added to the IAM service role (or AssumeRole) you use to run the runbook. **To send action output to CloudWatch Logs (console)** 1. Open the AWS Systems Manager console at [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/). 1. In the navigation pane, choose **Automation**. 1. Choose the **Preferences** tab, and then choose **Edit**. 1. Select the check box next to **Send output to CloudWatch Logs**. 1. (Recommended) Select the check box next to **Encrypt log data**. With this option turned on, log data is encrypted using the server-side encryption key specified for the log group. If you don't want to encrypt the log data that is sent to CloudWatch Logs, clear the check box. Clear the check box if encryption isn't allowed on the log group. 1. For **CloudWatch Logs log group**, to specify the existing CloudWatch Logs log group in your AWS account that you want to send action output to, select one of the following: + **Send output to the default log group** – If the default log group doesn't exist (`/aws/ssm/automation/executeScript`), Automation creates it for you. + **Choose from a list of log groups** – Select a log group that has already been created in your account to store action output. + **Enter a log group name** – Enter the name of a log group in the text box that has already been created in your account to store action output. 1. Choose **Save**. **To send action output to CloudWatch Logs (command line)** 1. Open your preferred command line tool and run the following command to update the action output destination. ------ #### [ Linux & macOS ] ``` aws ssm update-service-setting \ --setting-id arn:aws:ssm:region:account-id:servicesetting/ssm/automation/customer-script-log-destination \ --setting-value CloudWatch ``` ------ #### [ Windows ] ``` aws ssm update-service-setting ^ --setting-id arn:aws:ssm:region:account-id:servicesetting/ssm/automation/customer-script-log-destination ^ --setting-value CloudWatch ``` ------ #### [ PowerShell ] ``` Update-SSMServiceSetting ` -SettingId "arn:aws:ssm:region:account-id:servicesetting/ssm/automation/customer-script-log-destination" ` -SettingValue "CloudWatch" ``` ------ There is no output if the command succeeds. 1. Run the following command to specify the log group you want to send action output to. ------ #### [ Linux & macOS ] ``` aws ssm update-service-setting \ --setting-id arn:aws:ssm:region:account-id:servicesetting/ssm/automation/customer-script-log-group-name \ --setting-value my-log-group ``` ------ #### [ Windows ] ``` aws ssm update-service-setting ^ --setting-id arn:aws:ssm:region:account-id:servicesetting/ssm/automation/customer-script-log-group-name ^ --setting-value my-log-group ``` ------ #### [ PowerShell ] ``` Update-SSMServiceSetting ` -SettingId "arn:aws:ssm:region:account-id:servicesetting/ssm/automation/customer-script-log-group-name" ` -SettingValue "my-log-group" ``` ------ There is no output if the command succeeds. 1. Run the following command to view the current service settings for Automation action logging preferences in the current AWS account and AWS Region. ------ #### [ Linux & macOS ] ``` aws ssm get-service-setting \ --setting-id arn:aws:ssm:region:account-id:servicesetting/ssm/automation/customer-script-log-destination ``` ------ #### [ Windows ] ``` aws ssm get-service-setting ^ --setting-id arn:aws:ssm:region:account-id:servicesetting/ssm/automation/customer-script-log-destination ``` ------ #### [ PowerShell ] ``` Get-SSMServiceSetting ` -SettingId "arn:aws:ssm:region:account-id:servicesetting/ssm/automation/customer-script-log-destination" ``` ------ The command returns information like the following. ``` { "ServiceSetting": { "Status": "Customized", "LastModifiedDate": 1613758617.036, "SettingId": "/ssm/automation/customer-script-log-destination", "LastModifiedUser": "arn:aws:sts::123456789012:assumed-role/Administrator/User_1", "SettingValue": "CloudWatch", "ARN": "arn:aws:ssm:us-east-2:123456789012:servicesetting/ssm/automation/customer-script-log-destination" } } ``` # Configuring Amazon CloudWatch Logs for Run Command When you send a command by using Run Command, a tool in AWS Systems Manager, you can specify where you want to send the command output. By default, Systems Manager returns only the first 24,000 characters of the command output. If you want to view the full details of the command output, you can specify an Amazon Simple Storage Service (Amazon S3) bucket. Or you can specify Amazon CloudWatch Logs. If you specify CloudWatch Logs, Run Command periodically sends all command output and error logs to CloudWatch Logs. You can monitor output logs in near real-time, search for specific phrases, values, or patterns, and create alarms based on the search. If you configured your managed node to use the AWS Identity and Access Management (IAM) managed policies `AmazonSSMManagedInstanceCore` and `CloudWatchAgentServerPolicy`, then your node requires no additional configuration to send output to CloudWatch Logs. Choose this option if sending commands from the console, or add the `cloud-watch-output-config` section and `CloudWatchOutputEnabled` parameter if using the AWS Command Line Interface (AWS CLI), AWS Tools for Windows PowerShell, or an API operation. The `cloud-watch-output-config` section and `CloudWatchOutputEnabled` parameter are described in more detail later in this topic. For information about adding policies to an instance profile for EC2 instances, see [Configure instance permissions required for Systems Manager](setup-instance-permissions.md). For information about adding policies to a service role for on-premises servers and virtual machines that you plan to use as managed nodes, see [Create the IAM service role required for Systems Manager in hybrid and multicloud environments](hybrid-multicloud-service-role.md). If you're using a custom policy on your nodes, update the policy on each node to allow Systems Manager to send output and logs to CloudWatch Logs. Add the following policy objects to your custom policy. For more information about updating an IAM policy, see [Editing IAM policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_manage-edit.html) in the *IAM User Guide*. ``` { "Effect": "Allow", "Action": "logs:DescribeLogGroups", "Resource": "*" }, { "Effect":"Allow", "Action":[ "logs:CreateLogGroup", "logs:CreateLogStream", "logs:DescribeLogStreams", "logs:PutLogEvents" ], "Resource":"arn:aws:logs:*:*:log-group:/aws/ssm/*" }, ``` ## Specifying CloudWatch Logs when you send commands To specify CloudWatch Logs as the output when you send a command from the AWS Management Console, choose **CloudWatch Output** in the **Output options** section. Optionally, you can specify the name of CloudWatch Logs group where you want to send command output. If you don't specify a group name, Systems Manager automatically creates a log group for you. The log group uses the following naming format: `/aws/ssm/SystemsManagerDocumentName` If you run commands by using the AWS CLI, specify the `cloud-watch-output-config` section in your command. This section allows you to specify the `CloudWatchOutputEnabled` parameter, and optionally, the `CloudWatchLogGroupName` parameter. Here is an example. ------ #### [ Linux & macOS ] ``` aws ssm send-command \ --instance-ids "instance ID" \ --document-name "AWS-RunShellScript" \ --parameters "commands=echo helloWorld" \ --cloud-watch-output-config "CloudWatchOutputEnabled=true,CloudWatchLogGroupName=log group name" ``` ------ #### [ Windows ] ``` aws ssm send-command ^ --document-name "AWS-RunPowerShellScript" ^ --parameters commands=["echo helloWorld"] ^ --targets "Key=instanceids,Values=an instance ID” ^ --cloud-watch-output-config '{"CloudWatchLogGroupName":"log group name","CloudWatchOutputEnabled":true}' ``` ------ ## Viewing command output in CloudWatch Logs As soon as the command starts to run, Systems Manager sends output to CloudWatch Logs in near-real time. The output in CloudWatch Logs uses the following format: `CommandID/InstanceID/PluginID/stdout` `CommandID/InstanceID/PluginID/stderr` Output from the execution is uploaded every 30 seconds or when the buffer exceeds 200 KB, whichever happens first. **Note** Log streams are only created when output data is available. For example, if there is no error data for an execution, the stderr stream isn't created. Here is an example of the command output as it is displayed in CloudWatch Logs. ``` Group - /aws/ssm/AWS-RunShellScript Streams – 1234-567-8910/i-abcd-efg-hijk/AWS-RunPowerShellScript/stdout 24/1234-567-8910/i-abcd-efg-hijk/AWS-RunPowerShellScript/stderr ``` # Monitoring Systems Manager events with Amazon EventBridge Amazon EventBridge is a serverless event bus service that allows you to connect your applications with data from a variety of sources. EventBridge delivers a stream of real-time data from your own applications, software-as-a-service (SaaS) applications, and AWS services and routes that data to targets such as AWS Lambda. You can set up routing rules to determine where to send your data to build application architectures that react in real time to all of your data sources. EventBridge allows you to build event driven architectures, which are loosely coupled and distributed. EventBridge was formerly called Amazon CloudWatch Events. EventBridge includes new features that allow you to receive events from SaaS partners and your own applications. Existing CloudWatch Events users can access their existing default bus, rules, and events in the new EventBridge console and in the CloudWatch Events console. EventBridge uses the same CloudWatch Events API, so all of your existing CloudWatch Events API usage remains the same. EventBridge can add events from dozens of AWS services to your rules, and targets from over 20 AWS services. EventBridge provides support for both AWS Systems Manager events and Systems Manager targets. **Supported Systems Manager event types** Among the many types of Systems Manager events that EventBridge can detect are: + A just-in-time node access request status update for manual approvals. + A failed just-in-time node access request. + A maintenance window being turned off. + An Automation workflow completing successfully. Automation is a tool in AWS Systems Manager. + A managed node being out of patch compliance. + A parameter value being updated. EventBridge supports events from the following AWS Systems Manager tools: + Just-in-time node access (Events are emitted on a best effort basis.) + Automation (Events are emitted on a best effort basis.) + Change Calendar (Events are emitted on a best effort basis.) + Compliance + Inventory (Events are emitted on a best effort basis.) + Maintenance Windows (Events are emitted on a best effort basis.) + Parameter Store (Events are emitted on a best effort basis.) + Run Command (Events are emitted on a best effort basis.) + State Manager (Events are emitted on a best effort basis.) For complete details about supported Systems Manager event types, see [Reference: Amazon EventBridge event patterns and types for Systems Manager](reference-eventbridge-events.md) and [Amazon EventBridge event examples for Systems Manager](monitoring-systems-manager-event-examples.md). **Supported Systems Manager target types** EventBridge supports the following three Systems Manager tools as targets of an event rule: + Running an Automation workflow + Running a Run Command Command document (Events are emitted on a best effort basis.) + Creating an OpsCenter OpsItem For suggested ways you might use these targets, see [Sample scenarios: Systems Manager targets in Amazon EventBridge rules](monitoring-systems-manager-targets.md). For more information about how to get started with EventBridge and set up rules, see [Getting started with Amazon EventBridge](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-get-started.html) in the *Amazon EventBridge User Guide*. For complete information about working with EventBridge, see the [https://docs.aws.amazon.com/eventbridge/latest/userguide/](https://docs.aws.amazon.com/eventbridge/latest/userguide/). **Topics** + [Configuring EventBridge for Systems Manager events](monitoring-systems-manager-events.md) + [Amazon EventBridge event examples for Systems Manager](monitoring-systems-manager-event-examples.md) + [Sample scenarios: Systems Manager targets in Amazon EventBridge rules](monitoring-systems-manager-targets.md) # Configuring EventBridge for Systems Manager events You can use Amazon EventBridge to perform a target event when supported AWS Systems Manager status changes, state changes, or other conditions occur. You can create a rule that runs whenever there is a state or status transition, or when there is a transition to one or more states that are of interest. The following procedure provides general steps for creating an EventBridge rule that engages when a specified event is emitted by Systems Manager. For a list of procedures in this user guide that address specific scenarios, see **More info** at the end of this topic. **Note** When a service in your AWS account emits an event, it always goes to your account’s default event bus. To write a rule that responds to events from AWS services in your account, associate it with the default event bus. You can create a rule on a custom event bus that looks for events from AWS services, but this rule only engages when you receive such an event from another account through cross-account event delivery. For more information, see [Sending and receiving Amazon EventBridge events between AWS accounts](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-cross-account.html) in the *Amazon EventBridge User Guide*. **To configure EventBridge for Systems Manager events** 1. Open the Amazon EventBridge console at [https://console.aws.amazon.com/events/](https://console.aws.amazon.com/events/). 1. In the navigation pane, choose **Rules**. 1. Choose **Create rule**. 1. Enter a name and description for the rule. A rule can't have the same name as another rule in the same AWS Region and on the same event bus. 1. For **Event bus**, choose the event bus that you want to associate with this rule. If you want this rule to respond to matching events that come from your own AWS account, select **default**. When an AWS service in your account emits an event, it always goes to your account’s default event bus. 1. For **Rule type**, choose **Rule with an event pattern**. 1. Choose **Next**. 1. For **Event source**, choose **AWS events or EventBridge partner events**. 1. In the **Event pattern** section, choose **Event pattern form**. 1. For **Event source**, choose **AWS services**. 1. For **AWS service**, choose **Systems Manager**. 1. For **Event type**, do one of the following: + Choose **All Events**. If you choose **All Events**, all events emitted by Systems Manager will match the rule. Be aware that this option can result in many event target actions. + Choose the type of Systems Manager event to use for this rule. EventBridge supports events from the following AWS Systems Manager tools: + Automation + Change Calendar + Compliance + Inventory + Maintenance Windows + Parameter Store + Run Command + State Manager **Note** For Systems Manager actions that aren't supported by EventBridge, you can choose an AWS API call through CloudTrail to create an event rule that is based on an API call, which are recorded by CloudTrail. For an example, see [Monitoring session activity using Amazon EventBridge (console)](session-manager-auditing.md#session-manager-auditing-eventbridge-events). 1. (Optional) To make the rule more specific, add filter values. For example, if you chose **State Manager** and want to limit the rule to the state of a single managed instance that is targeted by an Association, for **Specific type(s)**, choose **EC2 State Manager Instance Association State Change**. For complete details about supported detail types, see [Reference: Amazon EventBridge event patterns and types for Systems Manager](reference-eventbridge-events.md). Some detail types have other supported options such as status. The available options depend on the tool you selected. 1. Choose **Next**. 1. For **Target types**, choose **AWS service**. 1. For **Select a target**, choose a target such as an Amazon SNS topic or AWS Lambda function. The target is triggered when an event is received that matches the event pattern defined in the rule. 1. For many target types, EventBridge needs permissions to send events to the target. In these cases, EventBridge can create the AWS Identity and Access Management (IAM) role needed for your rule to run: + To create an IAM role automatically, choose **Create a new role for this specific resource**. + To use an IAM role that you created earlier, choose **Use existing role**. 1. (Optional) Choose **Add another target** to add another target for this rule. 1. Choose **Next**. 1. (Optional) Enter one or more tags for the rule. For more information, see [Amazon EventBridge tags](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-tagging.html) in the *Amazon EventBridge User Guide*. 1. Choose **Next**. 1. Review the details of the rule and choose **Create rule**. **More info** + [Creating an EventBridge event that uses a runbook (console)](running-automations-event-bridge.md#automation-cwe-target-console) + [Passing data to Automation using input transformers](automation-tutorial-eventbridge-input-transformers.md) + [Remediating compliance issues using EventBridge](compliance-fixing.md) + [Viewing inventory delete actions in EventBridge](inventory-custom.md#delete-custom-inventory-cwe) + [Configure EventBridge rules to create OpsItems](OpsCenter-automatically-create-OpsItems-2.md) + [Configuring EventBridge rules for parameters and parameter policies](sysman-paramstore-cwe.md#cwe-parameter-changes) # Amazon EventBridge event examples for Systems Manager The following are examples, in JSON format, of supported EventBridge events for AWS Systems Manager. **Topics** + [AWS Systems Manager Automation Events](#SSM-Automation-event-types) + [AWS Systems Manager Change Calendar Events](#SSM-Change-Management-event-types) + [AWS Systems Manager Change Manager Events](#SSM-Change-Manager-event-types) + [AWS Systems Manager Compliance Events](#SSM-Configuration-Compliance-event-types) + [AWS Systems Manager Maintenance Windows Events](#EC2_maintenance_windows_event_types) + [AWS Systems Manager Parameter Store Events](#SSM-Parameter-Store-event-types) + [AWS Systems Manager OpsCenter Events](#SSM-OpsCenter-event-types) + [AWS Systems Manager Run Command Events](#SSM-Run-Command-event-types) + [AWS Systems Manager State Manager Events](#SSM-State-Manager-event-types) ## AWS Systems Manager Automation Events **Automation Step Status-change Notification** ``` { "version": "0", "id": "eeca120b-a321-433e-9635-dab369006a6b", "detail-type": "EC2 Automation Step Status-change Notification", "source": "aws.ssm", "account": "123456789012", "time": "2024-11-29T19:43:35Z", "region": "us-east-1", "resources": ["arn:aws:ssm:us-east-2:123456789012:automation-execution/333ba70b-2333-48db-b17e-a5e69c6f4d1c", "arn:aws:ssm:us-east-2:123456789012:automation-definition/runcommand1:1"], "detail": { "ExecutionId": "333ba70b-2333-48db-b17e-a5e69c6f4d1c", "Definition": "runcommand1", "DefinitionVersion": 1.0, "Status": "Success", "EndTime": "Nov 29, 2024 7:43:25 PM", "StartTime": "Nov 29, 2024 7:43:23 PM", "Time": 2630.0, "StepName": "runFixedCmds", "Action": "aws:runCommand" } } ``` **Automation Execution Status-change Notification** ``` { "version": "0", "id": "d290ece9-1088-4383-9df6-cd5b4ac42b99", "detail-type": "EC2 Automation Execution Status-change Notification", "source": "aws.ssm", "account": "123456789012", "time": "2024-11-29T19:43:35Z", "region": "us-east-2", "resources": ["arn:aws:ssm:us-east-2:123456789012:automation-execution/333ba70b-2333-48db-b17e-a5e69c6f4d1c", "arn:aws:ssm:us-east-2:123456789012:automation-definition/runcommand1:1"], "detail": { "ExecutionId": "333ba70b-2333-48db-b17e-a5e69c6f4d1c", "Definition": "runcommand1", "DefinitionVersion": 1.0, "Status": "Success", "StartTime": "Nov 29, 2024 7:43:20 PM", "EndTime": "Nov 29, 2024 7:43:26 PM", "Time": 5753.0, "ExecutedBy": "arn:aws:iam::123456789012:user/userName" } } ``` ## AWS Systems Manager Change Calendar Events Use the information in this topic to plan and understand the behavior of EventBridge events for AWS Systems Manager Change Calendar. **Note** State changes for calendars shared from other AWS accounts are not currently supported. ### Change Calendar integration with Amazon EventBridge AWS Systems Manager Change Calendar integrates with Amazon EventBridge to notify you of calendar state changes. Be aware of the following behaviors related to the underlying scheduling architecture: Event timing and reliability + EventBridge delivers notifications on a best-effort basis with up to a 15-minute scheduling tolerance. + State change events reflect overall calendar status transitions, not individual calendar events. + When multiple calendar events occur simultaneously, EventBridge generates only one event per actual calendar state change. + EventBridge triggers events only when the calendar's overall state transitions (for example, from CLOSED to OPEN), not for individual calendar events that don't result in a state change. + Advisory events that don't modify the calendar state don't trigger EventBridge notifications. Event modifications and timing considerations + If you modify calendar events within 15 minutes of their scheduled start or end time, EventBridge might generate duplicate notifications or miss notifications. + This behavior occurs because the scheduling system might not have sufficient time to properly update or cancel previously scheduled notifications. + For recurring events, this behavior typically affects only the first occurrence after modification. Adjacent and overlapping events + When calendar events are scheduled within 5 minutes of each other, state transition events might or might not occur, depending on the actual state change. + Creating overlapping events in certain orders might generate additional EventBridge events even when no actual state change occurs. + To ensure predictable behavior, avoid creating or modifying calendar events close to their execution times. Best practices + Design your EventBridge rules and downstream automation to handle potential duplicate events. + Implement idempotency in your automation workflows to prevent issues from duplicate notifications. + Allow sufficient lead time (at least 15 minutes) when you create or modify calendar events. + Test your EventBridge integrations thoroughly with your specific calendar event patterns. **Calendar OPEN** ``` { "version": "0", "id": "47a3f03a-f30d-1011-ac9a-du3bdEXAMPLE", "detail-type": "Calendar State Change", "source": "aws.ssm", "account": "123456789012", "time": "2024-09-19T18:00:07Z", "region": "us-east-2", "resources": [ "arn:aws:ssm:us-east-2:123456789012:document/MyCalendar" ], "detail": { "state": "OPEN", "atTime": "2024-09-19T18:00:07Z", "nextTransitionTime": "2024-10-11T18:00:07Z" } } ``` **Calendar CLOSED** ``` { "version": "0", "id": "f30df03a-1011-ac9a-47a3-f761eEXAMPLE", "detail-type": "Calendar State Change", "source": "aws.ssm", "account": "123456789012", "time": "2024-09-17T21:40:02Z", "region": "us-east-2", "resources": [ "arn:aws:ssm:us-east-2:123456789012:document/MyCalendar" ], "detail": { "state": "CLOSED", "atTime": "2024-08-17T21:40:00Z", "nextTransitionTime": "2024-09-19T18:00:07Z" } } ``` ## AWS Systems Manager Change Manager Events **Change request status update notification - example 1** ``` { "version": "0", "id": "feab80c1-a8ff-c721-b8b1-96ce70939696", "detail-type": "Change Request Status Update", "source": "aws.ssm", "account": "123456789012", "time": "2024-10-24T10:51:52Z", "region": "us-east-1", "resources": [ "arn:aws:ssm:us-west-2:123456789012:opsitem/oi-12345abcdef", "arn:aws:ssm:us-west-2:123456789012:document/MyRunbook1" ], "detail": { "change-request-id": "d0585556-80f6-4522-8dad-dada6d45b67d", "change-request-title": "A change request title", "ops-item-id": "oi-12345abcdef", "ops-item-created-by": "arn:aws:iam::123456789012:user/JohnDoe", "ops-item-created-time": "2024-10-24T10:50:33.180334Z", "ops-item-modified-by": "arn:aws:iam::123456789012:user/JohnDoe", "ops-item-modified-time": "2024-10-24T10:50:33.180340Z", "ops-item-status": "InProgress", "change-template-document-name": "MyChangeTemplate", "runbook-document-arn": "arn:aws:ssm:us-west-2:123456789012:document/MyRunbook1", "runbook-document-version": "1", "auto-approve": true, "approvers": [ "arn:aws:iam::123456789012:user/JaneDoe" ] } } ``` **Change request status update notification - example 2** ``` { "version": "0", "id": "25ce6b03-2e4e-1a2b-2a8f-6c9de8d278d2", "detail-type": "Change Request Status Update", "source": "aws.ssm", "account": "123456789012", "time": "2024-10-24T10:51:52Z", "region": "us-east-1", "resources": [ "arn:aws:ssm:us-west-2:123456789012:opsitem/oi-abcdef12345", "arn:aws:ssm:us-west-2:123456789012:document/MyRunbook1" ], "detail": { "change-request-id": "d0585556-80f6-4522-8dad-dada6d45b67d", "change-request-title": "A change request title", "ops-item-id": "oi-abcdef12345", "ops-item-created-by": "arn:aws:iam::123456789012:user/JohnDoe", "ops-item-created-time": "2024-10-24T10:50:33.180334Z", "ops-item-modified-by": "arn:aws:iam::123456789012:user/JohnDoe", "ops-item-modified-time": "2024-10-24T10:50:33.997163Z", "ops-item-status": "Rejected", "change-template-document-name": "MyChangeTemplate", "runbook-document-arn": "arn:aws:ssm:us-west-2:123456789012:document/MyRunbook1", "runbook-document-version": "1", "auto-approve": true, "approvers": [ "arn:aws:iam::123456789012:user/JaneDoe" ] } } ``` ## AWS Systems Manager Compliance Events The following are examples of the events for AWS Systems Manager Compliance. **Association Compliant** ``` { "version": "0", "id": "01234567-0123-0123-0123-012345678901", "detail-type": "Configuration Compliance State Change", "source": "aws.ssm", "account": "123456789012", "time": "2024-07-17T19:03:26Z", "region": "us-east-2", "resources": [ "arn:aws:ssm:us-east-2:123456789012:managed-instance/i-01234567890abcdef" ], "detail": { "last-runtime": "2024-01-01T10:10:10Z", "compliance-status": "compliant", "resource-type": "managed-instance", "resource-id": "i-01234567890abcdef", "compliance-type": "Association" } } ``` **Association Non-Compliant** ``` { "version": "0", "id": "01234567-0123-0123-0123-012345678901", "detail-type": "Configuration Compliance State Change", "source": "aws.ssm", "account": "123456789012", "time": "2024-07-17T19:02:31Z", "region": "us-east-2", "resources": [ "arn:aws:ssm:us-east-2:123456789012:managed-instance/i-01234567890abcdef" ], "detail": { "last-runtime": "2024-01-01T10:10:10Z", "compliance-status": "non_compliant", "resource-type": "managed-instance", "resource-id": "i-01234567890abcdef", "compliance-type": "Association" } } ``` **Patch Compliant** ``` { "version": "0", "id": "01234567-0123-0123-0123-012345678901", "detail-type": "Configuration Compliance State Change", "source": "aws.123456789012", "account": "123456789012", "time": "2024-07-17T19:03:26Z", "region": "us-east-2", "resources": [ "arn:aws:ssm:us-east-2:123456789012:managed-instance/i-01234567890abcdef" ], "detail": { "resource-type": "managed-instance", "resource-id": "i-01234567890abcdef", "compliance-status": "compliant", "compliance-type": "Patch", "patch-baseline-id": "PB789", "severity": "critical" } } ``` **Patch Non-Compliant** ``` { "version": "0", "id": "01234567-0123-0123-0123-012345678901", "detail-type": "Configuration Compliance State Change", "source": "aws.ssm", "account": "123456789012", "time": "2024-07-17T19:02:31Z", "region": "us-east-2", "resources": [ "arn:aws:ssm:us-east-2:123456789012:managed-instance/i-01234567890abcdef" ], "detail": { "resource-type": "managed-instance", "resource-id": "i-01234567890abcdef", "compliance-status": "non_compliant", "compliance-type": "Patch", "patch-baseline-id": "PB789", "severity": "critical" } } ``` ## AWS Systems Manager Maintenance Windows Events The following are examples of the events for Systems Manager Maintenance Windows. **Register a Target** Valid status values include `REGISTERED` and `DEREGISTERED`. ``` { "version":"0", "id":"01234567-0123-0123-0123-0123456789ab", "detail-type":"Maintenance Window Target Registration Notification", "source":"aws.ssm", "account":"123456789012", "time":"2024-11-16T00:58:37Z", "region":"us-east-2", "resources":[ "arn:aws:ssm:us-east-2:123456789012:maintenancewindow/mw-0ed7251d3fcf6e0c2", "arn:aws:ssm:us-east-2:123456789012:windowtarget/e7265f13-3cc5-4f2f-97a9-7d3ca86c32a6" ], "detail":{ "window-target-id":"e7265f13-3cc5-4f2f-97a9-7d3ca86c32a6", "window-id":"mw-0ed7251d3fcf6e0c2", "status":"REGISTERED" } } ``` **Window Execution Type** Valid status values include the following: + `CANCELLED` + `CANCELLING` + `FAILED` + `IN_PROGRESS` + `PENDING` + `SKIPPED_OVERLAPPING` + `SUCCESS TIMED_OUT` ``` { "version":"0", "id":"01234567-0123-0123-0123-0123456789ab", "detail-type":"Maintenance Window Execution State-change Notification", "source":"aws.ssm", "account":"123456789012", "time":"2025-06-02T14:52:18Z", "region":"us-east-2", "resources":[ "arn:aws:ssm:us-east-2:123456789012:maintenancewindow/mw-0c50858d01EXAMPLE" ], "detail":{ "start-time":"2025-06-02T14:48:28.039273Z", "end-time":"2025-06-02T14:52:18.083773Z", "window-id":"mw-0ed7251d3fcf6e0c2", "window-execution-id":"14bea65d-5ccc-462d-a2f3-e99c8EXAMPLE", "status":"SUCCESS" } } ``` **Task Execution Type** Valid status values include `IN_PROGRESS`, `SUCCESS`, `FAILED`, and `TIMED_OUT`. ``` { "version":"0", "id":"01234567-0123-0123-0123-0123456789ab", "detail-type":"Maintenance Window Task Execution State-change Notification", "source":"aws.ssm", "account":"123456789012", "time":"2025-06-02T14:52:18Z", "region":"us-east-2", "resources":[ "arn:aws:ssm:us-east-2:123456789012:maintenancewindow/mw-0c50858d01EXAMPLE" ], "detail":{ "start-time":"2025-06-02T14:48:28.039273Z", "task-execution-id":"6417e808-7f35-4d1a-843f-123456789012", "end-time":"2025-06-02T14:52:18.083773Z", "window-id":"mw-0ed7251d3fcf6e0c2", "window-execution-id":"14bea65d-5ccc-462d-a2f3-e99c8EXAMPLE", "status":"SUCCESS" } } ``` **Task Target Processed** Valid status values include `IN_PROGRESS`, `SUCCESS`, `FAILED`, and `TIMED_OUT`. ``` { "version":"0", "id":"01234567-0123-0123-0123-0123456789ab", "detail-type":"Maintenance Window Task Target Invocation State-change Notification", "source":"aws.ssm", "account":"123456789012", "time":"2025-06-02T14:52:18Z", "region":"us-east-2", "resources":[ "arn:aws:ssm:us-east-2:123456789012:maintenancewindow/mw-123456789012345678" ], "detail":{ "start-time":"2025-06-02T14:48:28.039273Z", "end-time":"2025-06-02T14:52:18.083773Z", "window-id":"mw-0ed7251d3fcf6e0c2", "window-execution-id":"791b72e0-f0da-4021-8b35-f95dfEXAMPLE", "task-execution-id":"c9b05aba-197f-4d8d-be34-e73fbEXAMPLE", "window-target-id":"e32eecb2-646c-4f4b-8ed1-205fbEXAMPLE", "status":"SUCCESS", "owner-information":"Owner" } } ``` **Window State Change** Valid status values include `ENABLED` and `DISABLED`. ``` { "version":"0", "id":"01234567-0123-0123-0123-0123456789ab", "detail-type":"Maintenance Window State-change Notification", "source":"aws.ssm", "account":"123456789012", "time":"2024-11-16T00:58:37Z", "region":"us-east-2", "resources":[ "arn:aws:ssm:us-east-2:123456789012:maintenancewindow/mw-0c50858d01EXAMPLE" ], "detail":{ "window-id":"mw-0c50858d01EXAMPLE", "status":"DISABLED" } } ``` ## AWS Systems Manager Parameter Store Events The following are examples of the events for Systems Manager Parameter Store. **Create Parameter** ``` { "version": "0", "id": "6a7e4feb-b491-4cf7-a9f1-bf3703497718", "detail-type": "Parameter Store Change", "source": "aws.ssm", "account": "123456789012", "time": "2024-05-22T16:43:48Z", "region": "us-east-2", "resources": [ "arn:aws:ssm:us-east-2:123456789012:parameter/MyExampleParameter" ], "detail": { "operation": "Create", "name": "MyExampleParameter", "type": "String", "description": "Sample Parameter" } } ``` **Update Parameter** ``` { "version": "0", "id": "9547ef2d-3b7e-4057-b6cb-5fdf09ee7c8f", "detail-type": "Parameter Store Change", "source": "aws.ssm", "account": "123456789012", "time": "2024-05-22T16:44:48Z", "region": "us-east-2", "resources": [ "arn:aws:ssm:us-east-2:123456789012:parameter/MyExampleParameter" ], "detail": { "operation": "Update", "name": "MyExampleParameter", "type": "String", "description": "Sample Parameter" } } ``` **Delete Parameter** ``` { "version": "0", "id": "80e9b391-6a9b-413c-839a-453b528053af", "detail-type": "Parameter Store Change", "source": "aws.ssm", "account": "123456789012", "time": "2024-05-22T16:45:48Z", "region": "us-east-2", "resources": [ "arn:aws:ssm:us-east-2:123456789012:parameter/MyExampleParameter" ], "detail": { "operation": "Delete", "name": "MyExampleParameter", "type": "String", "description": "Sample Parameter" } } ``` ## AWS Systems Manager OpsCenter Events **OpsCenter OpsItem create notification** ``` { "version": "0", "id": "aae66adc-7aac-f0c0-7854-7691e8c079b8", "detail-type": "OpsItem Create", "source": "aws.ssm", "account": "123456789012", "time": "2024-10-19T02:48:11Z", "region": "us-east-1", "resources": [ "arn:aws:ssm:us-west-2:123456789012:opsitem/oi-123456abcdef" ], "detail": { "created-by": "arn:aws:iam::123456789012:user/JohnDoe", "created-time": "2024-10-19T02:46:53.629361Z", "source": "aws.ssm", "status": "Open", "ops-item-id": "oi-123456abcdef", "title": "An issue title", "ops-item-type": "/aws/issue", "description": "A long description may appear here" } } ``` **OpsCenter OpsItem update notification** ``` { "version": "0", "id": "2fb5b168-b725-41dd-a890-29311200089c", "detail-type": "OpsItem Update", "source": "aws.ssm", "account": "123456789012", "time": "2024-10-19T02:48:11Z", "region": "us-east-1", "resources": [ "arn:aws:ssm:us-west-2:123456789012:opsitem/oi-123456abcdef" ], "detail": { "created-by": "arn:aws:iam::123456789012:user/JohnDoe", "created-time": "2024-10-19T02:46:54.049271Z", "modified-by": "arn:aws:iam::123456789012:user/JohnDoe", "modified-time": "2024-10-19T02:46:54.337354Z", "source": "aws.ssm", "status": "Open", "ops-item-id": "oi-123456abcdef", "title": "An issue title", "ops-item-type": "/aws/issue", "description": "A long description may appear here" } } ``` ## AWS Systems Manager Run Command Events **Run Command Status-change Notification** ``` { "version": "0", "id": "51c0891d-0e34-45b1-83d6-95db273d1602", "detail-type": "EC2 Command Status-change Notification", "source": "aws.ssm", "account": "123456789012", "time": "2024-07-10T21:51:32Z", "region": "us-east-2", "resources": ["arn:aws:ec2:us-east-2:123456789012:instance/i-02573cafcfEXAMPLE"], "detail": { "command-id": "e8d3c0e4-71f7-4491-898f-c9b35bee5f3b", "document-name": "AWS-RunPowerShellScript", "expire-after": "2024-07-14T22:01:30.049Z", "parameters": { "executionTimeout": ["3600"], "commands": ["date"] }, "requested-date-time": "2024-07-10T21:51:30.049Z", "status": "Success" } } ``` **Run Command Invocation Status-change Notification** ``` { "version": "0", "id": "4780e1b8-f56b-4de5-95f2-95dbEXAMPLE", "detail-type": "EC2 Command Invocation Status-change Notification", "source": "aws.ssm", "account": "123456789012", "time": "2024-07-10T21:51:32Z", "region": "us-east-2", "resources": ["arn:aws:ec2:us-east-2:123456789012:instance/i-02573cafcfEXAMPLE"], "detail": { "command-id": "e8d3c0e4-71f7-4491-898f-c9b35bee5f3b", "document-name": "AWS-RunPowerShellScript", "instance-id": "i-02573cafcfEXAMPLE", "requested-date-time": "2024-07-10T21:51:30.049Z", "status": "Success" } } ``` ## AWS Systems Manager State Manager Events **State Manager Association State Change** ``` { "version":"0", "id":"db839caf-6f6c-40af-9a48-25b2ae2b7774", "detail-type":"EC2 State Manager Association State Change", "source":"aws.ssm", "account":"123456789012", "time":"2024-05-16T23:01:10Z", "region":"us-east-2", "resources":[ "arn:aws:ssm:us-east-2::document/AWS-RunPowerShellScript" ], "detail":{ "association-id":"6e37940a-23ba-4ab0-9b96-5d0a1a05464f", "document-name":"AWS-RunPowerShellScript", "association-version":"1", "document-version":"Optional.empty", "targets":"[{\"key\":\"InstanceIds\",\"values\":[\"i-12345678\"]}]", "creation-date":"2024-02-13T17:22:54.458Z", "last-successful-execution-date":"2024-05-16T23:00:01Z", "last-execution-date":"2024-05-16T23:00:01Z", "last-updated-date":"2024-02-13T17:22:54.458Z", "status":"Success", "association-status-aggregated-count":"{\"Success\":1}", "schedule-expression":"cron(0 */30 * * * ? *)", "association-cwe-version":"1.0" } } ``` **State Manager Instance Association State Change** ``` { "version":"0", "id":"6a7e8feb-b491-4cf7-a9f1-bf3703467718", "detail-type":"EC2 State Manager Instance Association State Change", "source":"aws.ssm", "account":"123456789012", "time":"2024-02-23T15:23:48Z", "region":"us-east-2", "resources":[ "arn:aws:ec2:us-east-2:123456789012:instance/i-12345678", "arn:aws:ssm:us-east-2:123456789012:document/my-custom-document" ], "detail":{ "association-id":"34fcb7e0-9a14-4984-9989-0e04e3f60bd8", "instance-id":"i-02573cafcfEXAMPLE", "document-name":"my-custom-document", "document-version":"1", "targets":"[{\"key\":\"instanceids\",\"values\":[\"i-02573cafcfEXAMPLE\"]}]", "creation-date":"2024-02-23T15:23:48Z", "last-successful-execution-date":"2024-02-23T16:23:48Z", "last-execution-date":"2024-02-23T16:23:48Z", "status":"Success", "detailed-status":"", "error-code":"testErrorCode", "execution-summary":"testExecutionSummary", "output-url":"sampleurl", "instance-association-cwe-version":"1" } } ``` # Sample scenarios: Systems Manager targets in Amazon EventBridge rules When you specify the target to invoke in an Amazon EventBridge rule, you can choose from over 20 target types and add up to five targets to each rule. Of the various targets, you can choose from Automation, OpsCenter, and Run Command, which are tools in AWS Systems Manager, as target actions when an EventBridge event occurs. The following are several examples of ways you can use these tools as the target of an EventBridge rule. **Automation examples** You can configure an EventBridge rule to start Automation workflows when events such as the following occur: + When an Amazon CloudWatch alarm reports that a managed node has failed a status check (`StatusCheckFailed_Instance=1`), run the `AWSSupport-ExecuteEC2Rescue` Automation runbook on the node. + When an `EC2 Instance State-change Notification` event occurs because a new Amazon Elastic Compute Cloud (Amazon EC2) instance is running, run the `AWS-AttachEBSVolume` Automation runbook on the instance. + When an Amazon Elastic Block Store (Amazon EBS) volume is created and available, run the `AWS-CreateSnapshot` Automation runbook on the volume. **OpsCenter examples** You can configure an EventBridge rule to create a new OpsItem when incidents such as the following occur: + A throttling event for Amazon DynamoDB occurs, or Amazon EBS volume performance has degraded. + An Amazon EC2 Auto Scaling group fails to launch a node, or a Systems Manager Automation workflow fails. + An EC2 instance changes state from `Running` to `Stopped`. **Run Command examples** You can configure an EventBridge rule to run a Systems Manager Command document in Run Command when events such as the following occur: + When an Auto Scaling group is about to end, a Run Command script could capture the log files from the node before it is ended. + When a new node is created in an Auto Scaling group, a Run Command target action could turn on the web server role or install software on the node. + When a managed node is found to be out of compliance, a Run Command target action could update patches on the node by running the `AWS-RunPatchBaseline` document. # Monitoring Systems Manager status changes using Amazon SNS notifications You can configure Amazon Simple Notification Service (Amazon SNS) to send notifications about the status of commands that you send using Run Command or Maintenance Windows, which are tools in AWS Systems Manager. Amazon SNS coordinates and manages sending and delivering notifications to clients or endpoints that are subscribed to Amazon SNS topics. You can receive a notification whenever a command changes to a new state or to a specific state, such as *Failed* or *Timed Out*. In cases where you send a command to multiple nodes, you can receive a notification for each copy of the command sent to a specific node. Each copy is called an *invocation*. Amazon SNS can deliver notifications as HTTP or HTTPS POST, email (SMTP, either plaintext or in JSON format), or as a message posted to an Amazon Simple Queue Service (Amazon SQS) queue. For more information, see [What is Amazon SNS](https://docs.aws.amazon.com/sns/latest/dg/) in the *Amazon Simple Notification Service Developer Guide*. For examples of the structure of the JSON data included in the Amazon SNS notification provided by Run Command and Maintenance Windows, see [Example Amazon SNS notifications for AWS Systems Manager](monitoring-sns-examples.md). **Important** Note the following important information. Amazon Simple Notification Service FIFO topics aren't supported. Amazon Q Developer in chat applications isn't supported for monitoring Systems Manager with Amazon SNS. If you wish to use Amazon Q Developer in chat applications to monitor Systems Manager, you must use it with Amazon EventBridge. For information about monitoring Systems Manager using EventBridge, see [Monitoring Systems Manager events with Amazon EventBridge](monitoring-eventbridge-events.md). For information about Amazon EventBridge and Amazon Q Developer in chat applications, see [Tutorial: Creating an EventBridge rule that sends notifications to Amazon Q Developer in chat applications](https://docs.aws.amazon.com/chatbot/latest/adminguide/create-eventbridge-rule.html) in the *Amazon Q Developer in chat applications Administrator Guide*. ## Configure Amazon SNS notifications for AWS Systems Manager Run Command and Maintenance Windows tasks that are registered to a maintenance window can send Amazon SNS notifications for command tasks that enter the following statuses: + In Progress + Success + Failed + Timed Out + Cancelled For information about the conditions that cause a command to enter one of these statuses, see [Understanding command statuses](monitor-commands.md). **Note** Commands sent using Run Command also report Canceling and Pending status. These statuses aren't captured by Amazon SNS notifications. ### Command summary Amazon SNS notifications If you configure Run Command or a Run Command task in your maintenance window for Amazon SNS notifications, Amazon SNS sends summary messages that include the following information. **** | Field | Type | Description | | --- | --- | --- | | eventTime | String | The time that the event was initiated. The timestamp is important because Amazon SNS doesn't guarantee message delivery order. Example: 2016-04-26T13:15:30Z | | documentName | String | The name of the SSM document used to run this command. | | commandId | String | The ID generated by Run Command after the command was sent. | | expiresAfter | Date | If this time is reached and the command hasn't already started executing, it won't run. | | outputS3BucketName | String | The Amazon Simple Storage Service (Amazon S3) bucket where the responses to the command execution should be stored. | | outputS3KeyPrefix | String | The Amazon S3 directory path inside the bucket where the responses to the command execution should be stored. | | requestedDateTime | String | The time and date that the request was sent to this specific node. | | instanceIds | StringList | The nodes that were targeted by the command. Instance IDs are only included in the summary message if the Run Command task targeted instance IDs directly. Instance IDs aren't included in the summary message if the Run Command task was issued using tag-based targeting. | | status | String | Command status for the command. | ### Invocation-based Amazon SNS notifications If you send a command to multiple nodes, Amazon SNS can send messages about each copy or invocation of the command. The messages include the following information. **** | Field | Type | Description | | --- | --- | --- | | eventTime | String | The time that the event was initiated. The timestamp is important because Amazon SNS doesn't guarantee message delivery order. Example: 2016-04-26T13:15:30Z | | documentName | String | The name of the Systems Manager document (SSM document) used to run this command. | | requestedDateTime | String | The time and date that the request was sent to this specific node. | | commandId | String | The ID generated by Run Command after the command was sent. | | instanceId | String | The instance that was targeted by the command. | | status | String | Command status for this invocation. | To set up Amazon SNS notifications when a command changes status, complete the following tasks. **Note** If you aren't configuring Amazon SNS notifications for your maintenance window, then you can skip Task 5 later in this topic. **Topics** + [Command summary Amazon SNS notifications](#monitoring-sns-configure-summary) + [Invocation-based Amazon SNS notifications](#monitoring-sns-configure-invocation) + [Task 1: Create and subscribe to an Amazon SNS topic](#monitoring-configure-sns) + [Task 2: Create an IAM policy for Amazon SNS notifications](#monitoring-iam-policy) + [Task 3: Create an IAM role for Amazon SNS notifications](#monitoring-iam-notifications) + [Task 4: Configure user access](#monitoring-sns-passpolicy) + [Task 5: Attach the iam:PassRole policy to your maintenance window role](#monitoring-sns-passpolicy-mw) ### Task 1: Create and subscribe to an Amazon SNS topic An Amazon SNS *topic* is a communication channel that Run Command and Run Command tasks that are registered to a maintenance window use to send notifications about the status of your commands. Amazon SNS supports different communication protocols, including HTTP/S, email, and other AWS services like Amazon Simple Queue Service (Amazon SQS). To get started, we recommend that you start with the email protocol. For information about how to create a topic, see [Creating an Amazon SNS topic](https://docs.aws.amazon.com/sns/latest/dg/sns-create-topic.html) in the *Amazon Simple Notification Service Developer Guide*. **Note** After you create the topic, copy or make a note of the **Topic ARN**. You specify this ARN when you send a command that is configured to return status notifications. After you create the topic, subscribe to it by specifying an **Endpoint**. If you chose the Email protocol, the endpoint is the email address where you want to receive notifications. For more information about how to subscribe to a topic, see [Subscribing to an Amazon SNS topic](https://docs.aws.amazon.com/sns/latest/dg/sns-create-subscribe-endpoint-to-topic.html) in the *Amazon Simple Notification Service Developer Guide*. Amazon SNS sends a confirmation email from *AWS Notifications* to the email address that you specify. Open the email and choose the **Confirm subscription** link. You will receive an acknowledgement message from AWS. Amazon SNS is now configured to receive notifications and send the notification as an email to the email address that you specified. ### Task 2: Create an IAM policy for Amazon SNS notifications Use the following procedure to create a custom AWS Identity and Access Management (IAM) policy that provides permissions for inititating Amazon SNS notifications. **To create a custom IAM policy for Amazon SNS notifications** 1. Open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/). 1. In the navigation pane, choose **Policies**, and then choose **Create Policy**. (If a **Get Started** button is shown, choose it, and then choose **Create Policy**.) 1. Choose the **JSON** tab. 1. Replace the default content with one of the following, depending on whether the Amazon SNS topic uses AWS KMS encryption: ------ #### [ SNS topic not encrypted ] ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "sns:Publish" ], "Resource": "arn:aws:sns:us-east-1:111122223333:sns-topic-name" } ] } ``` ------ *region* represents the identifier for an AWS Region supported by AWS Systems Manager, such as `us-east-2` for the US East (Ohio) Region. For a list of supported *region* values, see the **Region** column in [Systems Manager service endpoints](https://docs.aws.amazon.com/general/latest/gr/ssm.html#ssm_region) in the *Amazon Web Services General Reference*. **account-id** represents the 12-digit identifier for your AWS account, in the format `123456789012`. *sns-topic-name* represents the name of the Amazon SNS topic you want to use for publishing notifications. ------ #### [ SNS topic encrypted ] ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "sns:Publish" ], "Resource": "arn:aws:sns:us-east-1:111122223333:sns-topic-name" }, { "Effect": "Allow", "Action": [ "kms:GenerateDataKey", "kms:Decrypt" ], "Resource": "arn:aws:kms:us-east-1:111122223333:key/kms-key-id" } ] } ``` ------ *region* represents the identifier for an AWS Region supported by AWS Systems Manager, such as `us-east-2` for the US East (Ohio) Region. For a list of supported *region* values, see the **Region** column in [Systems Manager service endpoints](https://docs.aws.amazon.com/general/latest/gr/ssm.html#ssm_region) in the *Amazon Web Services General Reference*. **account-id** represents the 12-digit identifier for your AWS account, in the format `123456789012`. *sns-topic-name* represents the name of the Amazon SNS topic you want to use for publishing notifications. *kms-key-id* represents the ID of the symmetric encryption KMS key in AWS KMS to use for encrypting and decrypting the topic, in the format `1234abcd-12ab-34cd-56ef-12345EXAMPLE`. **Note** There is a charge for using AWS KMS encryption. For more information, see [Managing Amazon SNS encryption keys and costs](https://docs.aws.amazon.com/sns/latest/dg/sns-key-management.html) in the *AWS Key Management Service Developer Guide*. ------ 1. Choose **Next: Tags**. 1. (Optional) Add one or more tag-key value pairs to organize, track, or control access for this policy. 1. Choose **Next: Review**. 1. On the **Review policy** page, for **Name**, enter a name for the inline policy. For example: **my-sns-publish-permissions**. 1. (Optional) For **Description**, enter a description for the policy. 1. Choose **Create policy**. ### Task 3: Create an IAM role for Amazon SNS notifications Use the following procedure to create an IAM role for Amazon SNS notifications. This service role is used by Systems Manager to initiate Amazon SNS notifications. In all subsequent procedures, this role is referred to as the Amazon SNS IAM role. **To create an IAM service role for Amazon SNS notifications** 1. Sign in to the AWS Management Console and open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/). 1. In the navigation pane of the IAM console, choose **Roles**, and then choose **Create role**. 1. Choose the **AWS service** role type, and then choose Systems Manager. 1. Choose the Systems Manager use case. Then, choose **Next**. 1. On the **Attach permissions policies** page, select the box to the left of the name of the custom policy you created in Task 2. For example: **my-sns-publish-permissions**. 1. (Optional) Set a [permissions boundary](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_boundaries.html). This is an advanced feature that is available for service roles, but not service-linked roles. Expand the **Permissions boundary** section and choose **Use a permissions boundary to control the maximum role permissions**. IAM includes a list of the AWS managed and customer managed policies in your account. Select the policy to use for the permissions boundary or choose **Create policy** to open a new browser tab and create a new policy from scratch. For more information, see [Creating IAM policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html#access_policies_create-start) in the *IAM User Guide*. After you create the policy, close that tab and return to your original tab to select the policy to use for the permissions boundary. 1. Choose **Next**. 1. If possible, enter a role name or role name suffix to help you identify the purpose of this role. Role names must be unique within your AWS account. They are not distinguished by case. For example, you cannot create roles named both **PRODROLE** and **prodrole**. Because various entities might reference the role, you cannot edit the name of the role after it has been created. 1. (Optional) For **Description**, enter a description for the new role. 1. Choose **Edit** in the **Step 1: Select trusted entities** or **Step 2: Select permissions** sections to edit the use cases and permissions for the role. 1. (Optional) Add metadata to the user by attaching tags as key-value pairs. For more information about using tags in IAM, see [Tagging IAM resources](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_tags.html) in the *IAM User Guide*. 1. Review the role and then choose **Create role**. 1. Choose the name of the role, and then copy or make a note of the **Role ARN** value. This Amazon Resource Name (ARN) for the role is used when you send a command that is configured to return Amazon SNS notifications. 1. Keep the **Summary** page open. ### Task 4: Configure user access If an IAM entity (user, role, or group) is assigned administrator permissions, then the user or role has access to Run Command and Maintenance Windows, tools in AWS Systems Manager. For entities without administrator permissions, an administrator must grant the following permissions to the IAM entity: + The `AmazonSSMFullAccess` managed policy, or a policy that provides comparable permissions. + `iam:PassRole` permissions for the role created in [Task 3: Create an IAM role for Amazon SNS notifications](#monitoring-iam-notifications). For example: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "iam:PassRole", "Resource": "arn:aws:iam::111122223333:role/sns-role-name", "Condition": { "StringEquals": { "iam:PassedToService": "ssm.amazonaws.com" } } } ] } ``` ------ To provide access, add permissions to your users, groups, or roles: + Users and groups in AWS IAM Identity Center: Create a permission set. Follow the instructions in [Create a permission set](https://docs.aws.amazon.com//singlesignon/latest/userguide/howtocreatepermissionset.html) in the *AWS IAM Identity Center User Guide*. + Users managed in IAM through an identity provider: Create a role for identity federation. Follow the instructions in [Create a role for a third-party identity provider (federation)](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_roles_create_for-idp.html) in the *IAM User Guide*. + IAM users: + Create a role that your user can assume. Follow the instructions in [Create a role for an IAM user](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_roles_create_for-user.html) in the *IAM User Guide*. + (Not recommended) Attach a policy directly to a user or add a user to a user group. Follow the instructions in [Adding permissions to a user (console)](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_users_change-permissions.html#users_change_permissions-add-console) in the *IAM User Guide*. **To configure user access and attach the `iam:PassRole` policy to a user account** 1. In the IAM navigation pane, choose **Users**, and then choose the user account that you want to configure. 1. On the **Permissions** tab, in the policies list, verify that either the **AmazonSSMFullAccess** policy is listed or that there is a comparable policy that gives the account permissions to access Systems Manager. 1. Choose **Add inline policy**. 1. On the **Create policy** page, choose the **Visual editor** tab. 1. Choose **Choose a service**, and then choose ** IAM**. 1. For **Actions**, in the **Filter actions** text box, enter **PassRole**, and then select the check box next to **PassRole**. 1. For **Resources**, verify that **Specific** is selected, and then choose **Add ARN**. 1. In the **Specify ARN for role** field, paste the Amazon SNS IAM role ARN that you copied at the end of Task 3. The system automatically populates the **Account** and **Role name with path** fields. 1. Choose **Add**. 1. Choose **Review policy**. 1. On the **Review Policy** page, enter a name and then choose **Create policy**. ### Task 5: Attach the iam:PassRole policy to your maintenance window role When you register a Run Command task with a maintenance window, you specify a service role Amazon Resource Name (ARN). This service role is used by Systems Manager to run tasks registered to the maintenance window. To configure Amazon SNS notifications for a registered Run Command task, attach an `iam:PassRole` policy to the maintenance window service role specified. If you don't intend to configure the registered task for Amazon SNS notifications, then you can skip this task. The `iam:PassRole` policy allows the Maintenance Windows service role to pass the Amazon SNS IAM role created in Task 3 to the Amazon SNS service. The following procedure shows how to attach the `iam:PassRole` policy to the Maintenance Windows service role. **Note** Use a custom service role for your maintenance window to send notifications related to the Run Command tasks registered. For information, see [Setting up Maintenance Windows](setting-up-maintenance-windows.md). If you need to create a custom service role for maintenance window tasks, see [Setting up Maintenance Windows](setting-up-maintenance-windows.md). **To attach the`iam:PassRole` policy to your Maintenance Windows role** 1. Open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/). 1. In the navigation pane, choose **Roles** and select the Amazon SNS IAM role created in Task 3. 1. Copy or make a note of the **Role ARN** and return to the **Roles** section of the IAM console. 1. Select the custom Maintenance Windows service role you created from the **Role name** list. 1. On the **Permissions** tab, verify that either the `AmazonSSMMaintenanceWindowRole` policy is listed or there is a comparable policy that gives maintenance windows permission to the Systems Manager API. If it is not, choose **Add permissions, Attach policies** to attach it. 1. Choose **Add permissions, Create inline policy**. 1. Choose the **Visual editor** tab. 1. For **Service**, choose **IAM**. 1. For **Actions**, in the **Filter actions** text box, enter **PassRole**, and then select the check box next to **PassRole**. 1. For **Resources**, choose **Specific**, and then choose **Add ARN**. 1. In the **Specify ARN for role** box, paste the ARN of the Amazon SNS IAM role created in Task 3, and then choose **Add**. 1. Choose **Review policy**. 1. On the **Review policy** page, specify a name for the `PassRole` policy, and then choose **Create policy**. # Example Amazon SNS notifications for AWS Systems Manager You can configure Amazon Simple Notification Service (Amazon SNS) to send notifications about the status of commands that you send using Run Command or Maintenance Windows, which are tools in AWS Systems Manager. **Note** This guide doesn't address how to configure notifications for Run Command or Maintenance Windows. For information about configuring Run Command or Maintenance Windows to send Amazon SNS notifications about the status of commands, see [Configure Amazon SNS notifications for AWS Systems Manager](monitoring-sns-notifications.md#monitoring-sns-configure). The following examples show the structure of the JSON output returned by Amazon SNS notifications when configured for Run Command or Maintenance Windows. **Sample JSON Output for Command summary messages using instance ID targeting** ``` { "commandId": "a8c7e76f-15f1-4c33-9052-0123456789ab", "documentName": "AWS-RunPowerShellScript", "instanceIds": [ "i-1234567890abcdef0", "i-9876543210abcdef0" ], "requestedDateTime": "2019-04-25T17:57:09.17Z", "expiresAfter": "2019-04-25T19:07:09.17Z", "outputS3BucketName": "amzn-s3-demo-bucket", "outputS3KeyPrefix": "runcommand", "status": "InProgress", "eventTime": "2019-04-25T17:57:09.236Z" } ``` **Sample JSON Output for Command summary messages using tag-based targeting** ``` { "commandId": "9e92c686-ddc7-4827-b040-0123456789ab", "documentName": "AWS-RunPowerShellScript", "instanceIds": [], "requestedDateTime": "2019-04-25T18:01:03.888Z", "expiresAfter": "2019-04-25T19:11:03.888Z", "outputS3BucketName": "", "outputS3KeyPrefix": "", "status": "InProgress", "eventTime": "2019-04-25T18:01:05.825Z" } ``` **Sample JSON Output for Invocation messages** ``` { "commandId": "ceb96b84-16aa-4540-91e3-925a9a278b8c", "documentName": "AWS-RunPowerShellScript", "instanceId": "i-1234567890abcdef0", "requestedDateTime": "2019-04-25T18:06:05.032Z", "status": "InProgress", "eventTime": "2019-04-25T18:06:05.099Z" } ``` # Use Run Command to send a command that returns status notifications The following procedures show how to use the AWS Command Line Interface (AWS CLI) or AWS Systems Manager console to send a command through Run Command, a tool in AWS Systems Manager, that is configured to return status notifications. ## Sending a Run Command that returns notifications (console) Use the following procedure to send a command through Run Command that is configured to return status notifications using the Systems Manager console. **To send a command that returns notifications (console)** 1. Open the AWS Systems Manager console at [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/). 1. In the navigation pane, choose **Run Command**. 1. Choose **Run command**. 1. In the **Command document** list, choose a Systems Manager document. 1. In the **Command parameters** section, specify values for required parameters. 1. In the **Targets** section, choose the managed nodes on which you want to run this operation by specifying tags, selecting instances or edge devices manually, or specifying a resource group. **Tip** If a managed node you expect to see isn't listed, see [Troubleshooting managed node availability](fleet-manager-troubleshooting-managed-nodes.md) for troubleshooting tips. 1. For **Other parameters**: + For **Comment**, enter information about this command. + For **Timeout (seconds)**, specify the number of seconds for the system to wait before failing the overall command execution. 1. For **Rate control**: + For **Concurrency**, specify either a number or a percentage of managed nodes on which to run the command at the same time. **Note** If you selected targets by specifying tags applied to managed nodes or by specifying AWS resource groups, and you aren't certain how many managed nodes are targeted, then restrict the number of targets that can run the document at the same time by specifying a percentage. + For **Error threshold**, specify when to stop running the command on other managed nodes after it fails on either a number or a percentage of nodes. For example, if you specify three errors, then Systems Manager stops sending the command when the fourth error is received. Managed nodes still processing the command might also send errors. 1. (Optional) For **Output options**, to save the command output to a file, select the **Write command output to an S3 bucket** box. Enter the bucket and prefix (folder) names in the boxes. **Note** The S3 permissions that grant the ability to write the data to an S3 bucket are those of the instance profile (for EC2 instances) or IAM service role (hybrid-activated machines) assigned to the instance, not those of the IAM user performing this task. For more information, see [Configure instance permissions required for Systems Manager](setup-instance-permissions.md) or [Create an IAM service role for a hybrid environment](hybrid-multicloud-service-role.md). In addition, if the specified S3 bucket is in a different AWS account, make sure that the instance profile or IAM service role associated with the managed node has the necessary permissions to write to that bucket. 1. In the **SNS Notifications** section, choose **Enable SNS notifications**. 1. For **IAM role**, choose the Amazon SNS IAM role ARN you created in Task 3 in [Monitoring Systems Manager status changes using Amazon SNS notifications](monitoring-sns-notifications.md). 1. For **SNS topic**, enter the Amazon SNS topic ARN to be used. 1. For **Event notifications**, choose the events for which you want to receive notifications. 1. For **Change notifications**, choose to receive notifications for the command summary only (**Command status changes**) or for each copy of a command sent to multiple nodes (**Command status on each instance changes**) . 1. Choose **Run**. 1. Check your email for a message from Amazon SNS and open the email message. Amazon SNS can take several minutes to send the email message. ## Sending a Run Command that returns notifications (CLI) Use the following procedure to send a command through Run Command that is configured to return status notifications using the AWS CLI. **To send a command that returns notifications (CLI)** 1. Open the AWS CLI. 1. Specify parameters in the following command to target based on managed node IDs. ``` aws ssm send-command --instance-ids "ID-1, ID-2" --document-name "Name" --parameters '{"commands":["input"]}' --service-role "SNSRoleARN" --notification-config '{"NotificationArn":"SNSTopicName","NotificationEvents":["All"],"NotificationType":"Command"}' ``` Following is an example. ``` aws ssm send-command --instance-ids "i-02573cafcfEXAMPLE, i-0471e04240EXAMPLE" --document-name "AWS-RunPowerShellScript" --parameters '{"commands":["Get-Process"]}' --service-role "arn:aws:iam::111122223333:role/SNS_Role" --notification-config '{"NotificationArn":"arn:aws:sns:us-east-1:111122223333:SNSTopic","NotificationEvents":["All"],"NotificationType":"Command"}' ``` **Alternative commands** Specify parameters in the following command to target managed instances using tags. ``` aws ssm send-command --targets "Key=tag:TagName,Values=TagKey" --document-name "Name" --parameters '{"commands":["input"]}' --service-role "SNSRoleARN" --notification-config '{"NotificationArn":"SNSTopicName","NotificationEvents":["All"],"NotificationType":"Command"}' ``` Following is an example. ``` aws ssm send-command --targets "Key=tag:Environment,Values=Dev" --document-name "AWS-RunPowerShellScript" --parameters '{"commands":["Get-Process"]}' --service-role "arn:aws:iam::111122223333:role/SNS_Role" --notification-config '{"NotificationArn":"arn:aws:sns:us-east-1:111122223333:SNSTopic","NotificationEvents":["All"],"NotificationType":"Command"}' ``` 1. Press **Enter**. 1. Check your email for a message from Amazon SNS and open the email message. Amazon SNS can take several minutes to send the email message. For more information, see [https://docs.aws.amazon.com/cli/latest/reference/ssm/send-command.html](https://docs.aws.amazon.com/cli/latest/reference/ssm/send-command.html) in the *AWS CLI Command Reference*. # Use a maintenance window to send a command that returns status notifications The following procedures show how to register a Run Command task with your maintenance window using the AWS Systems Manager console or the AWS Command Line Interface (AWS CLI). Run Command is a tool in AWS Systems Manager. The procedures also describe how to configure the Run Command task to return status notifications. **Before you begin** If you haven't created a maintenance window or registered targets, see [Create and manage maintenance windows using the console](sysman-maintenance-working.md) for steps on how to create a maintenance window and register targets. To receive notifications from the Amazon Simple Notification Service (Amazon SNS) service, attach an `iam:PassRole` policy to the Maintenance Windows service role specified in the registered task. If you haven't added `iam:PassRole` permissions to your Maintenance Windows service role, see [Task 5: Attach the iam:PassRole policy to your maintenance window role](monitoring-sns-notifications.md#monitoring-sns-passpolicy-mw). ## Registering a Run Command task to a maintenance window that returns notifications (console) Use the following procedure to register a Run Command task that is configured to return status notifications to your maintenance window using the Systems Manager console. **To register a Run Command task with your maintenance window that returns notifications (console)** 1. Open the AWS Systems Manager console at [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/). 1. In the navigation pane, choose **Maintenance Windows**. 1. Select the maintenance window for which you would like to register a Run Command task configured to send Amazon Simple Notification Service (Amazon SNS) notifications. 1. Choose **Actions** and then choose **Register Run command task**. 1. (Optional) In the **Name** field, enter a name for the task. 1. (Optional) In the **Description** field, enter a description. 1. For **Command document**, choose a Command document. 1. For **Task priority**, specify a priority for this task. Zero (`0`) is the highest priority. Tasks in a maintenance window are scheduled in priority order. Tasks that have the same priority are scheduled in parallel. 1. In the **Targets** section, select a registered target group or select unregistered targets. 1. For **Rate control**: + For **Concurrency**, specify either a number or a percentage of managed nodes on which to run the command at the same time. **Note** If you selected targets by specifying tags applied to managed nodes or by specifying AWS resource groups, and you aren't certain how many managed nodes are targeted, then restrict the number of targets that can run the document at the same time by specifying a percentage. + For **Error threshold**, specify when to stop running the command on other managed nodes after it fails on either a number or a percentage of nodes. For example, if you specify three errors, then Systems Manager stops sending the command when the fourth error is received. Managed nodes still processing the command might also send errors. 1. In the ** IAM service role** area, choose the Maintenance Windows service role that has `iam:PassRole` permissions to the SNS role. **Note** Add `iam:PassRole` permissions to the Maintenance Windows role to allow Systems Manager to pass the SNS role to Amazon SNS. If you haven't added `iam:PassRole` permissions, see Task 5 in the topic [Monitoring Systems Manager status changes using Amazon SNS notifications](monitoring-sns-notifications.md). 1. (Optional) For **Output options**, to save the command output to a file, select the **Enable writing output to S3** box. Enter the bucket and prefix (folder) names in the boxes. **Note** The S3 permissions that grant the ability to write the data to an S3 bucket are those of the instance profile assigned to the managed node, not those of the IAM user performing this task. For more information, see [Configure instance permissions required for Systems Manager](setup-instance-permissions.md) or [Create an IAM service role for a hybrid environment](hybrid-multicloud-service-role.md). In addition, if the specified S3 bucket is in a different AWS account, verify that the instance profile or IAM service role associated with the managed node has the necessary permissions to write to that bucket. 1. In the **SNS notifications** section, do the following: + Choose **Enable SNS Notifications**. + For **IAM role**, choose the Amazon SNS IAM role Amazon Resource Name (ARN) you created in Task 3 in [Monitoring Systems Manager status changes using Amazon SNS notifications](monitoring-sns-notifications.md) to initiate Amazon SNS. + For **SNS topic**, enter the Amazon SNS topic ARN to be used. + For **Event type**, choose the events for which you want to receive notifications. + For **Notification type**, choose to receive notifications for each copy of a command sent to multiple nodes (invocations) or the command summary. 1. In the **Parameters** section, enter the required parameters based on the Command document you chose. 1. Choose **Register Run command task**. 1. After the next time your maintenance window runs, check your email for a message from Amazon SNS and open the email message. Amazon SNS can take a few minutes to send the email message. ## Registering a Run Command task to a maintenance window that returns notifications (CLI) Use the following procedure to register a Run Command task that is configured to return status notifications to your maintenance window using the AWS CLI. **To register a Run Command task with your maintenance window that returns notifications (CLI)** **Note** To better manage your task options, this procedure uses the command option `--cli-input-json`, with option values stored in a JSON file. 1. On your local machine, create a file named `RunCommandTask.json`. 1. Paste the following contents into the file. ``` { "Name": "Name", "Description": "Description", "WindowId": "mw-0c50858d01EXAMPLE", "ServiceRoleArn": "arn:aws:iam::account-id:role/MaintenanceWindowIAMRole", "MaxConcurrency": "1", "MaxErrors": "1", "Priority": 3, "Targets": [ { "Key": "WindowTargetIds", "Values": [ "e32eecb2-646c-4f4b-8ed1-205fbEXAMPLE" ] } ], "TaskType": "RUN_COMMAND", "TaskArn": "CommandDocumentName", "TaskInvocationParameters": { "RunCommand": { "Comment": "Comment", "TimeoutSeconds": 3600, "NotificationConfig": { "NotificationArn": "arn:aws:sns:region:account-id:SNSTopicName", "NotificationEvents": [ "All" ], "NotificationType": "Command" }, "ServiceRoleArn": "arn:aws:iam::account-id:role/SNSIAMRole" } } } ``` 1. Replace the example values with information about your own resources. You can also restore options we've omitted from this example if you want to use them. For example, you can save command output to an S3 bucket. For more information, see [https://docs.aws.amazon.com/cli/latest/reference/ssm/register-task-with-maintenance-window.html](https://docs.aws.amazon.com/cli/latest/reference/ssm/register-task-with-maintenance-window.html) in the *AWS CLI Command Reference*. 1. Save the file. 1. In the directory on your local machine where you saved the file, run the following command. ``` aws ssm register-task-with-maintenance-window --cli-input-json file://RunCommandTask.json ``` **Important** Be sure to include `file://` before the file name. It's required in this command. If successful, the command returns information similar to the following. ``` { "WindowTaskId": "j2l8d5b5c-mw66-tk4d-r3g9-1d4d1EXAMPLE" } ``` 1. After the next execution of your maintenance window, check your email for a message from Amazon SNS and open the email message. Amazon SNS can take a few minutes to send the email message. For more information about registering tasks for a maintenance window from the command line, see [Register tasks with the maintenance window](mw-cli-tutorial-tasks.md).