feat(lambda): Add widget and alarms on init duration (#646)

Fixes #462

Add `init_duration` to `LambdaFunctionMonitoring`. Monitoring INIT has
become increasingly important due to:

1. Lambda now bills for the INIT phase.
[Blog](https://aws.amazon.com/blogs/compute/aws-lambda-standardizes-billing-for-init-phase/).
2. With the growing adoption of Provisioned Concurrency and SnapStart,
people want visibility into INIT durations.

While making changes for the PR, I noticed an issue with how the
function cost is calculated
(#645). I’ll
fix that next and also include INIT as part of the cost calculation.

<img width="1458" alt="image"
src="https://github.com/user-attachments/assets/5e0b53ce-304c-4ae6-94ff-e2d1e30b05ad"
/>
---

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

Author: Laxenade

API.md

@@ -246,6 +246,41 @@ export class LatencyAlarmFactory {
     });
   }
 
+  addCustomDurationAlarm(
+    metric: MetricWithAlarmSupport,
+    latencyType: LatencyType,
+    props: DurationThreshold,
+    durationName: string,
+    disambiguator?: string,
+    additionalAlarmNameSuffix: string | undefined = undefined,
+  ) {
+    const alarmNameSuffix = [
+      durationName,
+      latencyType,
+      additionalAlarmNameSuffix,
+    ]
+      .filter((i) => i !== undefined)
+      .join("-");
+
+    return this.alarmFactory.addAlarm(metric, {
+      treatMissingData:
+        props.treatMissingDataOverride ?? TreatMissingData.NOT_BREACHING,
+      comparisonOperator:
+        props.comparisonOperatorOverride ??
+        ComparisonOperator.GREATER_THAN_THRESHOLD,
+      ...props,
+      disambiguator,
+      threshold: props.maxDuration.toMilliseconds({ integral: false }),
+      alarmNameSuffix,
+      // we will dedupe any kind of latency issue to the same ticket
+      alarmDedupeStringSuffix: this.alarmFactory
+        .shouldUseDefaultDedupeForLatency
+        ? `Any${durationName}`
+        : alarmNameSuffix,
+      alarmDescription: `${latencyType} ${durationName} is too long.`,
+    });
+  }
+
   addJvmGarbageCollectionDurationAlarm(
     metric: MetricWithAlarmSupport,
     latencyType: LatencyType,

lib/common/monitoring/alarms/LatencyAlarmFactory.ts

@@ -74,6 +74,30 @@ export class LambdaFunctionEnhancedMetricFactory extends BaseMetricFactory<Lambd
     );
   }
 
