feat: add EC2Monitoring for network ingress/egress (#658)

Adding network egress and ingress monitoring to the EC2Monitoring.

This partially addresses:
#515

I tested this by deploying to my infrastructure and eyeballing the
dashboard and alarms from the console

```
monitoring.monitorEC2Instances({
        ...
        autoScalingGroup: autoscalingGroup,
        addNetworkOutTotalBytesExceedThresholdAlarm: {
          WARNING: {
            maxNetworkOutBytes: 1_000_000_000,
          },
        },
      });
```

<img width="1266" height="236" alt="ec2-network-monitoring"
src="https://github.com/user-attachments/assets/e07af62a-f3dd-49fb-b4b3-44e02317b7c7"
/>
Fixes #

---

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

---------

Co-authored-by: Jerzy 'Cedric' Zagorski <jzagorsk@amazon.com>

Author: xendo

API.md

@@ -0,0 +1,60 @@
+import {
+  ComparisonOperator,
+  TreatMissingData,
+} from "aws-cdk-lib/aws-cloudwatch";
+import { AlarmFactory, CustomAlarmThreshold } from "../../alarm";
+import { MetricWithAlarmSupport } from "../../metric";
+
+export interface NetworkOutThreshold extends CustomAlarmThreshold {
+  readonly maxNetworkOutBytes: number;
+}
+
+export interface NetworkInThreshold extends CustomAlarmThreshold {
+  readonly maxNetworkInBytes: number;
+}
+
+export class EC2AlarmFactory {
+  protected readonly alarmFactory: AlarmFactory;
+
+  constructor(alarmFactory: AlarmFactory) {
+    this.alarmFactory = alarmFactory;
+  }
+
+  addNetworkOutAlarm(
+    metric: MetricWithAlarmSupport,
+    props: NetworkOutThreshold,
+    disambiguator?: string,
+  ) {
+    return this.alarmFactory.addAlarm(metric, {
+      treatMissingData:
+        props.treatMissingDataOverride ?? TreatMissingData.MISSING,
+      comparisonOperator:
+        props.comparisonOperatorOverride ??
+        ComparisonOperator.GREATER_THAN_THRESHOLD,
+      ...props,
+      disambiguator,
+      threshold: props.maxNetworkOutBytes,
+      alarmNameSuffix: "NetworkOut",
+      alarmDescription: "Network out too high",
+    });
+  }
+
+  addNetworkInAlarm(
+    metric: MetricWithAlarmSupport,
+    props: NetworkInThreshold,
+    disambiguator?: string,
+  ) {
+    return this.alarmFactory.addAlarm(metric, {
+      treatMissingData:
+        props.treatMissingDataOverride ?? TreatMissingData.MISSING,
+      comparisonOperator:
+        props.comparisonOperatorOverride ??
+        ComparisonOperator.GREATER_THAN_THRESHOLD,
+      ...props,
+      disambiguator,
+      threshold: props.maxNetworkInBytes,
+      alarmNameSuffix: "NetworkIn",
+      alarmDescription: "Network in too high",
+    });
+  }
+}

lib/common/monitoring/alarms/EC2AlarmFactory.ts

@@ -4,6 +4,7 @@ export * from "./AuroraAlarmFactory";
 export * from "./CustomAlarmFactory";
 export * from "./ConnectionAlarmFactory";
 export * from "./DynamoAlarmFactory";
+export * from "./EC2AlarmFactory";
 export * from "./ElastiCacheAlarmFactory";
 export * from "./ErrorAlarmFactory";
 export * from "./KinesisAlarmFactory";

lib/common/monitoring/alarms/index.ts

@@ -6,6 +6,7 @@ import {
   BaseMetricFactoryProps,
   MetricFactory,
   MetricStatistic,
+  MetricWithAlarmSupport,
 } from "../../common";
 
 const EC2Namespace = "AWS/EC2";
@@ -17,7 +18,8 @@ export interface IEC2MetricFactoryStrategy {
     statistic: MetricStatistic,
     region?: string,
     account?: string,
-  ): IMetric[];
+    label?: string,
+  ): MetricWithAlarmSupport[];
 }
 
 /**
@@ -36,12 +38,13 @@ class AutoScalingGroupStrategy implements IEC2MetricFactoryStrategy {
     statistic: MetricStatistic,
     region?: string,
     account?: string,
+    label?: string,
   ) {
     return [
       metricFactory.createMetric(
         metricName,
         statistic,
-        undefined,
+        label,
         resolveDimensions(this.autoScalingGroup, undefined),
         undefined,
         EC2Namespace,
@@ -71,14 +74,15 @@ class SelectedInstancesStrategy implements IEC2MetricFactoryStrategy {
     statistic: MetricStatistic,
     region?: string,
     account?: string,
+    label?: string,
   ) {
     return this.instanceIds.map((instanceId) => {
       return metricFactory.createMetric(
         metricName,
         statistic,
         `${metricName} (${instanceId})`,
         resolveDimensions(this.autoScalingGroup, instanceId),
-        undefined,
+        label,
         EC2Namespace,
         undefined,
         region,
@@ -98,14 +102,15 @@ class AllInstancesStrategy implements IEC2MetricFactoryStrategy {
     statistic: MetricStatistic,
     region?: string,
     account?: string,
+    label?: string,
   ) {
     return [
       metricFactory.createMetricSearch(
         `MetricName="${metricName}"`,
         { InstanceId: undefined as unknown as string },
         statistic,
         EC2Namespace,
-        undefined,
+        label,
         undefined,
         region,
         account,
@@ -226,6 +231,22 @@ export class EC2MetricFactory extends BaseMetricFactory<EC2MetricFactoryProps> {
     return this.metric("NetworkOut", MetricStatistic.AVERAGE);
   }
 
+  /**
+   * The number of bytes received on all network interfaces by the instance.
+   * This metric identifies the volume of incoming network traffic to a single instance.
+   */
+  metricSumNetworkInRateBytes() {
+    return this.metric("NetworkIn", MetricStatistic.SUM, "Total NetworkIn");
+  }
+
+  /**
+   * The number of bytes sent out on all network interfaces by the instance.
+   * This metric identifies the volume of outgoing network traffic from a single instance.
+   */
+  metricSumNetworkOutRateBytes() {
+    return this.metric("NetworkOut", MetricStatistic.SUM, "Total NetworkOut");
+  }
+
   private createDiskMetrics(metricName: string, statistic: MetricStatistic) {
     const classicMetrics = this.strategy.createMetrics(
       this.metricFactory,
@@ -253,11 +274,18 @@ export class EC2MetricFactory extends BaseMetricFactory<EC2MetricFactoryProps> {
     });
   }
 
