feat(cloudwatch): add contributor insights widget

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

@@ -178,7 +178,7 @@ alarm.addAlarmAction(new cw_actions.SnsAction(topic));
 
 ### Composite Alarms
 
-[Composite Alarms](https://aws.amazon.com/about-aws/whats-new/2020/03/amazon-cloudwatch-now-allows-you-to-combine-multiple-alarms/) 
+[Composite Alarms](https://aws.amazon.com/about-aws/whats-new/2020/03/amazon-cloudwatch-now-allows-you-to-combine-multiple-alarms/)
 can be created from existing Alarm resources.
 
 ```ts
@@ -375,6 +375,18 @@ dashboard.addWidgets(new LogQueryWidget({
 }));
 ```
 
+### Contributor Insights widget
+
+A `ContributorInsightsWidget` displays data from a Contributor Insights rule:
+
+```ts
+dashboard.addWidgets(new cloudwatch.ContributorInsightsWidget({
+  title: 'Top 50 callers',
+  ruleName: 'my-contributor-insights-rule',
+  contributorSelection: cloudwatch.TopContributors.TOP50,
+}));
+```
+
 ### Dashboard Layout
 
 The widgets on a dashboard are visually laid out in a grid that is 24 columns

packages/@aws-cdk/aws-cloudwatch/lib/contributor-insights-widget.ts

@@ -0,0 +1,170 @@
+import * as cdk from '@aws-cdk/core';
+import { LegendPosition } from './graph';
+import { ConcreteWidget } from './widget';
+/**
+ * The number of top contributors to show.
+ */
+export enum TopContributors {
+  /**
+   * The top 10 contributors
+   */
+  TOP10 = 10,
+  /**
+   * The top 25 contributors
+   */
+  TOP25 = 25,
+  /**
+   * The top 50 contributors
+   */
+  TOP50 = 50,
+  /**
+   * The top 100 contributors
+   */
+  TOP100 = 100,
+}
+
+/**
+ * Statistic to use over the aggregation period
+ */
+export enum OrderStatistic {
+  /**
+   * All values submitted for the matching metric added together.
+   * This statistic can be useful for determining the total volume of a metric.
+   */
+  SUM = 'Sum',
+  /**
+   * The highest value observed during the specified period.
+   * You can use this value to determine high volumes of activity for your application.
+   */
+  MAXIMUM = 'Maximum'
+}
+
+/**
+ * Properties for a Contributor Insights widget
+ */
+export interface ContributorInsightsWidgetProps {
+  /**
+   * Title for the widget
+   *
+   * @default No title
+   */
+  readonly title?: string;
+
+  /**
+   * Insights rule to display
+   */
+  readonly ruleName: string;
+
+  /**
+   * The selection of contributors to display
+   *
+   * @default Top 10
+   */
+  readonly contributorSelection?: TopContributors;
+
+  /**
+   * Position of the legend
+   *
+   * @default - bottom
+   */
+  readonly legendPosition?: LegendPosition;
+
+  /**
+   * The region the metrics of this widget should be taken from
+   *
+   * @default Current region
+   */
+  readonly region?: string;
+
+  /**
+   * Whether the graph should be shown as stacked lines
+   *
+   * @default false
+   */
+  readonly stacked?: boolean;
+
+  /**
+   * What function to use for aggregating.
+   *
+   * @default Statistic.SUM
+   */
+  readonly statistic?: OrderStatistic;
+
+  /**
+   * The period over which the statistics are applied.
+   *
+   * @default Duration.minutes(5)
+   */
+  readonly period?: cdk.Duration;
+
+  /**
+   * Width of the widget, in a grid of 24 units wide
+   *
+   * @default 6
+   */
+  readonly width?: number;
+
+  /**
+   * Height of the widget
+   *
+   * @default 6
+   */
+  readonly height?: number;
+
+  /**
+   * Account the contributor insights data comes from
+   *
+   * @default Deployment account
+   */
+  readonly account?: string;
+}
+
+/**
+ * Display contributor insights
+ */
+export class ContributorInsightsWidget extends ConcreteWidget {
+  private readonly props: ContributorInsightsWidgetProps;
+  private period: number;
+
+  constructor(props: ContributorInsightsWidgetProps) {
+    super(props.width || 6, props.height || 6);
+
+    this.period = (props.period || cdk.Duration.minutes(5)).toSeconds();
+    if (![60, 300, 900, 3600, 21600, 86400].includes(this.period)) {
+      throw new Error(
+        `'period' must be 60s, 300s, 900s, 3600s, 21600s, or 86400s, received ${this.period}`,
+      );
+    }
+    this.props = props;
+  }
+
+  public toJson(): any[] {
+    return [
+      {
+        type: 'metric',
+        width: this.width,
+        height: this.height,
+        x: this.x,
+        y: this.y,
+        stacked: this.props.stacked || false,
+        properties: {
+          accountId: this.props.account,
+          period: this.period,
+          view: 'timeSeries',
+          title: this.props.title,
+          region: this.props.region || cdk.Aws.REGION,
+          insightRule: {
+            maxContributorCount:
+              this.props.contributorSelection || TopContributors.TOP10,
+            orderBy: this.props.statistic || OrderStatistic.SUM,
+            ruleName: this.props.ruleName,
+          },
+          legend:
+            this.props.legendPosition !== undefined
+              ? { position: this.props.legendPosition }
+              : undefined,
+        },
+      },
+    ];
+  }
+}

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

@@ -12,6 +12,7 @@ export * from './log-query';
 export * from './text';
 export * from './widget';
 export * from './alarm-status-widget';
+export * from './contributor-insights-widget';
 
 // AWS::CloudWatch CloudFormation Resources:
 export * from './cloudwatch.generated';

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

@@ -109,7 +109,11 @@
                   "QueueName"
                 ]
               },
