feat(dashboards): improve customizability (#349)

# Change Info
This change allows for improved customization of dashboards. It will allow consumers of this package to control how many dashboards they generate, the configuration of those dashboards, and the widgets on those dashboards. This probably helps address this related github issue: #66. 

This change is backwards compatible and consumers must make explicit changes to their code if they would like to take advantage of the additional dynamism around dashboard generation this contribution provides. As a consequence of this, the dashboard configuration provided by this contribution is not as robust or as flexible as I would like it to be, but this comes at the trade-off of being minimally intrusive to the existing codebase. 

# Testing Done
I've used my own CDK application to test this and have verified that these new changes allow me to create a custom number of dashboards according to my own configuration. 

# Backwards Compatibility
This change was made backwards compatible by retrofitting the existing `DefaultDashboardFactory` to also be an implementation of `IDynamicDashboardFactory` with an opinionated implementation which creates three dashboards: Summary, Details, and Alarms. 

## Backwards Compatibility Testing Done
I also tested this for backwards compatibility by: 

1. Using my own CDK application by using the existing constructs exposed by the `MonitoringFacade` and verified that `monitoring.addSegment` and `monitoring.monitorXYZ` calls populated the default dashboards as expected
2. Verifying that the jest snapshots for the `DefaultDashboardFactory` did not change. 

# How to consume / Documentation
I've added a README section on how to consume these changes. 

# Limitations of this approach
1. This does not really support minor-changes to existing dashboard content. If you want to use this, it amounts to a full swap & replace. Re-arrangement of existing widgets to new dashboards can easily be done, but small modifications to existing widgets are not cheap with this change. 
3. This change introduces some coupling between dashboard types and IDynamicDashboardSegments: when creating IDynamicDashboardSegment implementations, you are required to know which dashboards you are generating. 

However, since this contribution is minimally intrusive, I thought the above were decent trade-offs to form the basis of PR discussions. 

# Forward Thinking / Additional Augmentations
Organizations can use this to configure their own defaults for service teams in their organization and setup best practices which can easily be consumed by service teams when creating their dashboards. Further, such organizations can even introduce additional dashboard types (e.g. for higher level operational or business review) which can exist separately from service/engineering dashboards which are intended to have higher detail and be consumed by more technical audiences.

---

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

Author: djdawson3

API.md

@@ -265,6 +265,79 @@ This is a general procedure on how to do it:
 
 Both of these monitoring base classes are dashboard segments, so you can add them to your monitoring by calling `.addSegment()` on the `MonitoringFacade`.
 
+### Custom dashboards
+
+If you want *even* more flexibility, you can take complete control over dashboard generation by leveraging dynamic dashboarding features. This allows you to create an arbitrary number of dashboards while configuring each of them separately. You can do this in three simple steps:
+
+1. Create a dynamic dashboard factory
+2. Create `IDynamicDashboardSegment` implementations
+3. Add Dynamic Segments to your `MonitoringFacade`
+
+#### Create a dynamic dashboard factory
+
+The below code sample will generate two dashboards with the following names:
+* ExampleDashboards-HostedService
+* ExampleDashboards-Infrastructure
+
+
+```ts
+// create the dynamic dashboard factory.
+const factory = new DynamicDashboardFactory(stack, "DynamicDashboards", {
+  dashboardNamePrefix: "ExampleDashboards",
+  dashboardConfigs: [
+    // 'name' is the minimum required configuration
+    { name: "HostedService" },
+    // below is an example of additional dashboard-specific config options
+    { 
+      name: "Infrastructure",
+      range: Duration.hours(3),
+      periodOverride: PeriodOverride.AUTO,
+      renderingPreference: DashboardRenderingPreference.BITMAP_ONLY
+    },
+  ],
+});
+```
+
+#### Create `IDynamicDashboardSegment` implementations
+For each construct you want monitored, you will need to create an implementation of an `IDynamicDashboardSegment`. The following is a basic reference implementation as an example:
+
+```ts
+export enum DashboardTypes {
+  HostedService = "HostedService",
+  Infrastructure = "Infrastructure",
+}
+
+class ExampleSegment implements IDynamicDashboardSegment {
+  widgetsForDashboard(name: string): IWidget[] {
+    // this logic is what's responsible for allowing your dynamic segment to return
+    // different widgets for different dashboards
+    switch (name) {
+      case DashboardTypes.HostedService:
+        return [new TextWidget({ markdown: "This shows metrics for your service hosted on AWS Infrastructure" })];
+      case DashboardTypes.Infrastructure:
+        return [new TextWidget({ markdown: "This shows metrics for the AWS Infrastructure supporting your hosted service" })];
+      default:
+        throw new Error("Unexpected dashboard name!");
+    }
+  }
+}
+```
+
+#### Add Dynamic Segments to MonitoringFacade
+
+When you have instances of an `IDynamicDashboardSegment` to use, they can be added to your dashboard like this:
+
+```ts
+monitoring.addDynamicSegment(new ExampleSegment());
+```
+
+Now, this widget will be added to both dashboards and will show different content depending on the dashboard. Using the above example code, two dashboards will be generated with the following content:
+
+* Dashboard Name: "ExampleDashboards-HostedService"
+  * Content: "This shows metrics for your service hosted on AWS Infrastructure"
+* Dashboard Name: "ExampleDashboards-Infrastructure"
+  * Content: "This shows metrics for the AWS Infrastructure supporting your hosted service"
+
 ### Monitoring scopes
 
 You can monitor complete CDK construct scopes using an aspect. It will automatically discover all monitorable resources within the scope recursively and add them to your dashboard.

README.md

@@ -2,7 +2,9 @@ import { IWidget } from "aws-cdk-lib/aws-cloudwatch";
 
 import { MonitoringScope } from "./MonitoringScope";
 import {
+  DefaultDashboards,
   IDashboardSegment,
+  IDynamicDashboardSegment,
   MonitoringDashboardsOverrideProps,
   UserProvidedNames,
 } from "../../dashboard";
@@ -28,7 +30,9 @@ export interface BaseMonitoringProps
 /**
  * An independent unit of monitoring. This is the base for all monitoring classes with alarm support.
  */
-export abstract class Monitoring implements IDashboardSegment {
+export abstract class Monitoring
+  implements IDashboardSegment, IDynamicDashboardSegment
+{
   protected readonly scope: MonitoringScope;
   protected readonly alarms: AlarmWithAnnotation[];
   protected readonly localAlarmNamePrefixOverride?: string;
@@ -101,4 +105,17 @@ export abstract class Monitoring implements IDashboardSegment {
    * Returns widgets to be placed on the main dashboard.
    */
   abstract widgets(): IWidget[];
+
+  widgetsForDashboard(name: string): IWidget[] {
+    switch (name) {
+      case DefaultDashboards.SUMMARY:
+        return this.summaryWidgets();
+      case DefaultDashboards.DETAIL:
+        return this.widgets();
+      case DefaultDashboards.ALARMS:
+        return this.alarmWidgets();
+      default:
+        return [];
+    }
+  }
 }

lib/common/monitoring/Monitoring.ts

@@ -5,11 +5,12 @@ import {
   PeriodOverride,
 } from "aws-cdk-lib/aws-cloudwatch";
 import { Construct } from "constructs";
-
 import { BitmapDashboard } from "./BitmapDashboard";
 import { DashboardRenderingPreference } from "./DashboardRenderingPreference";
 import { DashboardWithBitmapCopy } from "./DashboardWithBitmapCopy";
+import { IDynamicDashboardSegment } from "./DynamicDashboardSegment";
 import { IDashboardFactory, IDashboardFactoryProps } from "./IDashboardFactory";
+import { IDynamicDashboardFactory } from "./IDynamicDashboardFactory";
 
 export interface MonitoringDashboardsProps {
   /**
@@ -67,15 +68,25 @@ export interface MonitoringDashboardsProps {
   readonly renderingPreference?: DashboardRenderingPreference;
 }
 
+export enum DefaultDashboards {
+  SUMMARY = "Summary",
+  DETAIL = "Detail",
+  ALARMS = "Alarms",
+}
+
 export class DefaultDashboardFactory
   extends Construct
-  implements IDashboardFactory
+  implements IDashboardFactory, IDynamicDashboardFactory
 {
+  // Legacy Dashboard Fields
   readonly dashboard?: Dashboard;
   readonly summaryDashboard?: Dashboard;
   readonly alarmDashboard?: Dashboard;
   readonly anyDashboardCreated: boolean;
 
+  // Dynamic Dashboard Fields
+  readonly dashboards: Record<string, Dashboard> = {};
+
   constructor(scope: Construct, id: string, props: MonitoringDashboardsProps) {
     super(scope, id);
 
@@ -108,6 +119,7 @@ export class DefaultDashboardFactory
         periodOverride:
           props.detailDashboardPeriodOverride ?? PeriodOverride.INHERIT,
       });
+      this.dashboards[DefaultDashboards.DETAIL] = this.dashboard;
     }
     if (createSummaryDashboard) {
       anyDashboardCreated = true;
@@ -121,6 +133,7 @@ export class DefaultDashboardFactory
             props.summaryDashboardPeriodOverride ?? PeriodOverride.INHERIT,
         }
       );
+      this.dashboards[DefaultDashboards.SUMMARY] = this.summaryDashboard;
     }
     if (createAlarmDashboard) {
       anyDashboardCreated = true;
@@ -134,26 +147,12 @@ export class DefaultDashboardFactory
             props.detailDashboardPeriodOverride ?? PeriodOverride.INHERIT,
         }
       );
+      this.dashboards[DefaultDashboards.ALARMS] = this.alarmDashboard;
     }
 
     this.anyDashboardCreated = anyDashboardCreated;
   }
 
-  protected createDashboard(
-    renderingPreference: DashboardRenderingPreference,
-    id: string,
-    props: DashboardProps
-  ) {
-    switch (renderingPreference) {
-      case DashboardRenderingPreference.INTERACTIVE_ONLY:
-        return new Dashboard(this, id, props);
-      case DashboardRenderingPreference.BITMAP_ONLY:
-        return new BitmapDashboard(this, id, props);
-      case DashboardRenderingPreference.INTERACTIVE_AND_BITMAP:
-        return new DashboardWithBitmapCopy(this, id, props);
-    }
-  }
-
   addSegment(props: IDashboardFactoryProps) {
     if ((props.overrideProps?.addToDetailDashboard ?? true) && this.dashboard) {
       this.dashboard.addWidgets(...props.segment.widgets());
@@ -172,6 +171,33 @@ export class DefaultDashboardFactory
     }
   }
 
+  addDynamicSegment(segment: IDynamicDashboardSegment): void {
+    this.dashboard?.addWidgets(
+      ...segment.widgetsForDashboard(DefaultDashboards.DETAIL)
+    );
+    this.summaryDashboard?.addWidgets(
+      ...segment.widgetsForDashboard(DefaultDashboards.SUMMARY)
+    );
+    this.alarmDashboard?.addWidgets(
+      ...segment.widgetsForDashboard(DefaultDashboards.ALARMS)
+    );
+  }
+
+  protected createDashboard(
+    renderingPreference: DashboardRenderingPreference,
+    id: string,
+    props: DashboardProps
+  ) {
+    switch (renderingPreference) {
+      case DashboardRenderingPreference.INTERACTIVE_ONLY:
+        return new Dashboard(this, id, props);
+      case DashboardRenderingPreference.BITMAP_ONLY:
+        return new BitmapDashboard(this, id, props);
+      case DashboardRenderingPreference.INTERACTIVE_AND_BITMAP:
+        return new DashboardWithBitmapCopy(this, id, props);
+    }
+  }
+
   createdDashboard(): Dashboard | undefined {
     return this.dashboard;
   }
@@ -183,4 +209,17 @@ export class DefaultDashboardFactory
   createdAlarmDashboard(): Dashboard | undefined {
     return this.alarmDashboard;
   }
+
+  getDashboard(name: string): Dashboard | undefined {
+    switch (name) {
+      case DefaultDashboards.SUMMARY:
+        return this.summaryDashboard;
+      case DefaultDashboards.DETAIL:
+        return this.dashboard;
+      case DefaultDashboards.ALARMS:
+        return this.alarmDashboard;
+      default:
+        throw new Error("Unexpected dashboard name!");
+    }
+  }
 }

lib/dashboard/DefaultDashboardFactory.ts

@@ -0,0 +1,133 @@
+import { Duration } from "aws-cdk-lib";
+import {
+  Dashboard,
+  DashboardProps,
+  PeriodOverride,
+} from "aws-cdk-lib/aws-cloudwatch";
+import { Construct } from "constructs";
+
+import { BitmapDashboard } from "./BitmapDashboard";
+import { DashboardRenderingPreference } from "./DashboardRenderingPreference";
+import { DashboardWithBitmapCopy } from "./DashboardWithBitmapCopy";
+import { DefaultDashboards } from "./DefaultDashboardFactory";
+import { IDynamicDashboardSegment } from "./DynamicDashboardSegment";
+import { IDynamicDashboardFactory } from "./IDynamicDashboardFactory";
+
+export interface DynamicDashboardConfiguration {
+  /**
+   * Name of the dashboard. Full dashboard name will take the form of:
+   * `{@link MonitoringDynamicDashboardsProps.dashboardNamePrefix}-{@link name}`
+   *
+   * NOTE: The dashboard names in {@link DefaultDashboardFactory.DefaultDashboards}
+   * are reserved and cannot be used as dashboard names.
+   */
+  readonly name: string;
+
+  /**
+   * Dashboard rendering preference.
+   *
+   * @default - DashboardRenderingPreference.INTERACTIVE_ONLY
+   */
+  readonly renderingPreference?: DashboardRenderingPreference;
+
+  /**
+   * Range of the dashboard
+   * @default - 8 hours
+   */
+  readonly range?: Duration;
+
+  /**
+   * Period override for the dashboard.
+   * @default - respect individual graphs (PeriodOverride.INHERIT)
+   */
+  readonly periodOverride?: PeriodOverride;
+}
+
+export interface MonitoringDynamicDashboardsProps {
+  /**
+   * Prefix added to each dashboard's name.
+   * This allows to have all dashboards sorted close to each other and also separate multiple monitoring facades.
+   */
+  readonly dashboardNamePrefix: string;
+
+  /**
+   * List of dashboard types to generate.
+   */
+  readonly dashboardConfigs: DynamicDashboardConfiguration[];
+}
+
+export class DynamicDashboardFactory
+  extends Construct
+  implements IDynamicDashboardFactory
+{
+  readonly dashboards: Record<string, Dashboard> = {};
+
+  constructor(
+    scope: Construct,
+    id: string,
+    props: MonitoringDynamicDashboardsProps
+  ) {
+    super(scope, id);
+
+    props.dashboardConfigs.forEach((dashboardConfig) => {
+      if (this.dashboards[dashboardConfig.name]) {
+        throw new Error(
+          `Duplicate dashboard name found: ${dashboardConfig.name}`
+        );
+      }
+
+      if (
+        Object.values<string>(DefaultDashboards).includes(dashboardConfig.name)
+      ) {
+        throw new Error(
+          `${dashboardConfig.name} is a reserved name and cannot be used`
+        );
+      }
+
+      const renderingPreference =
+        dashboardConfig.renderingPreference ??
+        DashboardRenderingPreference.INTERACTIVE_ONLY;
+      const start: string =
+        "-" + (dashboardConfig.range ?? Duration.hours(8).toIsoString());
+
+      const dashboard = this.createDashboard(
+        renderingPreference,
+        dashboardConfig.name,
+        {
+          dashboardName: `${props.dashboardNamePrefix}-${dashboardConfig.name}`,
+          start,
+          periodOverride:
+            dashboardConfig.periodOverride ?? PeriodOverride.INHERIT,
+        }
+      );
+
+      this.dashboards[dashboardConfig.name] = dashboard;
+    });
+  }
+
+  protected createDashboard(
+    renderingPreference: DashboardRenderingPreference,
+    id: string,
+    props: DashboardProps
+  ) {
+    switch (renderingPreference) {
+      case DashboardRenderingPreference.INTERACTIVE_ONLY:
+        return new Dashboard(this, id, props);
+      case DashboardRenderingPreference.BITMAP_ONLY:
+        return new BitmapDashboard(this, id, props);
+      case DashboardRenderingPreference.INTERACTIVE_AND_BITMAP:
+        return new DashboardWithBitmapCopy(this, id, props);
+    }
+  }
+
+  addDynamicSegment(segment: IDynamicDashboardSegment): void {
+    for (const type in this.dashboards) {
+      const dashboard = this.dashboards[type];
+      dashboard.addWidgets(...segment.widgetsForDashboard(type));
+    }
+  }
+
+  getDashboard(type: string): Dashboard | undefined {
+    return this.dashboards[type];
+  }
+}