There are more AWS SDK examples available in the [AWS Doc SDK Examples](https://github.com/awsdocs/aws-doc-sdk-examples) GitHub repo.
# Use `GetMetricData` with an AWS SDK or CLI
The following code examples show how to use `GetMetricData`.
Action examples are code excerpts from larger programs and must be run in context. You can see this action in context in the following code examples:
+ [Learn the basics](cloudwatch_example_cloudwatch_GetStartedMetricsDashboardsAlarms_section.md)
+ [Run CPU stress tests on EC2 instances using FIS](cloudwatch_example_iam_GettingStarted_069_section.md)
------
#### [ .NET ]
**SDK for .NET (v4)**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/dotnetv4/CloudWatch#code-examples).
```
///
/// Get data for CloudWatch metrics.
///
/// The number of minutes of data to include.
/// True to return the data descending by time.
/// The end date for the data, in UTC.
/// The maximum data points to include.
/// Optional data queries to include.
/// A list of the requested metric data.
public async Task> GetMetricData(int minutesOfData, bool useDescendingTime, DateTime? endDateUtc = null,
int maxDataPoints = 0, List? dataQueries = null)
{
var metricData = new List();
// If no end time is provided, use the current time for the end time.
endDateUtc ??= DateTime.UtcNow;
var timeZoneOffset = TimeZoneInfo.Local.GetUtcOffset(endDateUtc.Value.ToLocalTime());
var startTimeUtc = endDateUtc.Value.AddMinutes(-minutesOfData);
// The timezone string should be in the format +0000, so use the timezone offset to format it correctly.
var timeZoneString = $"{timeZoneOffset.Hours:D2}{timeZoneOffset.Minutes:D2}";
// Add the plus sign for positive offsets.
timeZoneString = timeZoneString.StartsWith('-') ? timeZoneString : "+" + timeZoneString;
var paginatedMetricData = _amazonCloudWatch.Paginators.GetMetricData(
new GetMetricDataRequest()
{
StartTimeUtc = startTimeUtc,
EndTimeUtc = endDateUtc.Value,
LabelOptions = new LabelOptions { Timezone = timeZoneString },
ScanBy = useDescendingTime ? ScanBy.TimestampDescending : ScanBy.TimestampAscending,
MaxDatapoints = maxDataPoints,
MetricDataQueries = dataQueries,
});
if (paginatedMetricData.MetricDataResults != null)
{
await foreach (var data in paginatedMetricData.MetricDataResults)
{
metricData.Add(data);
}
}
return metricData;
}
```
+ For API details, see [GetMetricData](https://docs.aws.amazon.com/goto/DotNetSDKV4/monitoring-2010-08-01/GetMetricData) in *AWS SDK for .NET API Reference*.
------
#### [ CLI ]
**AWS CLI**
**Example 1: To get the Average Total IOPS for the specified EC2 using math expression**
The following `get-metric-data` example retrieves CloudWatch metric values for the EC2 instance with InstanceID `i-abcdef` using metric math exprssion that combines `EBSReadOps` and `EBSWriteOps` metrics.
```
aws cloudwatch get-metric-data \
--metric-data-queries file://file.json \
--start-time 2024-09-29T22:10:00Z \
--end-time 2024-09-29T22:15:00Z
```
Contents of `file.json`:
```
[
{
"Id": "m3",
"Expression": "(m1+m2)/300",
"Label": "Avg Total IOPS"
},
{
"Id": "m1",
"MetricStat": {
"Metric": {
"Namespace": "AWS/EC2",
"MetricName": "EBSReadOps",
"Dimensions": [
{
"Name": "InstanceId",
"Value": "i-abcdef"
}
]
},
"Period": 300,
"Stat": "Sum",
"Unit": "Count"
},
"ReturnData": false
},
{
"Id": "m2",
"MetricStat": {
"Metric": {
"Namespace": "AWS/EC2",
"MetricName": "EBSWriteOps",
"Dimensions": [
{
"Name": "InstanceId",
"Value": "i-abcdef"
}
]
},
"Period": 300,
"Stat": "Sum",
"Unit": "Count"
},
"ReturnData": false
}
]
```
Output:
```
{
"MetricDataResults": [
{
"Id": "m3",
"Label": "Avg Total IOPS",
"Timestamps": [
"2024-09-29T22:10:00+00:00"
],
"Values": [
96.85
],
"StatusCode": "Complete"
}
],
"Messages": []
}
```
**Example 2: To monitor the estimated AWS charges using CloudWatch billing metrics**
The following `get-metric-data` example retrieves `EstimatedCharges` CloudWatch metric from AWS/Billing namespace.
```
aws cloudwatch get-metric-data \
--metric-data-queries '[{"Id":"m1","MetricStat":{"Metric":{"Namespace":"AWS/Billing","MetricName":"EstimatedCharges","Dimensions":[{"Name":"Currency","Value":"USD"}]},"Period":21600,"Stat":"Maximum"}}]' \
--start-time 2024-09-26T12:00:00Z \
--end-time 2024-09-26T18:00:00Z \
--region us-east-1
```
Output:
```
{
"MetricDataResults": [
{
"Id": "m1",
"Label": "EstimatedCharges",
"Timestamps": [
"2024-09-26T12:00:00+00:00"
],
"Values": [
542.38
],
"StatusCode": "Complete"
}
],
"Messages": []
}
```
For more information, see [Using math expressions with CloudWatch metrics](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/using-metric-math.html) in the *Amazon CloudWatch User Guide*.
+ For API details, see [GetMetricData](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/cloudwatch/get-metric-data.html) in *AWS CLI Command Reference*.
------
#### [ Java ]
**SDK for Java 2.x**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javav2/example_code/cloudwatch#code-examples).
```
/**
* Retrieves custom metric data from the AWS CloudWatch service.
*
* @param fileName the name of the file containing the custom metric information
* @return a {@link CompletableFuture} that completes when the metric data has been retrieved
*/
public CompletableFuture getCustomMetricDataAsync(String fileName) {
CompletableFuture readFileFuture = CompletableFuture.supplyAsync(() -> {
try {
// Read values from the JSON file.
JsonParser parser = new JsonFactory().createParser(new File(fileName));
com.fasterxml.jackson.databind.JsonNode rootNode = new ObjectMapper().readTree(parser);
return rootNode.toString(); // Return JSON as a string for further processing
} catch (IOException e) {
throw new RuntimeException("Failed to read file", e);
}
});
return readFileFuture.thenCompose(jsonContent -> {
try {
// Parse the JSON string to extract relevant values.
com.fasterxml.jackson.databind.JsonNode rootNode = new ObjectMapper().readTree(jsonContent);
String customMetricNamespace = rootNode.findValue("customMetricNamespace").asText();
String customMetricName = rootNode.findValue("customMetricName").asText();
// Set the current time and date range for metric query.
Instant nowDate = Instant.now();
long hours = 1;
long minutes = 30;
Instant endTime = nowDate.plus(hours, ChronoUnit.HOURS).plus(minutes, ChronoUnit.MINUTES);
Metric met = Metric.builder()
.metricName(customMetricName)
.namespace(customMetricNamespace)
.build();
MetricStat metStat = MetricStat.builder()
.stat("Maximum")
.period(60) // Assuming period in seconds
.metric(met)
.build();
MetricDataQuery dataQuery = MetricDataQuery.builder()
.metricStat(metStat)
.id("foo2")
.returnData(true)
.build();
List dq = new ArrayList<>();
dq.add(dataQuery);
GetMetricDataRequest getMetricDataRequest = GetMetricDataRequest.builder()
.maxDatapoints(10)
.scanBy(ScanBy.TIMESTAMP_DESCENDING)
.startTime(nowDate)
.endTime(endTime)
.metricDataQueries(dq)
.build();
// Call the async method for CloudWatch data retrieval.
return getAsyncClient().getMetricData(getMetricDataRequest);
} catch (IOException e) {
throw new RuntimeException("Failed to parse JSON content", e);
}
}).thenAccept(response -> {
List data = response.metricDataResults();
for (MetricDataResult item : data) {
logger.info("The label is: {}", item.label());
logger.info("The status code is: {}", item.statusCode().toString());
}
}).exceptionally(exception -> {
throw new RuntimeException("Failed to get metric data", exception);
});
}
```
+ For API details, see [GetMetricData](https://docs.aws.amazon.com/goto/SdkForJavaV2/monitoring-2010-08-01/GetMetricData) in *AWS SDK for Java 2.x API Reference*.
------
#### [ Kotlin ]
**SDK for Kotlin**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/kotlin/services/cloudwatch#code-examples).
```
suspend fun getCustomMetricData(fileName: String) {
// Read values from the JSON file.
val parser = JsonFactory().createParser(File(fileName))
val rootNode = ObjectMapper().readTree(parser)
val customMetricNamespace = rootNode.findValue("customMetricNamespace").asText()
val customMetricName = rootNode.findValue("customMetricName").asText()
// Set the date.
val nowDate = Instant.now()
val hours: Long = 1
val minutes: Long = 30
val date2 =
nowDate.plus(hours, ChronoUnit.HOURS).plus(
minutes,
ChronoUnit.MINUTES,
)
val met =
Metric {
metricName = customMetricName
namespace = customMetricNamespace
}
val metStat =
MetricStat {
stat = "Maximum"
period = 1
metric = met
}
val dataQUery =
MetricDataQuery {
metricStat = metStat
id = "foo2"
returnData = true
}
val dq = ArrayList()
dq.add(dataQUery)
val getMetReq =
GetMetricDataRequest {
maxDatapoints = 10
scanBy = ScanBy.TimestampDescending
startTime =
aws.smithy.kotlin.runtime.time
.Instant(nowDate)
endTime =
aws.smithy.kotlin.runtime.time
.Instant(date2)
metricDataQueries = dq
}
CloudWatchClient.fromEnvironment { region = "us-east-1" }.use { cwClient ->
val response = cwClient.getMetricData(getMetReq)
response.metricDataResults?.forEach { item ->
println("The label is ${item.label}")
println("The status code is ${item.statusCode}")
}
}
}
```
+ For API details, see [GetMetricData](https://sdk.amazonaws.com/kotlin/api/latest/index.html) in *AWS SDK for Kotlin API reference*.
------