feat(dashboards)!: improve customizability (#355)

This reverts commit acd69cb, i.e. it
reintroduces #349 by @djdawson3. However, this also has a major version
bump to v4.

BREAKING CHANGE: this introduces a new way of building dashboards which
is mostly backwards compatible,
but does expect that a new IDynamicDashboardFactory interface is
implemented for a MonitoringFacade's
dashboardFactory.

---

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

Co-authored-by: djdawson3 <[email protected]>

Author: Eugene Cheung

.projen/tasks.json

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

.projenrc.js

@@ -26,7 +26,7 @@ In your `package.json`:
 ```json
 {
   "dependencies": {
-    "cdk-monitoring-constructs": "^3.0.0",
+    "cdk-monitoring-constructs": "^4.0.0",
 
     // peer dependencies of cdk-monitoring-constructs
     "@aws-cdk/aws-apigatewayv2-alpha": "^2.65.0-alpha.0",
@@ -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.

API.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 [];
+    }
+  }
 }

README.md

@@ -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!");
+    }
+  }
 }