feat(cloudwatch): support cross-environment search expressions

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

@@ -334,6 +334,8 @@ export class Alarm extends AlarmBase {
                 assertSubmetricsCount(expr);
               }
 
+              self.validateMetricExpression(expr);
+
               return {
                 expression: expr.expression,
                 id: entry.id || uniqueMetricId(),
@@ -358,6 +360,17 @@ export class Alarm extends AlarmBase {
       throw new Error(`Cannot create an Alarm in region '${stack.region}' based on metric '${metric}' in '${stat.region}'`);
     }
   }
+
+  /**
+   * Validates that if a region or account is in the given expression config, they match the Alarm
+   */
+  private validateMetricExpression(expr: MetricExpressionConfig) {
+    const stack = Stack.of(this);
+
+    if (definitelyDifferent(expr.account, stack.account) || definitelyDifferent(expr.region, stack.region)) {
+      throw new Error('Cannot create an Alarm with a cross-account or cross-region math expression');
+    }
+  }
 }
 
 function definitelyDifferent(x: string | undefined, y: string) {

packages/@aws-cdk/aws-cloudwatch/lib/metric-types.ts

@@ -322,6 +322,20 @@ export interface MetricExpressionConfig {
    * How many seconds to aggregate over
    */
   readonly period: number;
+
+  /**
+   * Account to evaluate the expression within (for example when an expression includes SEARCH or SERVICE_QUOTA)
+   *
+   * @default Deployment account.
+   */
+  readonly account?: string;
+
+  /**
+   * Region to evaluate the expression within (for example when an expression includes SEARCH or SERVICE_QUOTA)
+   *
+   * @default Deployment region.
+   */
+  readonly region?: string;
 }
 
 /**

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

@@ -149,6 +149,20 @@ export interface MathExpressionOptions {
    * @default Duration.minutes(5)
    */
   readonly period?: cdk.Duration;
+
+  /**
+   * Account to evaluate the expression within (for example when an expression includes SEARCH or SERVICE_QUOTA)
+   *
+   * @default - Deployment account.
+   */
+  readonly account?: string;
+
+  /**
+    * Region to evaluate the expression within (for example when an expression includes SEARCH or SERVICE_QUOTA)
+    *
+    * @default - Deployment region.
+    */
+  readonly region?: string;
 }
 
 /**
@@ -482,12 +496,24 @@ export class MathExpression implements IMetric {
    */
   public readonly period: cdk.Duration;
 