+  enhancedMetricMaxInitDuration() {
+    return this.enhancedMetric(
+      "init_duration",
+      MetricStatistic.MAX,
+      "InitDuration.Max",
+    );
+  }
+
+  enhancedMetricP90InitDuration() {
+    return this.enhancedMetric(
+      "init_duration",
+      MetricStatistic.P90,
+      "InitDuration.P90",
+    );
+  }
+
+  enhancedMetricAvgInitDuration() {
+    return this.enhancedMetric(
+      "init_duration",
+      MetricStatistic.AVERAGE,
+      "InitDuration.Avg",
+    );
+  }
+
   enhancedMetricFunctionCost() {
     return this.metricFactory.createMetricMath(
       "memory_utilization * duration",

lib/monitoring/aws-lambda/LambdaFunctionEnhancedMetricFactory.ts

@@ -144,6 +144,20 @@ export interface LambdaFunctionMonitoringOptions extends BaseMonitoringProps {
     string,
     UsageThreshold
   >;
+
+  // Enhanced init duration metrics that are time-based
+  readonly addEnhancedMonitoringMaxInitDurationAlarm?: Record<
+    string,
+    DurationThreshold
+  >;
+  readonly addEnhancedMonitoringP90InitDurationAlarm?: Record<
+    string,
+    DurationThreshold
+  >;
+  readonly addEnhancedMonitoringAvgInitDurationAlarm?: Record<
+    string,
+    DurationThreshold
+  >;
 }
 
 export interface LambdaFunctionMonitoringProps
@@ -174,6 +188,7 @@ export class LambdaFunctionMonitoring extends Monitoring {
   readonly memoryUsageAnnotations: HorizontalAnnotation[];
   readonly maxIteratorAgeAnnotations: HorizontalAnnotation[];
   readonly maxOffsetLagAnnotations: HorizontalAnnotation[];
+  readonly initDurationAnnotations: HorizontalAnnotation[];
 
   readonly tpsMetric: MetricWithAlarmSupport;
   readonly p50LatencyMetric: MetricWithAlarmSupport;
@@ -202,6 +217,9 @@ export class LambdaFunctionMonitoring extends Monitoring {
   readonly enhancedMonitoringMaxMemoryUtilizationMetric?: MetricWithAlarmSupport;
   readonly enhancedMonitoringP90MemoryUtilizationMetric?: MetricWithAlarmSupport;
   readonly enhancedMonitoringAvgMemoryUtilizationMetric?: MetricWithAlarmSupport;
+  readonly enhancedMonitoringMaxInitDurationMetric?: MetricWithAlarmSupport;
+  readonly enhancedMonitoringP90InitDurationMetric?: MetricWithAlarmSupport;
+  readonly enhancedMonitoringAvgInitDurationMetric?: MetricWithAlarmSupport;
   readonly enhancedMetricFunctionCostMetric?: MetricWithAlarmSupport;
 
   constructor(scope: MonitoringScope, props: LambdaFunctionMonitoringProps) {
@@ -238,6 +256,7 @@ export class LambdaFunctionMonitoring extends Monitoring {
     this.memoryUsageAnnotations = [];
     this.maxIteratorAgeAnnotations = [];
     this.maxOffsetLagAnnotations = [];
+    this.initDurationAnnotations = [];
 
     this.metricFactory = new LambdaFunctionMetricFactory(
       scope.createMetricFactory(),
@@ -295,6 +314,12 @@ export class LambdaFunctionMonitoring extends Monitoring {
         this.enhancedMetricFactory.enhancedMetricP90MemoryUtilization();
       this.enhancedMonitoringAvgMemoryUtilizationMetric =
         this.enhancedMetricFactory.enhancedMetricAvgMemoryUtilization();
+      this.enhancedMonitoringMaxInitDurationMetric =
+        this.enhancedMetricFactory.enhancedMetricMaxInitDuration();
+      this.enhancedMonitoringP90InitDurationMetric =
+        this.enhancedMetricFactory.enhancedMetricP90InitDuration();
+      this.enhancedMonitoringAvgInitDurationMetric =
+        this.enhancedMetricFactory.enhancedMetricAvgInitDuration();
       this.enhancedMetricFunctionCostMetric =
         this.enhancedMetricFactory.enhancedMetricFunctionCost();
 
@@ -382,6 +407,51 @@ export class LambdaFunctionMonitoring extends Monitoring {
         this.memoryUsageAnnotations.push(createdAlarm.annotation);
         this.addAlarm(createdAlarm);
       }
+      for (const disambiguator in props.addEnhancedMonitoringMaxInitDurationAlarm) {
+        const alarmProps =
+          props.addEnhancedMonitoringMaxInitDurationAlarm[disambiguator];
+        const createdAlarm = this.latencyAlarmFactory.addCustomDurationAlarm(
+          /* eslint-disable @typescript-eslint/no-non-null-assertion */
+          this.enhancedMonitoringMaxInitDurationMetric!,
+          /* eslint-enable @typescript-eslint/no-non-null-assertion */
+          LatencyType.MAX,
+          alarmProps,
+          "InitDuration",
+          disambiguator,
+        );
+        this.initDurationAnnotations.push(createdAlarm.annotation);
+        this.addAlarm(createdAlarm);
+      }
+      for (const disambiguator in props.addEnhancedMonitoringP90InitDurationAlarm) {
+        const alarmProps =
+          props.addEnhancedMonitoringP90InitDurationAlarm[disambiguator];
+        const createdAlarm = this.latencyAlarmFactory.addCustomDurationAlarm(
+          /* eslint-disable @typescript-eslint/no-non-null-assertion */
+          this.enhancedMonitoringP90InitDurationMetric!,
+          /* eslint-enable @typescript-eslint/no-non-null-assertion */
+          LatencyType.P90,
+          alarmProps,
+          "InitDuration",
+          disambiguator,
+        );
+        this.initDurationAnnotations.push(createdAlarm.annotation);
+        this.addAlarm(createdAlarm);
+      }
+      for (const disambiguator in props.addEnhancedMonitoringAvgInitDurationAlarm) {
+        const alarmProps =
+          props.addEnhancedMonitoringAvgInitDurationAlarm[disambiguator];
+        const createdAlarm = this.latencyAlarmFactory.addCustomDurationAlarm(
+          /* eslint-disable @typescript-eslint/no-non-null-assertion */
+          this.enhancedMonitoringAvgInitDurationMetric!,
+          /* eslint-enable @typescript-eslint/no-non-null-assertion */
+          LatencyType.AVERAGE,
+          alarmProps,
+          "InitDuration",
+          disambiguator,
+        );
+        this.initDurationAnnotations.push(createdAlarm.annotation);
+        this.addAlarm(createdAlarm);
+      }
     }
     for (const disambiguator in props.addLatencyP50Alarm) {
       const alarmProps = props.addLatencyP50Alarm[disambiguator];
@@ -653,15 +723,19 @@ export class LambdaFunctionMonitoring extends Monitoring {
       widgets.push(
         new Row(
           this.createLambdaInsightsCpuWidget(
-            ThirdWidth,
+            QuarterWidth,
             DefaultGraphWidgetHeight,
           ),
           this.createLambdaInsightsMemoryWidget(
-            ThirdWidth,
+            QuarterWidth,
+            DefaultGraphWidgetHeight,
+          ),
+          this.createLambdaInsightsInitDurationWidget(
+            QuarterWidth,
             DefaultGraphWidgetHeight,
           ),
           this.createLambdaInsightsFunctionCostWidget(
-            ThirdWidth,
+            QuarterWidth,
             DefaultGraphWidgetHeight,
           ),
         ),
@@ -813,6 +887,23 @@ export class LambdaFunctionMonitoring extends Monitoring {
     });
   }
 
+  createLambdaInsightsInitDurationWidget(width: number, height: number) {
+    return new GraphWidget({
+      width,
+      height,
+      title: "Init Duration",
+      left: [
+        /* eslint-disable @typescript-eslint/no-non-null-assertion */
+        this.enhancedMonitoringMaxInitDurationMetric!,
+        this.enhancedMonitoringP90InitDurationMetric!,
+        this.enhancedMonitoringAvgInitDurationMetric!,
+        /* eslint-enable @typescript-eslint/no-non-null-assertion */
+      ],
+      leftYAxis: TimeAxisMillisFromZero,
+      leftAnnotations: this.initDurationAnnotations,
+    });
+  }
+
   createLambdaInsightsFunctionCostWidget(width: number, height: number) {
     return new GraphWidget({
       width,

lib/monitoring/aws-lambda/LambdaFunctionMonitoring.ts

@@ -357,6 +357,21 @@ test("snapshot test: all alarms, alarmPrefix on error dedupeString", () => {
         maxUsagePercent: 50,
       },
     },
+    addEnhancedMonitoringMaxInitDurationAlarm: {
+      Warning: {
+        maxDuration: Duration.millis(200),
+      },
+    },
+    addEnhancedMonitoringP90InitDurationAlarm: {
+      Warning: {
+        maxDuration: Duration.millis(150),
+      },
+    },
+    addEnhancedMonitoringAvgInitDurationAlarm: {
+      Warning: {
+        maxDuration: Duration.millis(100),
+      },
+    },
     useCreatedAlarms: {
       consume(alarms: AlarmWithAnnotation[]) {
         numAlarmsCreated = alarms.length;
@@ -365,7 +380,7 @@ test("snapshot test: all alarms, alarmPrefix on error dedupeString", () => {
   });
 
   addMonitoringDashboardsToStack(stack, monitoring);
-  expect(numAlarmsCreated).toStrictEqual(20);
+  expect(numAlarmsCreated).toStrictEqual(23);
   expect(Template.fromStack(stack)).toMatchSnapshot();
 });
 
@@ -500,6 +515,21 @@ test("snapshot test: all alarms, alarmPrefix on latency dedupeString", () => {
         maxUsagePercent: 50,
       },
     },
+    addEnhancedMonitoringMaxInitDurationAlarm: {
+      Warning: {
+        maxDuration: Duration.millis(200),
+      },
+    },
+    addEnhancedMonitoringP90InitDurationAlarm: {
+      Warning: {
+        maxDuration: Duration.millis(150),
+      },
+    },
+    addEnhancedMonitoringAvgInitDurationAlarm: {
+      Warning: {
+        maxDuration: Duration.millis(100),
+      },
+    },
     useCreatedAlarms: {
       consume(alarms: AlarmWithAnnotation[]) {
         numAlarmsCreated = alarms.length;
@@ -508,7 +538,7 @@ test("snapshot test: all alarms, alarmPrefix on latency dedupeString", () => {
   });
 
   addMonitoringDashboardsToStack(stack, monitoring);
-  expect(numAlarmsCreated).toStrictEqual(20);
+  expect(numAlarmsCreated).toStrictEqual(23);
   expect(Template.fromStack(stack)).toMatchSnapshot();
 });
 
@@ -620,6 +650,21 @@ test("doesn't create alarms for enhanced Lambda Insights metrics if not enabled"
         maxUsagePercent: 50,
       },
     },
+    addEnhancedMonitoringMaxInitDurationAlarm: {
+      Warning: {
+        maxDuration: Duration.millis(200),
+      },
+    },
+    addEnhancedMonitoringP90InitDurationAlarm: {
+      Warning: {
+        maxDuration: Duration.millis(150),
+      },
+    },
+    addEnhancedMonitoringAvgInitDurationAlarm: {
+      Warning: {
+        maxDuration: Duration.millis(100),
+      },
+    },
     useCreatedAlarms: {
       consume(alarms: AlarmWithAnnotation[]) {
         numAlarmsCreated = alarms.length;