feat(elasticache): monitor Redis engine CPU utilization (#442)

Monitor engine utilization by default for Redis ElastiCache clusters. Optionally add alarms based on this metric.

Redis is single-threaded and the Redis thread's utilization is available via the EngineCPUUtilization metric. This metric provides visibility into the load of the redis process itself.

---

_By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license_

Author: Ansk0

API.md

@@ -60,10 +60,16 @@ export class UsageAlarmFactory {
     percentMetric: MetricWithAlarmSupport,
     props: UsageThreshold,
     disambiguator?: string,
-    usageType?: UsageType
+    usageType?: UsageType,
+    additionalAlarmNameSuffix?: string
   ) {
-    const alarmNameSuffix: string =
-      usageType === undefined ? "CPU-Usage" : `${usageType}-CPU-Usage`;
+    const alarmNameSuffix: string = [
+      usageType,
+      "CPU-Usage",
+      additionalAlarmNameSuffix,
+    ]
+      .filter((i) => i !== undefined)
+      .join("-");
     return this.alarmFactory.addAlarm(percentMetric, {
       treatMissingData:
         props.treatMissingDataOverride ?? TreatMissingData.MISSING,

lib/common/monitoring/alarms/UsageAlarmFactory.ts

@@ -112,6 +112,25 @@ export class ElastiCacheClusterMetricFactory {
     );
   }
 
+  /**
+   * Because Redis is single-threaded, you can use this metric to analyze the load of the Redis process itself.
+   * Note that you may want to monitor both Engine CPU Utilization as well as CPU Utilization as background
+   * processes can take up a significant portion of the CPU workload. This is especially important for
+   * hosts with 2 vCPUs or less.
+   *
+   * @see https://docs.aws.amazon.com/AmazonElastiCache/latest/red-ug/CacheMetrics.Redis.html
+   */
+  metricMaxRedisEngineCpuUtilizationInPercent() {
+    return this.metricFactory.createMetric(
+      "EngineCPUUtilization",
+      MetricStatistic.MAX,
+      "Cluster Engine CPU Utilization",
+      this.dimensionsMap,
+      undefined,
+      Namespace
+    );
+  }
+
   metricAverageConnections() {
     return this.metricFactory.createMetric(
       "CurrConnections",

lib/monitoring/aws-elasticache/ElastiCacheClusterMetricFactory.ts

@@ -1,4 +1,5 @@
 import {
+  Column,
   GraphWidget,
   HorizontalAnnotation,
   IWidget,
@@ -13,6 +14,7 @@ import {
   BaseMonitoringProps,
   CountAxisFromZero,
   DefaultGraphWidgetHeight,
+  DefaultTwoLinerGraphWidgetHalfHeight,
   DefaultSummaryWidgetHeight,
   ElastiCacheAlarmFactory,
   MaxItemsCountThreshold,
@@ -42,10 +44,18 @@ export interface ElastiCacheClusterMonitoringOptions
   readonly clusterType: ElastiCacheClusterType;
 
   /**
-   * Add CPU usage alarm
+   * Add CPU usage alarm (useful for all clusterTypes including Redis)
    */
   readonly addCpuUsageAlarm?: Record<string, UsageThreshold>;
 
+  /**
+   * Add Redis engine CPU usage alarm.
+   *
+   * It is recommended to monitor CPU utilization with `addCpuUsageAlarm`
+   * as well for hosts with two vCPUs or less.
+   */
+  readonly addRedisEngineCpuUsageAlarm?: Record<string, UsageThreshold>;
+
   /**
    * Add alarm on total number of items
    */
@@ -81,9 +91,11 @@ export interface ElastiCacheClusterMonitoringProps
 export class ElastiCacheClusterMonitoring extends Monitoring {
   readonly title: string;
   readonly clusterUrl?: string;
+  readonly clusterType: ElastiCacheClusterType;
 
   readonly connectionsMetric: MetricWithAlarmSupport;
   readonly cpuUsageMetric: MetricWithAlarmSupport;
+  readonly redisEngineCpuUsageMetric: MetricWithAlarmSupport;
   readonly freeableMemoryMetric: MetricWithAlarmSupport;
   readonly unusedMemoryMetric: MetricWithAlarmSupport;
   readonly swapMemoryMetric: MetricWithAlarmSupport;
@@ -94,6 +106,7 @@ export class ElastiCacheClusterMonitoring extends Monitoring {
   readonly usageAlarmFactory: UsageAlarmFactory;
   readonly elastiCacheAlarmFactory: ElastiCacheAlarmFactory;
   readonly cpuUsageAnnotations: HorizontalAnnotation[];
+  readonly redisEngineCpuUsageAnnotations: HorizontalAnnotation[];
   readonly itemsCountAnnotations: HorizontalAnnotation[];
   readonly evictedItemsCountAnnotations: HorizontalAnnotation[];
   readonly memoryUsageAnnotations: HorizontalAnnotation[];
@@ -104,6 +117,8 @@ export class ElastiCacheClusterMonitoring extends Monitoring {
   ) {
     super(scope, props);
 
+    this.clusterType = props.clusterType;
+
     const clusterType = capitalizeFirstLetterOnly(
       ElastiCacheClusterType[props.clusterType]
     );
@@ -127,6 +142,8 @@ export class ElastiCacheClusterMonitoring extends Monitoring {
     );
     this.connectionsMetric = metricFactory.metricAverageConnections();
     this.cpuUsageMetric = metricFactory.metricMaxCpuUtilizationInPercent();
+    this.redisEngineCpuUsageMetric =
+      metricFactory.metricMaxRedisEngineCpuUtilizationInPercent();
     this.freeableMemoryMetric =
       metricFactory.metricAverageFreeableMemoryInBytes();
     this.unusedMemoryMetric = metricFactory.metricAverageUnusedMemoryInBytes();
@@ -137,6 +154,7 @@ export class ElastiCacheClusterMonitoring extends Monitoring {
     this.itemsEvictedMetrics = metricFactory.metricEvictions();
 
     this.cpuUsageAnnotations = [];
+    this.redisEngineCpuUsageAnnotations = [];
     this.itemsCountAnnotations = [];
     this.evictedItemsCountAnnotations = [];
     this.memoryUsageAnnotations = [];
@@ -157,6 +175,29 @@ export class ElastiCacheClusterMonitoring extends Monitoring {
       this.cpuUsageAnnotations.push(createdAlarm.annotation);
       this.addAlarm(createdAlarm);
     }
+
+    if (
+      props.addRedisEngineCpuUsageAlarm !== undefined &&
+      props.clusterType !== ElastiCacheClusterType.REDIS
+    ) {
+      throw new Error(
+        "It is only possible to alarm on Redis Engine CPU Usage for Redis clusters"
+      );
+    }
+
+    for (const disambiguator in props.addRedisEngineCpuUsageAlarm) {
+      const alarmProps = props.addRedisEngineCpuUsageAlarm[disambiguator];
+      const createdAlarm = this.usageAlarmFactory.addMaxCpuUsagePercentAlarm(
+        this.redisEngineCpuUsageMetric,
+        alarmProps,
+        disambiguator,
+        undefined,
+        "RedisEngine"
+      );
+      this.redisEngineCpuUsageAnnotations.push(createdAlarm.annotation);
+      this.addAlarm(createdAlarm);
+    }
+
     for (const disambiguator in props.addMaxItemsCountAlarm) {
       const alarmProps = props.addMaxItemsCountAlarm[disambiguator];
       const createdAlarm = this.elastiCacheAlarmFactory.addMaxItemsCountAlarm(
@@ -214,13 +255,32 @@ export class ElastiCacheClusterMonitoring extends Monitoring {
   }
 
   widgets(): IWidget[] {
-    return [
-      this.createTitleWidget(),
-      this.createCpuUsageWidget(QuarterWidth, DefaultGraphWidgetHeight),
-      this.createMemoryUsageWidget(QuarterWidth, DefaultGraphWidgetHeight),
-      this.createConnectionsWidget(QuarterWidth, DefaultGraphWidgetHeight),
-      this.createItemCountWidget(QuarterWidth, DefaultGraphWidgetHeight),
-    ];
+    if (this.clusterType === ElastiCacheClusterType.REDIS) {
+      return [
+        this.createTitleWidget(),
+        new Column(
+          this.createCpuUsageWidget(
+            QuarterWidth,
+            DefaultTwoLinerGraphWidgetHalfHeight
+          ),
+          this.createRedisEngineCpuUsageWidget(
+            QuarterWidth,
+            DefaultTwoLinerGraphWidgetHalfHeight
+          )
+        ),
+        this.createMemoryUsageWidget(QuarterWidth, DefaultGraphWidgetHeight),
+        this.createConnectionsWidget(QuarterWidth, DefaultGraphWidgetHeight),
+        this.createItemCountWidget(QuarterWidth, DefaultGraphWidgetHeight),
+      ];
+    } else {
+      return [
+        this.createTitleWidget(),
+        this.createCpuUsageWidget(QuarterWidth, DefaultGraphWidgetHeight),
+        this.createMemoryUsageWidget(QuarterWidth, DefaultGraphWidgetHeight),
+        this.createConnectionsWidget(QuarterWidth, DefaultGraphWidgetHeight),
+        this.createItemCountWidget(QuarterWidth, DefaultGraphWidgetHeight),
+      ];
+    }
   }
 
   createTitleWidget() {
@@ -242,6 +302,17 @@ export class ElastiCacheClusterMonitoring extends Monitoring {
     });
   }
 
+  createRedisEngineCpuUsageWidget(width: number, height: number) {
+    return new GraphWidget({
+      width,
+      height,
+      title: "Engine CPU Utilization",
+      left: [this.redisEngineCpuUsageMetric],
+      leftYAxis: PercentageAxisFromZeroToHundred,
+      leftAnnotations: this.redisEngineCpuUsageAnnotations,
+    });
+  }
+
   createMemoryUsageWidget(width: number, height: number) {
     return new GraphWidget({
       width,

lib/monitoring/aws-elasticache/ElastiCacheClusterMonitoring.ts

@@ -52,6 +52,7 @@ test("snapshot test: all alarms", () => {
   new ElastiCacheClusterMonitoring(scope, {
     clusterType: ElastiCacheClusterType.REDIS,
     addCpuUsageAlarm: { Warning: { maxUsagePercent: 11 } },
+    addRedisEngineCpuUsageAlarm: { Warning: { maxUsagePercent: 10 } },
     addMaxItemsCountAlarm: { Warning: { maxItemsCount: 21 } },
     addMaxEvictedItemsCountAlarm: { Warning: { maxItemsCount: 31 } },
     addMinFreeableMemoryAlarm: { Warning: { minFreeableMemoryInBytes: 41 } },
@@ -64,7 +65,7 @@ test("snapshot test: all alarms", () => {
   });
 
   expect(numAlarmsCreatedForMemcached).toStrictEqual(5);
-  expect(numAlarmsCreatedForRedis).toStrictEqual(5);
+  expect(numAlarmsCreatedForRedis).toStrictEqual(6);
   expect(Template.fromStack(stack)).toMatchSnapshot();
 });
 
@@ -89,3 +90,18 @@ test("snapshot test: cluster ID specified", () => {
 
   expect(Template.fromStack(stack)).toMatchSnapshot();
 });
+
+test("validation test: redisEngineCpuUsageAlarm added for non-redis cluster ", () => {
+  const stack = new Stack();
+  const scope = new TestMonitoringScope(stack, "Scope");
+
+  expect(
+    () =>
+      new ElastiCacheClusterMonitoring(scope, {
+        clusterType: ElastiCacheClusterType.MEMCACHED,
+        addRedisEngineCpuUsageAlarm: { Warning: { maxUsagePercent: 10 } },
+      })
+  ).toThrowError(
+    "It is only possible to alarm on Redis Engine CPU Usage for Redis clusters"
+  );
+});