Cloudwatch metrics

packages/@aws-cdk/assert/lib/assertions/have-resource.ts

@@ -3,6 +3,11 @@ import { StackInspector } from "../inspector";
 
 /**
  * An assertion to check whether a resource of a given type and with the given properties exists, disregarding properties
+ *
+ * Properties can be:
+ *
+ * - An object, in which case its properties will be compared to those of the actual resource found
+ * - A callablage, in which case it will be treated as a predicate that is applied to the Properties of the found resources.
  */
 export function haveResource(resourceType: string, properties?: any): Assertion<StackInspector> {
     return new HaveResourceAssertion(resourceType, properties);
@@ -21,7 +26,17 @@ class HaveResourceAssertion extends Assertion<StackInspector> {
             const resource = inspector.value.Resources[logicalId];
             if (resource.Type === this.resourceType) {
                 this.inspected.push(resource);
-                if (isSuperObject(resource.Properties, this.properties)) {
+
+                let matches: boolean;
+                if (typeof this.properties === 'function') {
+                    // If 'properties' is a callable, invoke it
+                    matches = this.properties(resource.Properties);
+                } else {
+                    // Otherwise treat as property bag that we check superset of
+                    matches = isSuperObject(resource.Properties, this.properties);
+                }
+
+                if (matches) {
                     return true;
                 }
             }
@@ -47,7 +62,7 @@ class HaveResourceAssertion extends Assertion<StackInspector> {
  *
  * A super-object has the same or more property values, recursing into nested objects.
  */
-function isSuperObject(superObj: any, obj: any): boolean {
+export function isSuperObject(superObj: any, obj: any): boolean {
     if (obj == null) { return true; }
     if (Array.isArray(superObj) !== Array.isArray(obj)) { return false; }
     if (Array.isArray(superObj)) {

packages/@aws-cdk/cloudwatch/.gitignore

@@ -0,0 +1,7 @@
+*.js
+tsconfig.json
+tslint.json
+*.js.map
+*.d.ts
+dist
+lib/generated/resources.ts

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

@@ -0,0 +1,44 @@
+Add alarms and graphs to CDK applications
+=========================================
+
+
+Making Alarms
+-------------
+
+Making Dashboards
+-----------------
+
+Dashboards are set of Widgets stored server-side which can be accessed quickly
+from the AWS console. Available widgets are graphs of a metric over time, the
+current value of a metric, or a static piece of Markdown which explains what the
+graphs mean.
+
+The following widgets are available:
+
+- `GraphWidget` -- shows any number of metrics on both the left and right
+  vertical axes.
+- `AlarmWidget` -- shows the graph and alarm line for a single alarm.
+- `SingleValueWidget` -- shows the current value of a set of metrics.
+- `TextWidget` -- shows some static Markdown.
+
+
+Dashboard Layout
+----------------
+
+The widgets on a dashboard are visually laid out in a grid that is 24 columns
+wide. Normally you specify X and Y coordinates for the widgets on a Dashboard,
+but because this is inconvenient to do manually, the library contains a simple
+layout system to help you lay out your dashboards the way you want them to.
+
+Widgets have a `width` and `height` property, and they will be automatically
+laid out either horizontally or vertically stacked to fill out the available
+space.
+
+Widgets are added to a Dashboard by calling `add(widget1, widget2, ...)`.
+Widgets given in the same call will be laid out horizontally. Widgets given
+in different calls will be laid out vertically. To make more complex layouts,
+you can use the following widgets to pack widgets together in different ways:
+
+- `Column`: stack two or more widgets vertically.
+- `Row`: lay out two or more widgets horizontally.
+- `Spacer`: take up empty space

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

@@ -0,0 +1,195 @@
+import { Arn, Construct, Token } from '@aws-cdk/core';
+import { cloudwatch } from '@aws-cdk/resources';
+import { Metric } from './metric';
+
+/**
+ * Properties for Alarms
+ */
+export interface AlarmProps {
+    /**
+     * The metric to add the alarm on
+     */
+    metric: Metric;
+
+    /**
+     * Name of the alarm
+     *
+     * @default Automatically generated name
+     */
+    alarmName?: string;
+
+    /**
+     * Description for the alarm
+     *
+     * @default No description
+     */
+    alarmDescription?: string;
+
+    /**
+     * Comparison to use to check if metric is breaching
+     *
+     * @default GreaterThanOrEqualToThreshold
+     */
+    comparisonOperator?: ComparisonOperator;
+
+    /**
+     * The value against which the specified statistic is compared.
+     */
+    threshold: number;
+
+    /**
+     * The number of periods over which data is compared to the specified threshold.
+     */
+    evaluationPeriods: number;
+
+    /**
+     * Number of datapoints that must be breaching to trigger the alarm
+     *
+     * This is used only if you are setting an "M out of N" alarm. In that case, this value is the M.
+     *
+     * @default Not an "M out of N" alarm.
+     */
+    datapointsToAlarm?: number;
+
+    /**
+     * Specifies whether to evaluate the data and potentially change the alarm state if there are too few data points to be statistically significant.
+     *
+     * Used only for alarms that are based on percentiles.
+     */
+    evaluateLowSampleCountPercentile?: string;
+
+    /**
+     * Sets how this alarm is to handle missing data points.
+     *
+     * @default TreatMissingData.Missing
+     */
+    treatMissingData?: TreatMissingData;
+
+    /**
+     * Whether the actions for this alarm are enabled
+     *
+     * @default true
+     */
+    actionsEnabled?: boolean;
+}
+
+/**
+ * Comparison operator for evaluating alarms
+ */
+export enum ComparisonOperator {
+    GreaterThanOrEqualToThreshold = 'GreaterThanOrEqualToThreshold',
+    GreaterThanThreshold = 'GreaterThanThreshold',
+    LessThanThreshold = 'LessThanThreshold',
+    LessThanOrEqualToThreshold = 'LessThanOrEqualToThreshold',
+}
+
+/**
+ * Specify how missing data points are treated during alarm evaluation
+ */
+export enum TreatMissingData {
+    /**
+     * Missing data points are treated as breaching the threshold
+     */
+    Breaching = 'breaching',
+
+    /**
+     * Missing data points are treated as being within the threshold
+     */
+    NotBreaching = 'notBreaching',
+
+    /**
+     * The current alarm state is maintained
+     */
+    Ignore = 'ignore',
+
+    /**
+     * The alarm does not consider missing data points when evaluating whether to change state
+     */
+    Missing = 'missing'
+}
+
+/**
+ * An alarm on a CloudWatch metric
+ */
+export class Alarm extends Construct {
+    /**
+     * ARN of this alarm
+     */
+    public readonly alarmArn: AlarmArn;
+
+    /**
+     * The metric object this alarm was based on
+     */
+    public readonly metric: Metric;
+
+    private alarmActions?: Arn[];
+    private insufficientDataActions?: Arn[];
+    private okActions?: Arn[];
+
+    constructor(parent: Construct, name: string, props: AlarmProps) {
+        super(parent, name);
+
+        const alarm = new cloudwatch.AlarmResource(this, 'Resource', {
+            actionsEnabled: props.actionsEnabled,
+            alarmActions: new Token(() => this.alarmActions),
+            alarmDescription: props.alarmDescription,
+            alarmName: props.alarmName,
+            comparisonOperator: props.comparisonOperator || ComparisonOperator.GreaterThanOrEqualToThreshold,
+            evaluateLowSampleCountPercentile: props.evaluateLowSampleCountPercentile,
+            evaluationPeriods: props.evaluationPeriods,
+            insufficientDataActions: new Token(() => this.insufficientDataActions),
+            okActions: new Token(() => this.okActions),
+            threshold: props.threshold,
+            treatMissingData: props.treatMissingData,
+            ...props.metric.toAlarmJson()
+        });
+
+        this.alarmArn = alarm.alarmArn;
+        this.metric = props.metric;
+    }
+
+    /**
+     * Trigger this action if the alarm fires
+     *
+     * Typically the ARN of an SNS topic or ARN of an AutoScaling policy.
+     */
+    public onAlarm(arn: Arn) {
+        if (this.alarmActions === undefined) {
+            this.alarmActions = [];
+        }
+
+        this.alarmActions.push(arn);
+    }
+
+    /**
+     * Trigger this action if there is insufficient data to evaluate the alarm
+     *
+     * Typically the ARN of an SNS topic or ARN of an AutoScaling policy.
+     */
+    public onInsufficientData(arn: Arn) {
+        if (this.insufficientDataActions === undefined) {
+            this.insufficientDataActions = [];
+        }
+
+        this.insufficientDataActions.push(arn);
+    }
+
+    /**
+     * Trigger this action if the alarm returns from breaching state into ok state
+     *
+     * Typically the ARN of an SNS topic or ARN of an AutoScaling policy.
+     */
+    public onOk(arn: Arn) {
+        if (this.okActions === undefined) {
+            this.okActions = [];
+        }
+
+        this.okActions.push(arn);
+    }
+}
+
+/**
+ * The ARN of an Alarm
+ */
+export class AlarmArn extends Arn {
+}

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

@@ -0,0 +1,51 @@
+import { Construct, resolve, Token } from "@aws-cdk/core";
+import { cloudwatch } from "@aws-cdk/resources";
+import { Column, Row } from "./layout";
+import { Widget } from "./widget";
+
+export interface DashboardProps {
+    /**
+     * Name of the dashboard
+     *
+     * @default Automatically generated name
+     */
+    dashboardName?: string;
+}
+
+/**
+ * A CloudWatch dashboard
+ */
+export class Dashboard extends Construct {
+    private readonly rows: Widget[] = [];
+
+    constructor(parent: Construct, name: string, props?: DashboardProps) {
+        super(parent, name);
+
+        new cloudwatch.DashboardResource(this, 'Resource', {
+            dashboardName: props && props.dashboardName,
+            dashboardBody: new Token(() => {
+                const column = new Column(...this.rows);
+                column.position(0, 0);
+                return JSON.stringify(resolve({ widgets: column.toJson() }));
+            })
+        });
+    }
+
+    /**
+     * Add a widget to the dashboard.
+     *
+     * Widgets given in multiple calls to add() will be laid out stacked on
+     * top of each other.
+     *
+     * Multiple widgets added in the same call to add() will be laid out next
+     * to each other.
+     */
+    public add(...widgets: Widget[]) {
+        if (widgets.length === 0) {
+            return;
+        }
+
+        const w = widgets.length > 1 ? new Row(...widgets) : widgets[0];
+        this.rows.push(w);
+    }
+}