-  private metric(metricName: string, statistic: MetricStatistic) {
+  private metric(
+    metricName: string,
+    statistic: MetricStatistic,
+    label?: string,
+  ) {
     return this.strategy.createMetrics(
       this.metricFactory,
       metricName,
       statistic,
+      undefined,
+      undefined,
+      label,
     );
   }
 }

lib/monitoring/aws-ec2/EC2MetricFactory.ts

@@ -1,40 +1,69 @@
-import { GraphWidget, IMetric, IWidget } from "aws-cdk-lib/aws-cloudwatch";
+import {
+  GraphWidget,
+  HorizontalAnnotation,
+  IMetric,
+  IWidget,
+} from "aws-cdk-lib/aws-cloudwatch";
 
 import { EC2MetricFactory, EC2MetricFactoryProps } from "./EC2MetricFactory";
 import {
   BaseMonitoringProps,
   CountAxisFromZero,
   DefaultGraphWidgetHeight,
   DefaultSummaryWidgetHeight,
+  MetricWithAlarmSupport,
   Monitoring,
   MonitoringScope,
   PercentageAxisFromZeroToHundred,
   QuarterWidth,
   SizeAxisBytesFromZero,
   ThirdWidth,
 } from "../../common";
+import {
+  EC2AlarmFactory,
+  NetworkInThreshold,
+  NetworkOutThreshold,
+} from "../../common/monitoring/alarms/EC2AlarmFactory";
 import {
   MonitoringHeaderWidget,
   MonitoringNamingStrategy,
 } from "../../dashboard";
 
 export interface EC2MonitoringOptions
   extends EC2MetricFactoryProps,
