AWS AmazonCloudWatch: Add PromQL alarm examples for CloudWatch across SDKs
Summary
Adds code snippets to the PutMetricAlarm documentation showing how to create PromQL-based metric alarms (EvaluationCriteria/PromQLCriteria with query, pending/recovery periods, EvaluationInterval) in C#, C++, Java, JavaScript, Kotlin, Python, and Ruby, and renames a link to 'Manage custom metrics and alarms'. No security guidance or vulnerability is referenced.
Security assessment
The change is purely additive API usage documentation demonstrating how to construct a PromQL alarm request; it contains no authentication, encryption, IAM, credential, or vulnerability-related content, so it does not address any specific weakness or document a security control.
Evidence
+Create an alarm that evaluates a PromQL query against OpenTelemetry metrics.
Diff
diff --git a/AmazonCloudWatch/latest/monitoring/example_cloudwatch_PutMetricAlarm_section.md b/AmazonCloudWatch/latest/monitoring/example_cloudwatch_PutMetricAlarm_section.md index bb906c99b..7f0a59a69 100644 --- a//AmazonCloudWatch/latest/monitoring/example_cloudwatch_PutMetricAlarm_section.md +++ b//AmazonCloudWatch/latest/monitoring/example_cloudwatch_PutMetricAlarm_section.md @@ -17 +17 @@ Action examples are code excerpts from larger programs and must be run in contex - * [Manage metrics and alarms](./example_cloudwatch_Usage_MetricsAlarms_section.html) + * [Manage custom metrics and alarms](./example_cloudwatch_Usage_MetricsAlarms_section.html) @@ -20,0 +21,2 @@ Action examples are code excerpts from larger programs and must be run in contex + * [Send OpenTelemetry metrics and alarm on them with PromQL](./example_cloudwatch_Scenario_OTelMetrics_section.html) + @@ -33,0 +36,57 @@ There's more on GitHub. Find the complete example and learn how to set up and ru +Create an alarm that evaluates a PromQL query against OpenTelemetry metrics. + + + /// <summary> + /// Create an alarm that evaluates a PromQL query. + /// + /// A PromQL alarm differs from a classic metric alarm in a few ways. The query can + /// match many series at once, and each matching series is tracked separately as a + /// contributor. Instead of counting breaching periods, you specify durations: a + /// contributor moves to ALARM after it breaches continuously for the pending period, + /// and back to OK after it stops breaching for the recovery period. A PromQL alarm + /// starts in the OK state rather than INSUFFICIENT_DATA. + /// + /// EvaluationCriteria is a union and is mutually exclusive with the classic + /// MetricName and Metrics properties. When you use it you must also set + /// EvaluationInterval, and you must not set Period, Statistic, Threshold, + /// ComparisonOperator, EvaluationPeriods, DatapointsToAlarm, or TreatMissingData. + /// </summary> + /// <param name="alarmName">The name of the alarm, unique within the Region.</param> + /// <param name="query">The PromQL query to evaluate, such as + /// avg(cpu_utilization_percent) > 80. The comparison belongs in the query itself; + /// there is no separate threshold property.</param> + /// <param name="evaluationInterval">How often, in seconds, to run the query. Valid + /// values are 10, 20, 30, and any multiple of 60, up to 3600.</param> + /// <param name="pendingPeriod">How long, in seconds, a contributor must breach + /// continuously before it moves to ALARM.</param> + /// <param name="recoveryPeriod">How long, in seconds, a contributor must stop + /// breaching before it moves back to OK.</param> + /// <returns>True if successful.</returns> + public async Task<bool> PutPromQLMetricAlarm(string alarmName, string query, + int evaluationInterval = 60, int pendingPeriod = 300, int recoveryPeriod = 120) + { + var response = await _amazonCloudWatch.PutMetricAlarmAsync( + new PutMetricAlarmRequest + { + AlarmName = alarmName, + AlarmDescription = "A PromQL alarm created by the AWS SDK for .NET example.", + EvaluationCriteria = new EvaluationCriteria + { + PromQLCriteria = new AlarmPromQLCriteria + { + Query = query, + PendingPeriod = pendingPeriod, + RecoveryPeriod = recoveryPeriod + } + }, + EvaluationInterval = evaluationInterval + }); + + _logger.LogInformation($"Created PromQL alarm {alarmName} for query {query}."); + return response.HttpStatusCode == System.Net.HttpStatusCode.OK; + } + + + +Create an alarm that evaluates a single CloudWatch metric. + @@ -111 +170,49 @@ There's more on GitHub. Find the complete example and learn how to set up and ru -Include the required files. +Include the required files for a PromQL alarm. + + + #include <aws/core/Aws.h> + #include <aws/monitoring/CloudWatchClient.h> + #include <aws/monitoring/model/AlarmPromQLCriteria.h> + #include <aws/monitoring/model/EvaluationCriteria.h> + #include <aws/monitoring/model/PutMetricAlarmRequest.h> + #include <iostream> + + + +Create an alarm that evaluates a PromQL query against OpenTelemetry metrics. + + + Aws::Client::ClientConfiguration clientConfig; + // Optional: Set to the AWS Region (overrides config file). + // clientConfig.region = "us-east-1"; + Aws::CloudWatch::CloudWatchClient cw(clientConfig); + + Aws::CloudWatch::Model::AlarmPromQLCriteria promQLCriteria; + promQLCriteria.SetQuery(query); + // A contributor moves to ALARM after breaching continuously for 300 seconds, + // and back to OK after 120 seconds without breaching. + promQLCriteria.SetPendingPeriod(300); + promQLCriteria.SetRecoveryPeriod(120); + + Aws::CloudWatch::Model::EvaluationCriteria evaluationCriteria; + evaluationCriteria.SetPromQLCriteria(promQLCriteria); + + Aws::CloudWatch::Model::PutMetricAlarmRequest request; + request.SetAlarmName(alarm_name); + request.SetAlarmDescription("A PromQL alarm created by the AWS SDK for C++."); + request.SetEvaluationCriteria(evaluationCriteria); + // Valid values are 10, 20, 30, and any multiple of 60, up to 3600. + request.SetEvaluationInterval(30); + + auto outcome = cw.PutMetricAlarm(request); + if (!outcome.IsSuccess()) { + std::cerr << "Failed to create PromQL alarm: " + << outcome.GetError().GetMessage() << std::endl; + } else { + std::cout << "Successfully created PromQL alarm " << alarm_name + << " for query " << query << std::endl; + } + + + +Include the required files for a metric alarm. @@ -202,0 +310,64 @@ There's more on GitHub. Find the complete example and learn how to set up and ru +Create an alarm that evaluates a PromQL query against OpenTelemetry metrics. + + + /** + * Creates an alarm that evaluates a PromQL query. + * + * <p>A PromQL alarm differs from a classic metric alarm in a few ways. The query + * can match many series at once, and each matching series is tracked separately as + * a contributor. Instead of counting breaching periods, you specify durations: a + * contributor moves to ALARM after it breaches continuously for the pending period, + * and back to OK after it stops breaching for the recovery period. A PromQL alarm + * starts in the OK state rather than INSUFFICIENT_DATA. + * + * <p>{@link EvaluationCriteria} is a union and is mutually exclusive with the + * classic {@code metricName} and {@code metrics} parameters. When you use it you + * must also set {@code evaluationInterval}, and you must not set {@code period}, + * {@code statistic}, {@code threshold}, {@code comparisonOperator}, + * {@code evaluationPeriods}, {@code datapointsToAlarm}, or + * {@code treatMissingData}. + * + * @param cw the CloudWatch client + * @param alarmName the name of the alarm, unique within the Region + * @param query the PromQL query to evaluate, such as + * {@code avg(cpu_utilization_percent) > 80}. The + * comparison belongs in the query itself; there is no + * separate threshold parameter. + * @param evaluationInterval how often, in seconds, to run the query. Valid values + * are 10, 20, 30, and any multiple of 60, up to 3600. + * @param pendingPeriod how long, in seconds, a contributor must breach + * continuously before it moves to ALARM + * @param recoveryPeriod how long, in seconds, a contributor must stop breaching + * before it moves back to OK + */ + public static void putPromQLMetricAlarm(CloudWatchClient cw, String alarmName, String query, + int evaluationInterval, int pendingPeriod, int recoveryPeriod) { + try { + AlarmPromQLCriteria promQLCriteria = AlarmPromQLCriteria.builder() + .query(query) + .pendingPeriod(pendingPeriod) + .recoveryPeriod(recoveryPeriod) + .build(); + + PutMetricAlarmRequest request = PutMetricAlarmRequest.builder() + .alarmName(alarmName) + .alarmDescription("PromQL alarm created by the AWS SDK for Java 2.x example.") + .evaluationCriteria(EvaluationCriteria.builder() + .promQLCriteria(promQLCriteria) + .build()) + .evaluationInterval(evaluationInterval) + .build(); + + cw.putMetricAlarm(request); + System.out.printf("Created PromQL alarm %s for query %s.%n", alarmName, query); + + } catch (CloudWatchException e) { + System.err.println(e.awsErrorDetails().errorMessage()); + System.exit(1); + } + } + + + +Create an alarm that evaluates a single CloudWatch metric. + @@ -277 +448,50 @@ There's more on GitHub. Find the complete example and learn how to set up and ru -Import the SDK and client modules and call the API. +Create an alarm that evaluates a PromQL query against OpenTelemetry metrics. + + + import { PutMetricAlarmCommand } from "@aws-sdk/client-cloudwatch"; + import { client } from "../libs/client.js"; + + // Create an alarm that evaluates a PromQL query over OpenTelemetry metrics. + // + // A PromQL alarm differs from a classic metric alarm in a few ways. The query can match + // many series at once, and each matching series is tracked separately as a contributor + // (see describe-alarm-contributors.js). Instead of counting breaching periods, you + // specify durations: a contributor moves to ALARM after it breaches continuously for + // PendingPeriod seconds, and back to OK after it stops breaching for RecoveryPeriod + // seconds. A PromQL alarm starts in OK rather than INSUFFICIENT_DATA.