+  /**
+   * The account in which the expression is executed
+   */
+  public readonly account?: string;
+
+  /**
+   * The region in which the expression is executed
+   */
+  public readonly region?: string;
+
   constructor(props: MathExpressionProps) {
     this.period = props.period || cdk.Duration.minutes(5);
     this.expression = props.expression;
     this.usingMetrics = changeAllPeriods(props.usingMetrics, this.period);
     this.label = props.label;
     this.color = props.color;
+    this.account = props.account;
+    this.region = props.region;
 
     const invalidVariableNames = Object.keys(props.usingMetrics).filter(x => !validVariableName(x));
     if (invalidVariableNames.length > 0) {
@@ -508,7 +534,9 @@ export class MathExpression implements IMetric {
     // Short-circuit creating a new object if there would be no effective change
     if ((props.label === undefined || props.label === this.label)
       && (props.color === undefined || props.color === this.color)
-      && (props.period === undefined || props.period.toSeconds() === this.period.toSeconds())) {
+      && (props.period === undefined || props.period.toSeconds() === this.period.toSeconds())
+      && (props.account === undefined || props.account === this.account)
+      && (props.region === undefined || props.region === this.region)) {
       return this;
     }
 
@@ -518,6 +546,8 @@ export class MathExpression implements IMetric {
       label: ifUndefined(props.label, this.label),
       color: ifUndefined(props.color, this.color),
       period: ifUndefined(props.period, this.period),
+      account: ifUndefined(props.account, this.account),
+      region: ifUndefined(props.region, this.region),
     });
   }
 
@@ -541,6 +571,8 @@ export class MathExpression implements IMetric {
         period: this.period.toSeconds(),
         expression: this.expression,
         usingMetrics: this.usingMetrics,
+        account: this.account,
+        region: this.region,
       },
       renderingProperties: {
         label: this.label,

packages/@aws-cdk/aws-cloudwatch/lib/private/metric-util.ts

@@ -25,6 +25,12 @@ export function metricKey(metric: IMetric): string {
       parts.push(id);
       parts.push(metricKey(conf.mathExpression.usingMetrics[id]));
     }
+    if (conf.mathExpression.region) {
+      parts.push(conf.mathExpression.region);
+    }
+    if (conf.mathExpression.account) {
+      parts.push(conf.mathExpression.account);
+    }
   }
   if (conf.metricStat) {
     parts.push(conf.metricStat.namespace);

packages/@aws-cdk/aws-cloudwatch/lib/private/rendering.ts

@@ -55,6 +55,8 @@ function metricGraphJson(metric: IMetric, yAxis?: string, id?: string) {
 
     withExpression(expr) {
       options.expression = expr.expression;
+      if (expr.account) { options.accountId = accountIfDifferentFromStack(expr.account); }
+      if (expr.region) { options.region = regionIfDifferentFromStack(expr.region); }
       if (expr.period && expr.period !== 300) { options.period = expr.period; }
     },
   });

packages/@aws-cdk/aws-cloudwatch/test/cross-environment.test.ts

@@ -78,6 +78,35 @@ describe('cross environment', () => {
 
 
     });
+
+    test('math expressions with explicit account and region will render in environment agnostic stack', () => {
+      // GIVEN
+      const expression = 'SEARCH(\'MetricName="ACount"\', \'Sum\', 300)';
+
+      const b = new MathExpression({
+        expression,
+        usingMetrics: {},
+        label: 'Test label',
+        account: '5678',
+        region: 'mars',
+      });
+
+      const graph = new GraphWidget({
+        left: [
+          b,
+        ],
+      });
+
+      // THEN
+      graphMetricsAre(new Stack(), graph, [
+        [{
+          expression,
+          accountId: '5678',
+          region: 'mars',
+          label: 'Test label',
+        }],
+      ]);
+    });
   });
 
   describe('in alarms', () => {
@@ -234,6 +263,60 @@ describe('cross environment', () => {
         ],
       });
     });
+
+    test('math expression with different account will throw', () => {
+      // Cross-region/cross-account math expressions (e.g. SEARCH) are supported in Dashboards
+      // but not in Alarms (submetrics can be cross-account for Alarms, but math expressions
+      // themselves cannot be)
+
+      // GIVEN
+      const b = new Metric({
+        namespace: 'Test',
+        metricName: 'ACount',
+        account: '1234',
+      });
+
+      const c = new MathExpression({
+        expression: 'a + b',
+        usingMetrics: { a: a.attachTo(stack3), b },
+        period: Duration.minutes(1),
+        account: '5678',
+      });
+
+      // THEN
+      expect(() => {
+        new Alarm(stack1, 'Alarm', {
+          threshold: 1,
+          evaluationPeriods: 1,
+          metric: c,
+        });
+      }).toThrow(/Cannot create an Alarm with a cross-account or cross-region math expression/);
+    });
+
+    test('match expression with different region will throw', () => {
+      // GIVEN
+      const b = new Metric({
+        namespace: 'Test',
+        metricName: 'ACount',
+        account: '1234',
+      });
+
+      const c = new MathExpression({
+        expression: 'a + b',
+        usingMetrics: { a: a.attachTo(stack3), b },
+        period: Duration.minutes(1),
+        region: 'mars',
+      });
+
+      // THEN
+      expect(() => {
+        new Alarm(stack1, 'Alarm', {
+          threshold: 1,
+          evaluationPeriods: 1,
+          metric: c,
+        });
+      }).toThrow(/Cannot create an Alarm with a cross-account or cross-region math expression/);
+    });
   });
 });