-    BaseMonitoringProps {}
+    BaseMonitoringProps {
+  readonly addNetworkOutTotalBytesExceedThresholdAlarm?: Record<
+    string,
+    NetworkOutThreshold
+  >;
+
+  readonly addNetworkInTotalBytesExceedThresholdAlarm?: Record<
+    string,
+    NetworkInThreshold
+  >;
+}
 
 export interface EC2MonitoringProps extends EC2MonitoringOptions {}
 
 export class EC2Monitoring extends Monitoring {
   readonly family: string;
   readonly title: string;
 
+  readonly ec2AlarmFactory: EC2AlarmFactory;
+
   readonly cpuUtilisationMetrics: IMetric[];
   readonly diskReadBytesMetrics: IMetric[];
   readonly diskWriteBytesMetrics: IMetric[];
   readonly diskReadOpsMetrics: IMetric[];
   readonly diskWriteOpsMetrics: IMetric[];
-  readonly networkInMetrics: IMetric[];
-  readonly networkOutMetrics: IMetric[];
+  readonly networkInMetrics: MetricWithAlarmSupport[];
+  readonly networkOutMetrics: MetricWithAlarmSupport[];
+
+  readonly networkInSumMetrics: MetricWithAlarmSupport[];
+  readonly networkOutSumMetrics: MetricWithAlarmSupport[];
+
+  readonly networkInSumLimitAnnotations: HorizontalAnnotation[];
+  readonly networkOutSumLimitAnnotations: HorizontalAnnotation[];
 
   constructor(scope: MonitoringScope, props: EC2MonitoringProps) {
     super(scope, props);
@@ -48,11 +77,28 @@ export class EC2Monitoring extends Monitoring {
     });
     this.family = props.autoScalingGroup ? "EC2 Auto Scaling Group" : "EC2";
     this.title = namingStrategy.resolveHumanReadableName();
+    this.networkOutSumLimitAnnotations = [];
+    this.networkInSumLimitAnnotations = [];
 
     const metricFactory = new EC2MetricFactory(
       scope.createMetricFactory(),
       props,
     );
+
+    // using different fallback alarm construct name
+    // as alarms don't allow whitespace
+    const fallbackAlarmConstructName = props.autoScalingGroup
+      ? props.autoScalingGroup.autoScalingGroupName
+      : "All-Instances";
+    const namingAlarmStrategy = new MonitoringNamingStrategy({
+      ...props,
+      fallbackConstructName: fallbackAlarmConstructName,
+    });
+    const alarmFactory = this.createAlarmFactory(
+      namingAlarmStrategy.resolveAlarmFriendlyName(),
+    );
+    this.ec2AlarmFactory = new EC2AlarmFactory(alarmFactory);
+
     this.cpuUtilisationMetrics =
       metricFactory.metricAverageCpuUtilisationPercent();
     this.diskReadBytesMetrics = metricFactory.metricAverageDiskReadBytes();
@@ -61,6 +107,47 @@ export class EC2Monitoring extends Monitoring {
     this.diskWriteOpsMetrics = metricFactory.metricAverageDiskWriteOps();
     this.networkInMetrics = metricFactory.metricAverageNetworkInRateBytes();
     this.networkOutMetrics = metricFactory.metricAverageNetworkOutRateBytes();
+
+    this.networkInSumMetrics = metricFactory.metricSumNetworkInRateBytes();
+    this.networkOutSumMetrics = metricFactory.metricSumNetworkOutRateBytes();
+
+    for (const disambiguator in props.addNetworkInTotalBytesExceedThresholdAlarm) {
+      const alarmProps =
+        props.addNetworkInTotalBytesExceedThresholdAlarm[disambiguator];
+
+      const createdAlarms = this.networkInMetrics.map((metric) => {
+        const createdAlarm = this.ec2AlarmFactory.addNetworkInAlarm(
+          metric,
+          alarmProps,
+          disambiguator,
+        );
+        this.addAlarm(createdAlarm);
+        return createdAlarm;
+      });
+
+      if (createdAlarms.length > 0) {
+        this.networkInSumLimitAnnotations.push(createdAlarms[0].annotation);
+      }
+    }
+
+    for (const disambiguator in props.addNetworkOutTotalBytesExceedThresholdAlarm) {
+      const alarmProps =
+        props.addNetworkOutTotalBytesExceedThresholdAlarm[disambiguator];
+      const createdAlarms = this.networkOutSumMetrics.map((metric) => {
+        const createdAlarm = this.ec2AlarmFactory.addNetworkOutAlarm(
+          metric,
+          alarmProps,
+          disambiguator,
+        );
+        this.addAlarm(createdAlarm);
+        return createdAlarm;
+      });
+
+      if (createdAlarms.length > 0) {
+        this.networkOutSumLimitAnnotations.push(createdAlarms[0].annotation);
+      }
+    }
+    props.useCreatedAlarms?.consume(this.createdAlarms());
   }
 
   summaryWidgets(): IWidget[] {
@@ -135,6 +222,12 @@ export class EC2Monitoring extends Monitoring {
       title: "Network",
       left: [...this.networkInMetrics, ...this.networkOutMetrics],
       leftYAxis: SizeAxisBytesFromZero,
+      right: [...this.networkInSumMetrics, ...this.networkOutSumMetrics],
+      rightYAxis: SizeAxisBytesFromZero,
+      rightAnnotations: [
+        ...this.networkInSumLimitAnnotations,
+        ...this.networkOutSumLimitAnnotations,
+      ],
     });
   }
 }