# Work with CloudWatch This section provides examples of programming [Amazon CloudWatch](https://docs.aws.amazon.com//AmazonCloudWatch/latest/monitoring/WhatIsCloudWatch.html) by using the AWS SDK for Java 2.x. Amazon CloudWatch monitors your Amazon Web Services (AWS) resources and the applications you run on AWS in real time. You can use CloudWatch to collect and track metrics, which are variables you can measure for your resources and applications. CloudWatch alarms send notifications or automatically make changes to the resources you are monitoring based on rules that you define. The following examples include only the code needed to demonstrate each technique. The [complete example code is available on GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javav2). From there, you can download a single source file or clone the repository locally to get all the examples to build and run. **Topics** + [Get metrics from CloudWatch](examples-cloudwatch-get-metrics.md) + [Publish custom metric data to CloudWatch](examples-cloudwatch-publish-custom-metrics.md) + [Work with CloudWatch alarms](examples-cloudwatch-create-alarms.md) + [Use Amazon CloudWatch Events](examples-cloudwatch-send-events.md) # Get metrics from CloudWatch ## Listing metrics To list CloudWatch metrics, create a [ListMetricsRequest](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/cloudwatch/model/ListMetricsRequest.html) and call the CloudWatchClient’s `listMetrics` method. You can use the `ListMetricsRequest` to filter the returned metrics by namespace, metric name, or dimensions. **Note** A list of metrics and dimensions that are posted by AWS services can be found within the [Amazon CloudWatch Metrics and Dimensions Reference](https://docs.aws.amazon.com//AmazonCloudWatch/latest/monitoring/aws-services-cloudwatch-metrics.html) in the Amazon CloudWatch User Guide. **Imports** ``` import software.amazon.awssdk.regions.Region; import software.amazon.awssdk.services.cloudwatch.CloudWatchClient; import software.amazon.awssdk.services.cloudwatch.model.CloudWatchException; import software.amazon.awssdk.services.cloudwatch.model.ListMetricsRequest; import software.amazon.awssdk.services.cloudwatch.model.ListMetricsResponse; import software.amazon.awssdk.services.cloudwatch.model.Metric; ``` **Code** ``` public static void listMets( CloudWatchClient cw, String namespace) { boolean done = false; String nextToken = null; try { while(!done) { ListMetricsResponse response; if (nextToken == null) { ListMetricsRequest request = ListMetricsRequest.builder() .namespace(namespace) .build(); response = cw.listMetrics(request); } else { ListMetricsRequest request = ListMetricsRequest.builder() .namespace(namespace) .nextToken(nextToken) .build(); response = cw.listMetrics(request); } for (Metric metric : response.metrics()) { System.out.printf( "Retrieved metric %s", metric.metricName()); System.out.println(); } if(response.nextToken() == null) { done = true; } else { nextToken = response.nextToken(); } } } catch (CloudWatchException e) { System.err.println(e.awsErrorDetails().errorMessage()); System.exit(1); } } ``` The metrics are returned in a [ListMetricsResponse](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/cloudwatch/model/ListMetricsResponse.html) by calling its `getMetrics` method. The results may be *paged*. To retrieve the next batch of results, call `nextToken` on the response object and use the token value to build a new request object. Then call the `listMetrics` method again with the new request. See the [complete example](https://github.com/awsdocs/aws-doc-sdk-examples/blob/f4eaf2b2971805cfb2b87a8e5ab408f83169432e/javav2/example_code/cloudwatch/src/main/java/com/example/cloudwatch/ListMetrics.java) on GitHub. ## More information + [ListMetrics](https://docs.aws.amazon.com//AmazonCloudWatch/latest/APIReference/API_ListMetrics.html) in the Amazon CloudWatch API Reference # Publish custom metric data to CloudWatch A number of AWS services publish [their own metrics](https://docs.aws.amazon.com//AmazonCloudWatch/latest/monitoring/aws-services-cloudwatch-metrics.html) in namespaces beginning with " `AWS` " You can also publish custom metric data using your own namespace (as long as it doesn’t begin with " `AWS` "). ## Publish custom metric data To publish your own metric data, call the CloudWatchClient’s `putMetricData` method with a [PutMetricDataRequest](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/cloudwatch/model/PutMetricDataRequest.html). The `PutMetricDataRequest` must include the custom namespace to use for the data, and information about the data point itself in a [MetricDatum](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/cloudwatch/model/MetricDatum.html) object. **Note** You cannot specify a namespace that begins with " `AWS` ". Namespaces that begin with " `AWS` " are reserved for use by Amazon Web Services products. **Imports** ``` import software.amazon.awssdk.regions.Region; import software.amazon.awssdk.services.cloudwatch.CloudWatchClient; import software.amazon.awssdk.services.cloudwatch.model.Dimension; import software.amazon.awssdk.services.cloudwatch.model.MetricDatum; import software.amazon.awssdk.services.cloudwatch.model.StandardUnit; import software.amazon.awssdk.services.cloudwatch.model.PutMetricDataRequest; import software.amazon.awssdk.services.cloudwatch.model.CloudWatchException; import java.time.Instant; import java.time.ZoneOffset; import java.time.ZonedDateTime; import java.time.format.DateTimeFormatter; ``` **Code** ``` public static void putMetData(CloudWatchClient cw, Double dataPoint ) { try { Dimension dimension = Dimension.builder() .name("UNIQUE_PAGES") .value("URLS") .build(); // Set an Instant object String time = ZonedDateTime.now( ZoneOffset.UTC ).format( DateTimeFormatter.ISO_INSTANT ); Instant instant = Instant.parse(time); MetricDatum datum = MetricDatum.builder() .metricName("PAGES_VISITED") .unit(StandardUnit.NONE) .value(dataPoint) .timestamp(instant) .dimensions(dimension).build(); PutMetricDataRequest request = PutMetricDataRequest.builder() .namespace("SITE/TRAFFIC") .metricData(datum).build(); cw.putMetricData(request); } catch (CloudWatchException e) { System.err.println(e.awsErrorDetails().errorMessage()); System.exit(1); } System.out.printf("Successfully put data point %f", dataPoint); } ``` See the [complete example](https://github.com/awsdocs/aws-doc-sdk-examples/blob/f4eaf2b2971805cfb2b87a8e5ab408f83169432e/javav2/example_code/cloudwatch/src/main/java/com/example/cloudwatch/PutMetricData.java) on GitHub. ## More information + [Use Amazon CloudWatch Metrics](https://docs.aws.amazon.com//AmazonCloudWatch/latest/monitoring/working_with_metrics.html) in the Amazon CloudWatch User Guide. + [AWS Namespaces](https://docs.aws.amazon.com//AmazonCloudWatch/latest/monitoring/aws-services-cloudwatch-metrics.html) in the Amazon CloudWatch User Guide. + [PutMetricData](https://docs.aws.amazon.com//AmazonCloudWatch/latest/APIReference/API_PutMetricData.html) in the Amazon CloudWatch API Reference. # Work with CloudWatch alarms ## Create an alarm To create an alarm based on a CloudWatch metric, call the CloudWatchClient’s `putMetricAlarm` method with a [PutMetricAlarmRequest](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/cloudwatch/model/PutMetricAlarmRequest.html) filled with the alarm conditions. **Imports** ``` import software.amazon.awssdk.regions.Region; import software.amazon.awssdk.services.cloudwatch.CloudWatchClient; import software.amazon.awssdk.services.cloudwatch.model.Dimension; import software.amazon.awssdk.services.cloudwatch.model.PutMetricAlarmRequest; import software.amazon.awssdk.services.cloudwatch.model.ComparisonOperator; import software.amazon.awssdk.services.cloudwatch.model.Statistic; import software.amazon.awssdk.services.cloudwatch.model.StandardUnit; import software.amazon.awssdk.services.cloudwatch.model.CloudWatchException; ``` **Code** ``` public static void putMetricAlarm(CloudWatchClient cw, String alarmName, String instanceId) { try { Dimension dimension = Dimension.builder() .name("InstanceId") .value(instanceId).build(); PutMetricAlarmRequest request = PutMetricAlarmRequest.builder() .alarmName(alarmName) .comparisonOperator( ComparisonOperator.GREATER_THAN_THRESHOLD) .evaluationPeriods(1) .metricName("CPUUtilization") .namespace("AWS/EC2") .period(60) .statistic(Statistic.AVERAGE) .threshold(70.0) .actionsEnabled(false) .alarmDescription( "Alarm when server CPU utilization exceeds 70%") .unit(StandardUnit.SECONDS) .dimensions(dimension) .build(); cw.putMetricAlarm(request); System.out.printf( "Successfully created alarm with name %s", alarmName); } catch (CloudWatchException e) { System.err.println(e.awsErrorDetails().errorMessage()); System.exit(1); } } ``` See the [complete example](https://github.com/awsdocs/aws-doc-sdk-examples/blob/f4eaf2b2971805cfb2b87a8e5ab408f83169432e/javav2/example_code/cloudwatch/src/main/java/com/example/cloudwatch/PutMetricAlarm.java) on GitHub. ## List alarms To list the CloudWatch alarms that you have created, call the CloudWatchClient’s `describeAlarms` method with a [DescribeAlarmsRequest](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/cloudwatch/model/DescribeAlarmsRequest.html) that you can use to set options for the result. **Imports** ``` import software.amazon.awssdk.regions.Region; import software.amazon.awssdk.services.cloudwatch.CloudWatchClient; import software.amazon.awssdk.services.cloudwatch.model.CloudWatchException; import software.amazon.awssdk.services.cloudwatch.model.DescribeAlarmsRequest; import software.amazon.awssdk.services.cloudwatch.model.DescribeAlarmsResponse; import software.amazon.awssdk.services.cloudwatch.model.MetricAlarm; ``` **Code** ``` public static void desCWAlarms( CloudWatchClient cw) { try { boolean done = false; String newToken = null; while(!done) { DescribeAlarmsResponse response; if (newToken == null) { DescribeAlarmsRequest request = DescribeAlarmsRequest.builder().build(); response = cw.describeAlarms(request); } else { DescribeAlarmsRequest request = DescribeAlarmsRequest.builder() .nextToken(newToken) .build(); response = cw.describeAlarms(request); } for(MetricAlarm alarm : response.metricAlarms()) { System.out.printf("\n Retrieved alarm %s", alarm.alarmName()); } if(response.nextToken() == null) { done = true; } else { newToken = response.nextToken(); } } } catch (CloudWatchException e) { System.err.println(e.awsErrorDetails().errorMessage()); System.exit(1); } System.out.printf("Done"); } ``` The list of alarms can be obtained by calling `MetricAlarms` on the [DescribeAlarmsResponse](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/cloudwatch/model/DescribeAlarmsResponse.html) that is returned by `describeAlarms`. The results may be *paged*. To retrieve the next batch of results, call `nextToken` on the response object and use the token value to build a new request object. Then call the `describeAlarms` method again with the new request. **Note** You can also retrieve alarms for a specific metric by using the CloudWatchClient’s `describeAlarmsForMetric` method. Its use is similar to `describeAlarms`. See the [complete example](https://github.com/awsdocs/aws-doc-sdk-examples/blob/f4eaf2b2971805cfb2b87a8e5ab408f83169432e/javav2/example_code/cloudwatch/src/main/java/com/example/cloudwatch/DescribeAlarms.java) on GitHub. ## Delete alarms To delete CloudWatch alarms, call the CloudWatchClient’s `deleteAlarms` method with a [DeleteAlarmsRequest](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/cloudwatch/model/DeleteAlarmsRequest.html) containing one or more names of alarms that you want to delete. **Imports** ``` import software.amazon.awssdk.regions.Region; import software.amazon.awssdk.services.cloudwatch.CloudWatchClient; import software.amazon.awssdk.services.cloudwatch.model.CloudWatchException; import software.amazon.awssdk.services.cloudwatch.model.DeleteAlarmsRequest; ``` **Code** ``` public static void deleteCWAlarm(CloudWatchClient cw, String alarmName) { try { DeleteAlarmsRequest request = DeleteAlarmsRequest.builder() .alarmNames(alarmName) .build(); cw.deleteAlarms(request); System.out.printf("Successfully deleted alarm %s", alarmName); } catch (CloudWatchException e) { System.err.println(e.awsErrorDetails().errorMessage()); System.exit(1); } } ``` See the [complete example](https://github.com/awsdocs/aws-doc-sdk-examples/blob/f4eaf2b2971805cfb2b87a8e5ab408f83169432e/javav2/example_code/cloudwatch/src/main/java/com/example/cloudwatch/DeleteAlarm.java) on GitHub. ## More information + [Using Amazon CloudWatch alarms](https://docs.aws.amazon.com//AmazonCloudWatch/latest/monitoring/AlarmThatSendsEmail.html) in the Amazon CloudWatch User Guide + [PutMetricAlarm](https://docs.aws.amazon.com//AmazonCloudWatch/latest/APIReference/API_PutMetricAlarm.html) in the Amazon CloudWatch API Reference + [DescribeAlarms](https://docs.aws.amazon.com//AmazonCloudWatch/latest/APIReference/API_DescribeAlarms.html) in the Amazon CloudWatch API Reference + [DeleteAlarms](https://docs.aws.amazon.com//AmazonCloudWatch/latest/APIReference/API_DeleteAlarms.html) in the Amazon CloudWatch API Reference # Use Amazon CloudWatch Events CloudWatch Events delivers a near real-time stream of system events that describe changes in AWS resources to Amazon EC2 instances, Lambda functions, Kinesis streams, Amazon ECS tasks, Step Functions state machines, Amazon SNS topics, Amazon SQS queues, or built-in targets. You can match events and route them to one or more target functions or streams by using simple rules. Amazon EventBridge is the [evolution](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-cwe-now-eb.html) of CloudWatch Events. Both services use the same API, so you can continue using the [CloudWatch Events client](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/cloudwatch/CloudWatchClient.html) provided by the SDK or migrate to the SDK for Java's [EventBridge client](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/eventbridge/EventBridgeClient.html) for CloudWatch Events functionality. CloudWatch Events [User Guide documentation](https://docs.aws.amazon.com/eventbridge/latest/userguide/index.html) and [API reference](https://docs.aws.amazon.com/eventbridge/latest/APIReference/index.html) are now available through the EventBridge documentation sites. ## Add events To add custom CloudWatch events, call the `CloudWatchEventsClient’s` `putEvents` method with a [https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/cloudwatchevents/model/PutEventsRequest.html](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/cloudwatchevents/model/PutEventsRequest.html) object that contains one or more [https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/cloudwatchevents/model/PutEventsRequestEntry.html](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/cloudwatchevents/model/PutEventsRequestEntry.html) objects that provide details about each event. You can specify several parameters for the entry such as the source and type of the event, resources associated with the event, and so on. **Note** You can specify a maximum of 10 events per call to `putEvents`. **Imports** ``` import software.amazon.awssdk.services.cloudwatch.model.CloudWatchException; import software.amazon.awssdk.services.cloudwatchevents.CloudWatchEventsClient; import software.amazon.awssdk.services.cloudwatchevents.model.PutEventsRequest; import software.amazon.awssdk.services.cloudwatchevents.model.PutEventsRequestEntry; ``` **Code** ``` public static void putCWEvents(CloudWatchEventsClient cwe, String resourceArn ) { try { final String EVENT_DETAILS = "{ \"key1\": \"value1\", \"key2\": \"value2\" }"; PutEventsRequestEntry requestEntry = PutEventsRequestEntry.builder() .detail(EVENT_DETAILS) .detailType("sampleSubmitted") .resources(resourceArn) .source("aws-sdk-java-cloudwatch-example") .build(); PutEventsRequest request = PutEventsRequest.builder() .entries(requestEntry) .build(); cwe.putEvents(request); System.out.println("Successfully put CloudWatch event"); } catch (CloudWatchException e) { System.err.println(e.awsErrorDetails().errorMessage()); System.exit(1); } } ``` See the [complete example](https://github.com/awsdocs/aws-doc-sdk-examples/blob/0b1785e42949ebf959eaa0f0da4dc2a48f92ea25/javav2/example_code/cloudwatch/src/main/java/com/example/cloudwatch/PutEvents.java) on GitHub. ## Add rules To create or update a rule, call the `CloudWatchEventsClient’s` `putRule` method with a [https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/cloudwatchevents/model/PutRuleRequest.html](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/cloudwatchevents/model/PutRuleRequest.html) with the name of the rule and optional parameters such as the [event pattern](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-event-patterns.html), IAM role to associate with the rule, and a [scheduling expression](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-create-rule-schedule.html) that describes how often the rule is run. **Imports** ``` import software.amazon.awssdk.services.cloudwatch.model.CloudWatchException; import software.amazon.awssdk.services.cloudwatchevents.CloudWatchEventsClient; import software.amazon.awssdk.services.cloudwatchevents.model.PutRuleRequest; import software.amazon.awssdk.services.cloudwatchevents.model.PutRuleResponse; import software.amazon.awssdk.services.cloudwatchevents.model.RuleState; ``` **Code** ``` public static void putCWRule(CloudWatchEventsClient cwe, String ruleName, String roleArn) { try { PutRuleRequest request = PutRuleRequest.builder() .name(ruleName) .roleArn(roleArn) .scheduleExpression("rate(5 minutes)") .state(RuleState.ENABLED) .build(); PutRuleResponse response = cwe.putRule(request); System.out.printf( "Successfully created CloudWatch events rule %s with arn %s", roleArn, response.ruleArn()); } catch ( CloudWatchException e) { System.err.println(e.awsErrorDetails().errorMessage()); System.exit(1); } } ``` See the [complete example](https://github.com/awsdocs/aws-doc-sdk-examples/blob/0b1785e42949ebf959eaa0f0da4dc2a48f92ea25/javav2/example_code/cloudwatch/src/main/java/com/example/cloudwatch/PutRule.java) on GitHub. ## Add targets Targets are the resources that are invoked when a rule is triggered. Example targets include Amazon EC2 instances, Lambda functions, Kinesis streams, Amazon ECS tasks, Step Functions state machines, and built-in targets. To add a target to a rule, call the `CloudWatchEventsClient’s` `putTargets` method with a [https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/cloudwatchevents/model/PutTargetsRequest.html](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/cloudwatchevents/model/PutTargetsRequest.html) containing the rule to update and a list of targets to add to the rule. **Imports** ``` import software.amazon.awssdk.services.cloudwatch.model.CloudWatchException; import software.amazon.awssdk.services.cloudwatchevents.CloudWatchEventsClient; import software.amazon.awssdk.services.cloudwatchevents.model.PutTargetsRequest; import software.amazon.awssdk.services.cloudwatchevents.model.PutTargetsResponse; import software.amazon.awssdk.services.cloudwatchevents.model.Target; ``` **Code** ``` public static void putCWTargets(CloudWatchEventsClient cwe, String ruleName, String functionArn, String targetId ) { try { Target target = Target.builder() .arn(functionArn) .id(targetId) .build(); PutTargetsRequest request = PutTargetsRequest.builder() .targets(target) .rule(ruleName) .build(); PutTargetsResponse response = cwe.putTargets(request); System.out.printf( "Successfully created CloudWatch events target for rule %s", ruleName); } catch (CloudWatchException e) { System.err.println(e.awsErrorDetails().errorMessage()); System.exit(1); } } ``` See the [complete example](https://github.com/awsdocs/aws-doc-sdk-examples/blob/0b1785e42949ebf959eaa0f0da4dc2a48f92ea25/javav2/example_code/cloudwatch/src/main/java/com/example/cloudwatch/PutTargets.java) on GitHub. ## More information + [Adding Events with PutEvents](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-putevents.html) in the Amazon EventBridge User Guide + [Schedule Expressions for Rules](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-create-rule-schedule.html#eb-create-scheduled-rule-schedule) in the Amazon EventBridge User Guide + [Event Types for CloudWatch Events](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-service-event.html) in the Amazon EventBridge User Guide + [Event Patterns](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-event-patterns.html) in the Amazon EventBridge User Guide + [PutEvents](https://docs.aws.amazon.com/eventbridge/latest/APIReference/API_PutEvents.html) in the Amazon EventBridge API Reference + [PutTargets](https://docs.aws.amazon.com/eventbridge/latest/APIReference/API_PutTargets.html) in the Amazon EventBridge API Reference + [PutRule](https://docs.aws.amazon.com/eventbridge/latest/APIReference/API_PutRule.html) in the Amazon EventBridge API Reference