There are more AWS SDK examples available in the [AWS Doc SDK Examples](https://github.com/awsdocs/aws-doc-sdk-examples) GitHub repo.
# Use `DescribeAlarmHistory` with an AWS SDK or CLI
The following code examples show how to use `DescribeAlarmHistory`.
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 example:
+ [Learn the basics](cloudwatch_example_cloudwatch_GetStartedMetricsDashboardsAlarms_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).
```
///
/// Describe the history of an alarm for a number of days in the past.
///
/// The name of the alarm.
/// The number of days in the past.
/// The list of alarm history data.
public async Task> DescribeAlarmHistory(string alarmName, int historyDays)
{
List alarmHistory = new List();
var paginatedAlarmHistory = _amazonCloudWatch.Paginators.DescribeAlarmHistory(
new DescribeAlarmHistoryRequest()
{
AlarmName = alarmName,
EndDateUtc = DateTime.UtcNow,
HistoryItemType = HistoryItemType.StateUpdate,
StartDateUtc = DateTime.UtcNow.AddDays(-historyDays)
});
await foreach (var data in paginatedAlarmHistory.AlarmHistoryItems)
{
alarmHistory.Add(data);
}
return alarmHistory;
}
```
+ For API details, see [DescribeAlarmHistory](https://docs.aws.amazon.com/goto/DotNetSDKV4/monitoring-2010-08-01/DescribeAlarmHistory) in *AWS SDK for .NET API Reference*.
------
#### [ CLI ]
**AWS CLI**
**To retrieve history for an alarm**
The following example uses the `describe-alarm-history` command to retrieve history for the Amazon CloudWatch alarm named "myalarm":
```
aws cloudwatch describe-alarm-history --alarm-name "myalarm" --history-item-type StateUpdate
```
Output:
```
{
"AlarmHistoryItems": [
{
"Timestamp": "2014-04-09T18:59:06.442Z",
"HistoryItemType": "StateUpdate",
"AlarmName": "myalarm",
"HistoryData": "{\"version\":\"1.0\",\"oldState\":{\"stateValue\":\"ALARM\",\"stateReason\":\"testing purposes\"},\"newState\":{\"stateValue\":\"OK\",\"stateReason\":\"Threshold Crossed: 2 datapoints were not greater than the threshold (70.0). The most recent datapoints: [38.958, 40.292].\",\"stateReasonData\":{\"version\":\"1.0\",\"queryDate\":\"2014-04-09T18:59:06.419+0000\",\"startDate\":\"2014-04-09T18:44:00.000+0000\",\"statistic\":\"Average\",\"period\":300,\"recentDatapoints\":[38.958,40.292],\"threshold\":70.0}}}",
"HistorySummary": "Alarm updated from ALARM to OK"
},
{
"Timestamp": "2014-04-09T18:59:05.805Z",
"HistoryItemType": "StateUpdate",
"AlarmName": "myalarm",
"HistoryData": "{\"version\":\"1.0\",\"oldState\":{\"stateValue\":\"OK\",\"stateReason\":\"Threshold Crossed: 2 datapoints were not greater than the threshold (70.0). The most recent datapoints: [38.839999999999996, 39.714].\",\"stateReasonData\":{\"version\":\"1.0\",\"queryDate\":\"2014-03-11T22:45:41.569+0000\",\"startDate\":\"2014-03-11T22:30:00.000+0000\",\"statistic\":\"Average\",\"period\":300,\"recentDatapoints\":[38.839999999999996,39.714],\"threshold\":70.0}},\"newState\":{\"stateValue\":\"ALARM\",\"stateReason\":\"testing purposes\"}}",
"HistorySummary": "Alarm updated from OK to ALARM"
}
]
}
```
+ For API details, see [DescribeAlarmHistory](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/cloudwatch/describe-alarm-history.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 the alarm history for a given alarm name and date range.
*
* @param fileName the path to the JSON file containing the alarm name
* @param date the date to start the alarm history search (in the format "yyyy-MM-dd'T'HH:mm:ss'Z'")
* @return a {@code CompletableFuture} that completes when the alarm history has been retrieved and processed
*/
public CompletableFuture getAlarmHistoryAsync(String fileName, String date) {
CompletableFuture readFileFuture = CompletableFuture.supplyAsync(() -> {
try {
JsonParser parser = new JsonFactory().createParser(new File(fileName));
com.fasterxml.jackson.databind.JsonNode rootNode = new ObjectMapper().readTree(parser);
return rootNode.findValue("exampleAlarmName").asText(); // Return alarmName from the JSON file
} catch (IOException e) {
throw new RuntimeException("Failed to read or parse the file", e);
}
});
// Use the alarm name to describe alarm history with a paginator.
return readFileFuture.thenCompose(alarmName -> {
try {
Instant start = Instant.parse(date);
Instant endDate = Instant.now();
DescribeAlarmHistoryRequest historyRequest = DescribeAlarmHistoryRequest.builder()
.startDate(start)
.endDate(endDate)
.alarmName(alarmName)
.historyItemType(HistoryItemType.ACTION)
.build();
// Use the paginator to paginate through alarm history pages.
DescribeAlarmHistoryPublisher historyPublisher = getAsyncClient().describeAlarmHistoryPaginator(historyRequest);
CompletableFuture future = historyPublisher
.subscribe(response -> response.alarmHistoryItems().forEach(item -> {
logger.info("History summary: {}", item.historySummary());
logger.info("Timestamp: {}", item.timestamp());
}))
.whenComplete((result, exception) -> {
if (exception != null) {
logger.error("Error occurred while getting alarm history: " + exception.getMessage(), exception);
} else {
logger.info("Successfully retrieved all alarm history.");
}
});
// Return the future to the calling code for further handling
return future;
} catch (Exception e) {
throw new RuntimeException("Failed to process alarm history", e);
}
}).whenComplete((result, exception) -> {
if (exception != null) {
throw new RuntimeException("Error completing alarm history processing", exception);
}
});
}
```
+ For API details, see [DescribeAlarmHistory](https://docs.aws.amazon.com/goto/SdkForJavaV2/monitoring-2010-08-01/DescribeAlarmHistory) 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 getAlarmHistory(
fileName: String,
date: String,
) {
// Read values from the JSON file.
val parser = JsonFactory().createParser(File(fileName))
val rootNode = ObjectMapper().readTree(parser)
val alarmNameVal = rootNode.findValue("exampleAlarmName").asText()
val start = Instant.parse(date)
val endDateVal = Instant.now()
val historyRequest =
DescribeAlarmHistoryRequest {
startDate =
aws.smithy.kotlin.runtime.time
.Instant(start)
endDate =
aws.smithy.kotlin.runtime.time
.Instant(endDateVal)
alarmName = alarmNameVal
historyItemType = HistoryItemType.Action
}
CloudWatchClient.fromEnvironment { region = "us-east-1" }.use { cwClient ->
val response = cwClient.describeAlarmHistory(historyRequest)
val historyItems = response.alarmHistoryItems
if (historyItems != null) {
if (historyItems.isEmpty()) {
println("No alarm history data found for $alarmNameVal.")
} else {
for (item in historyItems) {
println("History summary ${item.historySummary}")
println("Time stamp: ${item.timestamp}")
}
}
}
}
}
```
+ For API details, see [DescribeAlarmHistory](https://sdk.amazonaws.com/kotlin/api/latest/index.html) in *AWS SDK for Kotlin API reference*.
------