# Configure alarms to create investigations
You can configure an existing CloudWatch alarm to automatically create investigations in CloudWatch investigations. When the alarm enters the ALARM state, CloudWatch automatically creates a new investigation or adds to an existing investigation based on the deduplication string.
When configuring an alarm to automatically create investigations, you'll need to specify an Amazon Resource Name (ARN) in the alarm's actionArns. This ARN identifies the investigation group where alarm-triggered investigations will be created. You can optionally include a deduplication string in the ARN to group related alarms.
## ARN format and parameters
The ARN pattern for investigation group alarm actions follows this format:
```
arn:aws:aiops:region:account-id:investigation-group/investigation-group-identifier#DEDUPE_STRING=value
```
The following table describes each ARN component:
| Parameter | Description |
| --- | --- |
| region (required) | The AWS Region where your investigation group is located. For example: us-east-1. |
| account-id (required) | Your 12-digit AWS account ID. For example: 123456789012. |
| investigation-group-identifier (required) | The unique identifier of your investigation group. Fore example, sMwwg1IogXdvL7UZ |
| DEDUPE\$1STRING=value (optional) | A deduplication string that groups related alarms into the same investigation. When multiple alarms use the same deduplication string, they contribute to a single investigation instead of creating separate ones. |
**Example without deduplication string:**
```
arn:aws:aiops:us-east-1:123456789012:investigation-group/sMwwg1IogXdvL7UZ
```
**Example with deduplication string:**
```
arn:aws:aiops:us-east-1:123456789012:investigation-group/sMwwg1IogXdvL7UZ#DEDUPE_STRING=performance
```
### Benefits of deduplication strings
Deduplication strings help you organize related alarms and reduce investigation fragmentation. Use deduplication strings when:
+ **Multiple alarms monitor the same system** - CPU, memory, and disk alarms for the same EC2 instance can share a deduplication string to create one comprehensive investigation.
+ **Cascading failures occur** - When one issue triggers multiple related alarms, the same deduplication string prevents creating separate investigations for each symptom.
+ **You want to categorize by problem type** - Use descriptive strings like "performance", "connectivity", or "security" to group alarms by issue category.
Effective deduplication string examples:
+ `DEDUPE_STRING=webserver-performance` - Groups performance-related alarms for web servers
+ `DEDUPE_STRING=database-connectivity` - Groups database connection issues
+ `DEDUPE_STRING=instance-i-1234567890abcdef0` - Groups all alarms for a specific EC2 instance
**Note**
If no deduplication string is specified, the system uses a default combination of alarm name, account ID, and region to group investigations.
For more information about investigation groups, see [Set up an investigation group](Investigations-GetStarted-Group.md).
# Configure an alarm to create investigations
After you have an investigation group set up in your account, you can configure existing CloudWatch alarms to automatically create investigations when they enter the ALARM state. This eliminates the need to manually start investigations and ensures consistent response to operational issues. You can configure alarms using the AWS Management Console, AWS CLI, CloudFormation, or AWS SDKs.
------
#### [ 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 **Alarms**, and select an existing alarm.
1. Choose **Actions**, **Edit**.
1. In the **Alarm actions** section, choose **Add alarm action**.
1. Under the **Configure actions**, **Investigation action** section, choose the investigation group ARN.
1. (Optional) Add a deduplication string to group related alarms.
1. Choose **Update alarm**.
------
#### [ CLI ]
This command requires that you specify an ARN for the `alarm-actions` parameter. For information about how to create the ARN, see [ARN format and parameters](Investigations-configure-alarms.md#Investigations-arn-format).
**To configure a CloudWatch alarm with InvestigationGroup action (AWS CLI)**
1. Install and configure the AWS CLI, if you haven't already. For information, see [Installing or updating the latest version of the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html).
1. Run the following command to collect information about the alarm that you want to configure.
```
aws cloudwatch describe-alarms --alarm-names "alarm name"
```
1. Run the following command to update an alarm. Replace each *example resource placeholder* with your own information.
```
aws cloudwatch put-metric-alarm --alarm-name name \
--alarm-description "description" \
--metric-name name --namespace namespace \
--statistic statistic --period value --threshold value \
--comparison-operator value \
--dimensions "dimensions" --evaluation-periods value \
--alarm-actions "arn:aws:aiops:region:{account-id}:investigation-group/{investigationGroupIdentifier}#DEDUPE_STRING={my-dedupe-string}"
```
Here's an example.
```
//Without deduplication string
aws cloudwatch put-metric-alarm --alarm-name cpu-mon \
--alarm-description "Alarm when CPU exceeds 70 percent" \
--metric-name CPUUtilization --namespace AWS/EC2 \
--statistic Average --period 300 --threshold 70 \
--comparison-operator GreaterThanThreshold \
--dimensions "Name=InstanceId,Value=i-12345678" --evaluation-periods 2 \
--alarm-actions arn:aws:aiops:us-east-1:123456789012:investigation-group/sMwwg1IogXdvL7UZ \
--unit Percent
//With deduplication string
aws cloudwatch put-metric-alarm --alarm-name cpu-mon \
--alarm-description "Alarm when CPU exceeds 70 percent" \
--metric-name CPUUtilization --namespace AWS/EC2 \
--statistic Average --period 300 --threshold 70 \
--comparison-operator GreaterThanThreshold \
--dimensions "Name=InstanceId,Value=i-12345678" --evaluation-periods 2 \
--alarm-actions arn:aws:aiops:us-east-1:123456789012:investigation-group/sMwwg1IogXdvL7UZ#DEDUPE_STRING=performance \
--unit Percent
```
------
#### [ CloudFormation ]
This section includes CloudFormation templates that you can use to configure CloudWatch alarms to automatically create or update investigations. Each template requires that you specify an ARN for the `AlarmActions` parameter. For information about how to create the ARN, see [ARN format and parameters](Investigations-configure-alarms.md#Investigations-arn-format).
```
//Without deduplication string
Resources:
MyAlarm:
Type: AWS::CloudWatch::Alarm
Properties:
AlarmActions:
- !Sub "arn:aws:aiops:${AWS::Region}:${AWS::AccountId}:investigation-group/{investigationGroupIdentifier}"
//With deduplication string
Resources:
MyAlarm:
Type: AWS::CloudWatch::Alarm
Properties:
AlarmActions:
- !Sub "arn:aws:aiops:${AWS::Region}:${AWS::AccountId}:investigation-group/{investigationGroupIdentifier}#DEDUPE_STRING={my-dedupe-string}"
```
------
#### [ SDK ]
This section includes Java code snippets that you can use to configure CloudWatch alarms to automatically create or update investigations. Each snippet requires that you specify an ARN for the `investigationGroupArn` parameter. For information about how to create the ARN, see [ARN format and parameters](Investigations-configure-alarms.md#Investigations-arn-format).
```
import com.amazonaws.services.cloudwatch.AmazonCloudWatch;
import com.amazonaws.services.cloudwatch.AmazonCloudWatchClientBuilder;
import com.amazonaws.services.cloudwatch.model.ComparisonOperator;
import com.amazonaws.services.cloudwatch.model.Dimension;
import com.amazonaws.services.cloudwatch.model.PutMetricAlarmRequest;
import com.amazonaws.services.cloudwatch.model.PutMetricAlarmResult;
import com.amazonaws.services.cloudwatch.model.StandardUnit;
import com.amazonaws.services.cloudwatch.model.Statistic;
//Without deduplication string
private void putMetricAlarmWithCloudWatchInvestigationAction() {
final AmazonCloudWatch cloudWatchClient =
AmazonCloudWatchClientBuilder.defaultClient();
Dimension dimension = new Dimension()
.withName("InstanceId")
.withValue("i-12345678");
String investigationGroupArn = "arn:aws:aiops:us-east-1:123456789012:investigation-group/sMwwg1IogXdvL7UZ";
PutMetricAlarmRequest request = new PutMetricAlarmRequest()
.withAlarmName("cpu-mon")
.withComparisonOperator(
ComparisonOperator.GreaterThanThreshold)
.withEvaluationPeriods(2)
.withMetricName("CPUUtilization")
.withNamespace("AWS/EC2")
.withPeriod(300)
.withStatistic(Statistic.Average)
.withThreshold(70.0)
.withActionsEnabled(true)
.withAlarmDescription("Alarm when CPU exceeds 70 percent")
.withUnit(StandardUnit.Percent)
.withDimensions(dimension)
.withAlarmActions(investigationGroupArn);
PutMetricAlarmResult response = cloudWatchClient.putMetricAlarm(request);
}
//With deduplication string
private void putMetricAlarmWithCloudWatchInvestigationActionWithDedupeString() {
final AmazonCloudWatch cloudWatchClient =
AmazonCloudWatchClientBuilder.defaultClient();
Dimension dimension = new Dimension()
.withName("InstanceId")
.withValue("i-12345678");
String investigationGroupArn = "arn:aws:aiops:us-east-1:123456789012:investigation-group/sMwwg1IogXdvL7UZ#DEDUPE_STRING=performance";
PutMetricAlarmRequest request = new PutMetricAlarmRequest()
.withAlarmName("cpu-mon")
.withComparisonOperator(
ComparisonOperator.GreaterThanThreshold)
.withEvaluationPeriods(2)
.withMetricName("CPUUtilization")
.withNamespace("AWS/EC2")
.withPeriod(300)
.withStatistic(Statistic.Average)
.withThreshold(70.0)
.withActionsEnabled(true)
.withAlarmDescription("Alarm when CPU exceeds 70 percent")
.withUnit(StandardUnit.Percent)
.withDimensions(dimension)
.withAlarmActions(investigationGroupArn);
PutMetricAlarmResult response = cloudWatchClient.putMetricAlarm(request);
}
```
------