feat(cloudwatch): Add CustomWidget (#19327)

This PR introcudes the CustomWidget for Cloudwatch Dashboards

fixes: #17579

based on the work of @dannyber

If you wonder, why only a string typed option was used instead of an lambda.IFunction, the reason is, that this would introduce a circular dependency between lambda -> cloudwatch -> lambda and leads to build errors.

Creating a new package for this tiny feature to work around the circular dependency would be too much of a good thing. Apart from that it could be unintuitive to find the custom widget in a package 'aws-cloudwatch-pattarns' if all other widgets come from 'aws-cloudwatch'.

*By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license*

Author: markussiebert

packages/@aws-cdk/aws-cloudwatch/README.md

@@ -501,6 +501,28 @@ dashboard.addWidgets(new cloudwatch.LogQueryWidget({
 }));
 ```
 
+### Custom widget
+
+A `CustomWidget` shows the result of an AWS Lambda function:
+
+```ts
+declare const dashboard: cloudwatch.Dashboard;
+
+// Import or create a lambda function
+const fn = lambda.Function.fromFunctionArn(
+  dashboard,
+  'Function',
+  'arn:aws:lambda:us-east-1:123456789012:function:MyFn',
+);
+
+dashboard.addWidgets(new cloudwatch.CustomWidget({
+  functionArn: fn.functionArn,
+  title: 'My lambda baked widget',
+}));
+```
+
+You can learn more about custom widgets in the [Amazon Cloudwatch User Guide](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/add_custom_widget_dashboard.html).
+
 ### Dashboard Layout
 
 The widgets on a dashboard are visually laid out in a grid that is 24 columns

packages/@aws-cdk/aws-cloudwatch/lib/graph.ts

@@ -368,6 +368,97 @@ export class SingleValueWidget extends ConcreteWidget {
   }
 }
 
+/**
+ * The properties for a CustomWidget
+ */
+export interface CustomWidgetProps {
+  /**
+   * The Arn of the AWS Lambda function that returns HTML or JSON that will be displayed in the widget
+   */
+  readonly functionArn: string;
+
+  /**
+   * Width of the widget, in a grid of 24 units wide
+   *
+   * @default 6
+   */
+  readonly width?: number;
+
+  /**
+   * Height of the widget
+   *
+   * @default - 6 for Alarm and Graph widgets.
+   *   3 for single value widgets where most recent value of a metric is displayed.
+   */
+  readonly height?: number;
+
+  /**
+   * The title of the widget
+   */
+  readonly title: string;
+
+  /**
+   * Update the widget on refresh
+   *
+   * @default true
+   */
+  readonly updateOnRefresh?: boolean;
+
+  /**
+   * Update the widget on resize
+   *
+   * @default true
+   */
+  readonly updateOnResize?: boolean;
+
+  /**
+   * Update the widget on time range change
+   *
+   * @default true
+   */
+  readonly updateOnTimeRangeChange?: boolean;
+
+  /**
+   * Parameters passed to the lambda function
+   *
+   * @default - no parameters are passed to the lambda function
+   */
+  readonly params?: any;
+}
+
+/**
+ * A CustomWidget shows the result of a AWS lambda function
+ */
+export class CustomWidget extends ConcreteWidget {
+
+  private readonly props: CustomWidgetProps;
+
+  public constructor(props: CustomWidgetProps) {
+    super(props.width ?? 6, props.height ?? 6);
+    this.props = props;
+  }
+
+  public toJson(): any[] {
+    return [{
+      type: 'custom',
+      width: this.width,
+      height: this.height,
+      x: this.x,
+      y: this.y,
+      properties: {
+        endpoint: this.props.functionArn,
+        params: this.props.params,
+        title: this.props.title,
+        updateOn: {
+          refresh: this.props.updateOnRefresh ?? true,
+          resize: this.props.updateOnResize ?? true,
+          timeRange: this.props.updateOnTimeRangeChange ?? true,
+        },
+      },
+    }];
+  }
+}
+
 /**
  * Horizontal annotation to be added to a graph
  */

packages/@aws-cdk/aws-cloudwatch/test/alarm-and-dashboard.integ.snapshot/aws-cdk-cloudwatch-alarms.template.json

@@ -116,7 +116,7 @@
          "QueueName"
         ]
        },
-       "\"]],\"singleValueFullPrecision\":true}}]}"
+       "\"]],\"singleValueFullPrecision\":true}},{\"type\":\"custom\",\"width\":6,\"height\":6,\"x\":0,\"y\":56,\"properties\":{\"endpoint\":\"arn:aws:lambda:us-west-2:123456789012:function:my-function\",\"title\":\"My custom alarm\",\"updateOn\":{\"refresh\":true,\"resize\":true,\"timeRange\":true}}}]}"
       ]
      ]
     },

packages/@aws-cdk/aws-cloudwatch/test/alarm-and-dashboard.integ.snapshot/tree.json

@@ -162,7 +162,7 @@
                               "QueueName"
                             ]
                           },
-                          "\"]],\"singleValueFullPrecision\":true}}]}"
+                          "\"]],\"singleValueFullPrecision\":true}},{\"type\":\"custom\",\"width\":6,\"height\":6,\"x\":0,\"y\":56,\"properties\":{\"endpoint\":\"arn:aws:lambda:us-west-2:123456789012:function:my-function\",\"title\":\"My custom alarm\",\"updateOn\":{\"refresh\":true,\"resize\":true,\"timeRange\":true}}}]}"
                         ]
                       ]
                     },

packages/@aws-cdk/aws-cloudwatch/test/graphs.test.ts

@@ -1,5 +1,5 @@
 import { Duration, Stack } from '@aws-cdk/core';
-import { Alarm, AlarmWidget, Color, GraphWidget, GraphWidgetView, LegendPosition, LogQueryWidget, Metric, Shading, SingleValueWidget, LogQueryVisualizationType } from '../lib';
+import { Alarm, AlarmWidget, Color, GraphWidget, GraphWidgetView, LegendPosition, LogQueryWidget, Metric, Shading, SingleValueWidget, LogQueryVisualizationType, CustomWidget } from '../lib';
 
 describe('Graphs', () => {
   test('add stacked property to graphs', () => {
@@ -348,6 +348,71 @@ describe('Graphs', () => {
 
   });
 
+  test('custom widget basic', () => {
+    // GIVEN
+    const stack = new Stack();
+
+    // WHEN
+    const widget = new CustomWidget({
+      functionArn: 'arn:aws:lambda:us-east-1:123456789:function:customwidgetfunction',
+      title: 'CustomWidget',
+    });
+
+    // THEN
+    expect(stack.resolve(widget.toJson())).toEqual([{
+      type: 'custom',
+      width: 6,
+      height: 6,
+      properties: {
+        title: 'CustomWidget',
+        endpoint: 'arn:aws:lambda:us-east-1:123456789:function:customwidgetfunction',
+        updateOn: {
+          refresh: true,
+          resize: true,
+          timeRange: true,
+        },
+      },
+    }]);
+  });
+
+  test('custom widget full config', () => {
+    // GIVEN
+    const stack = new Stack();
+
+    // WHEN
+    const widget = new CustomWidget({
+      functionArn: 'arn:aws:lambda:us-east-1:123456789:function:customwidgetfunction',
+      title: 'CustomWidget',
+      height: 1,
+      width: 1,
+      params: {
+        any: 'param',
+      },
+      updateOnRefresh: false,
+      updateOnResize: false,
+      updateOnTimeRangeChange: false,
+    });
+
+    // THEN
+    expect(stack.resolve(widget.toJson())).toEqual([{
+      type: 'custom',
+      width: 1,
+      height: 1,
+      properties: {
+        title: 'CustomWidget',
+        endpoint: 'arn:aws:lambda:us-east-1:123456789:function:customwidgetfunction',
+        params: {
+          any: 'param',
+        },
+        updateOn: {
+          refresh: false,
+          resize: false,
+          timeRange: false,
+        },
+      },
+    }]);
+  });
+
   test('add annotations to graph', () => {
     // WHEN
     const stack = new Stack();

packages/@aws-cdk/aws-cloudwatch/test/integ.alarm-and-dashboard.expected.json

@@ -116,7 +116,7 @@
                   "QueueName"
                 ]
               },
-              "\"]],\"singleValueFullPrecision\":true}}]}"
+              "\"]],\"singleValueFullPrecision\":true}},{\"type\":\"custom\",\"width\":6,\"height\":6,\"x\":0,\"y\":56,\"properties\":{\"endpoint\":\"arn:aws:lambda:us-west-2:123456789012:function:my-function\",\"title\":\"My custom alarm\",\"updateOn\":{\"refresh\":true,\"resize\":true,\"timeRange\":true}}}]}"
             ]
           ]
         },

packages/@aws-cdk/aws-cloudwatch/test/integ.alarm-and-dashboard.ts

@@ -102,5 +102,9 @@ dashboard.addWidgets(new cloudwatch.SingleValueWidget({
   metrics: [sentMessageSizeMetric],
   fullPrecision: true,
 }));
+dashboard.addWidgets(new cloudwatch.CustomWidget({
+  title: 'My custom alarm',
+  functionArn: 'arn:aws:lambda:us-west-2:123456789012:function:my-function',
+}));
 
 app.synth();