fix(dashboards)!: handle dynamic dashboards in SingleWidgetDashboardSegment (#373)

This change fixes a couple things with the dynamic dashboard functionality that was introduced in d118a6e

1. `SingleWidgetDashboardSegment` was accepting ctor params to control dashboard visibility which conflicted with the overrideProps uses elsewhere to control the same. This change removes those params in favor of having consumers control this using overrideProps.
2. Fixes some issues in the `StaticSegmentDynamicAdapter` logic which were impacting backwards compatibility.
3. Introduces a new test to provide better coverage for the above two issues.

---

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

Author: djdawson3

.projen/tasks.json

@@ -11,7 +11,7 @@ const project = new awscdk.AwsCdkConstructLibrary({
   keywords: ["cloudwatch", "monitoring"],
 
   defaultReleaseBranch: "main",
-  majorVersion: 4,
+  majorVersion: 5,
   stability: "experimental",
 
   cdkVersion: CDK_VERSION,

.projenrc.js

@@ -17,26 +17,26 @@ export class StaticSegmentDynamicAdapter implements IDynamicDashboardSegment {
     this.props = props;
   }
 
+  /**
+   * Adapts an IDashboardSegment to the IDynamicDashboardSegment interface by using
+   * overrideProps to determine if a segment should be shown on a specific dashboard.
+   * The default values are true, so consumers must set these to false if they would
+   * like to hide these items from dashboards
+   */
   widgetsForDashboard(name: string): IWidget[] {
-    if (
-      this.props.overrideProps?.addToDetailDashboard ||
-      name === DefaultDashboards.DETAIL
-    ) {
+    const overrideProps = this.props.overrideProps;
+    const addToDetailDashboard = overrideProps?.addToDetailDashboard ?? true;
+    const addToSummaryDashboard = overrideProps?.addToSummaryDashboard ?? true;
+    const addToAlarmsDashboard = overrideProps?.addToAlarmDashboard ?? true;
+    if (addToDetailDashboard && name === DefaultDashboards.DETAIL) {
       return this.props.segment.widgets();
     }
-    if (
-      this.props.overrideProps?.addToSummaryDashboard ||
-      name === DefaultDashboards.SUMMARY
-    ) {
+    if (addToSummaryDashboard && name === DefaultDashboards.SUMMARY) {
       return this.props.segment.summaryWidgets();
     }
-    if (
-      this.props.overrideProps?.addToAlarmDashboard ||
-      name === DefaultDashboards.ALARMS
-    ) {
+    if (addToAlarmsDashboard && name === DefaultDashboards.ALARMS) {
       return this.props.segment.alarmWidgets();
     }
-
     return [];
   }
 }

API.md

@@ -1,33 +1,57 @@
 import { IWidget } from "aws-cdk-lib/aws-cloudwatch";
-
 import { IDashboardSegment } from "./DashboardSegment";
+import { DefaultDashboards } from "./DefaultDashboardFactory";
+import { IDynamicDashboardSegment } from "./DynamicDashboardSegment";
 
-export class SingleWidgetDashboardSegment implements IDashboardSegment {
+export class SingleWidgetDashboardSegment
+  implements IDashboardSegment, IDynamicDashboardSegment
+{
   protected readonly widget: IWidget;
-  protected readonly addToSummary: boolean;
-  protected readonly addToAlarm: boolean;
+  protected readonly dashboardsToInclude: string[];
 
-  constructor(widget: IWidget, addToSummary?: boolean, addToAlarm?: boolean) {
+  /**
+   * Create a dashboard segment representing a single widget.
+   * @param widget widget to add
+   * @param dashboardsToInclude list of dashboard names which to show this widget on. Defaults to the default dashboards.
+   */
+  constructor(widget: IWidget, dashboardsToInclude?: string[]) {
     this.widget = widget;
-    this.addToSummary = addToSummary ?? true;
-    this.addToAlarm = addToAlarm ?? true;
+    this.dashboardsToInclude = dashboardsToInclude ?? [
+      DefaultDashboards.ALARMS,
+      DefaultDashboards.DETAIL,
+      DefaultDashboards.SUMMARY,
+    ];
+  }
+
+  widgetsForDashboard(name: string): IWidget[] {
+    if (this.dashboardsToInclude.includes(name)) {
+      return [this.widget];
+    } else {
+      return [];
+    }
   }
 
   alarmWidgets(): IWidget[] {
-    if (this.addToAlarm) {
+    if (this.dashboardsToInclude.includes(DefaultDashboards.ALARMS)) {
       return [this.widget];
+    } else {
+      return [];
     }
-    return [];
   }
 
   summaryWidgets(): IWidget[] {
-    if (this.addToSummary) {
+    if (this.dashboardsToInclude.includes(DefaultDashboards.SUMMARY)) {
       return [this.widget];
+    } else {
+      return [];
     }
-    return [];
   }
 
   widgets(): IWidget[] {
-    return [this.widget];
+    if (this.dashboardsToInclude.includes(DefaultDashboards.DETAIL)) {
+      return [this.widget];
+    } else {
+      return [];
+    }
   }
 }

lib/dashboard/DynamicDashboardSegment.ts

@@ -371,9 +371,11 @@ export class MonitoringFacade extends MonitoringScope {
   }
 
   addWidget(widget: IWidget, addToSummary?: boolean, addToAlarm?: boolean) {
-    this.addSegment(
-      new SingleWidgetDashboardSegment(widget, addToSummary, addToAlarm)
-    );
+    this.addSegment(new SingleWidgetDashboardSegment(widget), {
+      addToAlarmDashboard: addToAlarm ?? true,
+      addToSummaryDashboard: addToSummary ?? true,
+      addToDetailDashboard: true,
+    });
     return this;
   }
 

lib/dashboard/SingleWidgetDashboardSegment.ts

@@ -1,6 +1,12 @@
 import { Stack } from "aws-cdk-lib";
-import { Template } from "aws-cdk-lib/assertions";
-import { DynamicDashboardFactory, MonitoringFacade } from "../../lib";
+import { Capture, Template } from "aws-cdk-lib/assertions";
+import { TextWidget } from "aws-cdk-lib/aws-cloudwatch";
+import {
+  DefaultDashboardFactory,
+  DynamicDashboardFactory,
+  MonitoringFacade,
+  SingleWidgetDashboardSegment,
+} from "../../lib";
 
 describe("test of defaults", () => {
   test("only default dashboard gets created by default", () => {
@@ -57,4 +63,48 @@ describe("test of defaults", () => {
       DashboardName: "testPrefix-Dynamic2",
     });
   });
+
+  test("SingleWidgetDashboardSegment is not displayed if addSegment overrides set to false", () => {
+    // configure monitoring facade with dashboard factory which populates all three default dashboards
+    const stack = new Stack();
+    const dashboardFactory = new DefaultDashboardFactory(
+      stack,
+      "TestDashboardFactory",
+      {
+        dashboardNamePrefix: "testPrefix",
+        createDashboard: true,
+        createAlarmDashboard: true,
+        createSummaryDashboard: true,
+      }
+    );
+    const facade = new MonitoringFacade(stack, "Test", {
+      dashboardFactory: dashboardFactory,
+    });
+
+    // add SingleWidgetDashboardSegment with default ctor args but use overrides to
+    // direct exclusion from default dashboards
+    facade.addSegment(
+      new SingleWidgetDashboardSegment(
+        new TextWidget({ markdown: "Simple Dashboard Segment" })
+      ),
+      {
+        addToAlarmDashboard: false,
+        addToDetailDashboard: false,
+        addToSummaryDashboard: false,
+      }
+    );
+
+    // verify that the generated dashboards do not include the SingleWidgetDashboardSegment
+    // due to override exclusion directives
+    const result = Template.fromStack(stack);
+    const dashboardCapture = new Capture();
+    result.hasResourceProperties("AWS::CloudWatch::Dashboard", {
+      DashboardBody: dashboardCapture,
+    });
+
+    do {
+      const dashboardBody = JSON.parse(dashboardCapture.asString());
+      expect(dashboardBody.widgets).toHaveLength(0);
+    } while (dashboardCapture.next());
+  });
 });