-              "\"]],\"singleValueFullPrecision\":true}}]}"
+              "\"]],\"singleValueFullPrecision\":true}},{\"type\":\"metric\",\"width\":6,\"height\":6,\"x\":0,\"y\":53,\"stacked\":false,\"properties\":{\"period\":300,\"view\":\"timeSeries\",\"title\":\"Top 50 callers\",\"region\":\"",
+              {
+                "Ref": "AWS::Region"
+              },
+              "\",\"insightRule\":{\"maxContributorCount\":50,\"orderBy\":\"Sum\",\"ruleName\":\"my-contributor-insights-rule\"}}}]}"
             ]
           ]
         },

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

@@ -98,5 +98,10 @@ dashboard.addWidgets(new cloudwatch.SingleValueWidget({
   metrics: [sentMessageSizeMetric],
   fullPrecision: true,
 }));
+dashboard.addWidgets(new cloudwatch.ContributorInsightsWidget({
+  title: 'Top 50 callers',
+  ruleName: 'my-contributor-insights-rule',
+  contributorSelection: cloudwatch.TopContributors.TOP50,
+}));
 
 app.synth();

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

@@ -1,6 +1,6 @@
 import { Stack } from '@aws-cdk/core';
 import { Test } from 'nodeunit';
-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, ContributorInsightsWidget } from '../lib';
 
 export = {
   'add stacked property to graphs'(test: Test) {
@@ -317,6 +317,38 @@ export = {
     test.done();
   },
 
+
+  'contributor insights widget'(test: Test) {
+    // GIVEN
+    const stack = new Stack();
+    const ruleName = 'my-contributor-insights-rule';
+
+    // WHEN
+    const widget = new ContributorInsightsWidget({
+      ruleName,
+    });
+
+    // THEN
+    test.deepEqual(stack.resolve(widget.toJson()), [{
+      type: 'metric',
+      width: 6,
+      height: 6,
+      stacked: false,
+      properties: {
+        period: 300,
+        view: 'timeSeries',
+        region: { Ref: 'AWS::Region' },
+        insightRule: {
+          maxContributorCount: 10,
+          orderBy: 'Sum',
+          ruleName: 'my-contributor-insights-rule',
+        },
+      },
+    }]);
+
+    test.done();
+  },
+
   'alarm widget'(test: Test) {
     // GIVEN
     const stack = new Stack();