# MathExpressionProps

Properties for a MathExpression.

Extends: MathExpressionProps
Extends: MathExpressionOptions
Used as props by: MathExpression

- Source: [`aws-cloudwatch/lib/metric.ts`](https://github.com/aws/aws-cdk/blob/v2.274.0/packages/aws-cdk-lib/aws-cloudwatch/lib/metric.ts#L253)

## Example

```ts
declare const matchmakingRuleSet: gamelift.MatchmakingRuleSet;
// Alarm that triggers when the per-second average of not placed matches exceed 10%
const ruleEvaluationRatio = new cloudwatch.MathExpression({
  expression: '1 - (ruleEvaluationsPassed / ruleEvaluationsFailed)',
  usingMetrics: {
    ruleEvaluationsPassed: matchmakingRuleSet.metricRuleEvaluationsPassed({ statistic: cloudwatch.Statistic.SUM }),
    ruleEvaluationsFailed: matchmakingRuleSet.metric('ruleEvaluationsFailed'),
  },
});
new cloudwatch.Alarm(this, 'Alarm', {
  metric: ruleEvaluationRatio,
  threshold: 0.1,
  evaluationPeriods: 3,
});
```

## Properties

- `color`: string — Color for this metric when added to a Graph in a Dashboard.

  **Default:** Automatic color

- `expression`: string (required) — The expression defining the metric.

  When an expression contains a SEARCH function, it cannot be used
  within an Alarm.

- `label`: string — Label for this expression when added to a Graph in a Dashboard.

  **Default:** Expression value is used as label

  If this expression evaluates to more than one time series (for
  example, through the use of `METRICS()` or `SEARCH()` expressions),
  each time series will appear in the graph using a combination of the
  expression label and the individual metric label. Specify the empty
  string (`''`) to suppress the expression label and only keep the
  metric label.

  You can use [dynamic labels](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/graph-dynamic-labels.html)
  to show summary information about the displayed time series
  in the legend. For example, if you use:

  ```
  [max: ${MAX}] MyMetric
  ```

  As the metric label, the maximum value in the visible range will
  be shown next to the time series name in the graph's legend. If the
  math expression produces more than one time series, the maximum
  will be shown for each individual time series produce by this
  math expression.

- `period`: [Duration](/cdk/api/v2/docs/aws-cdk-lib.Duration.html) = Duration.minutes(5) — The period over which the math expression's statistics are applied.

  This period overrides all periods in the metrics used in this
  math expression.

- `searchAccount`: string — Account to evaluate search expressions within.

  **Default:** Deployment account.

  Specifying a searchAccount has no effect to the account used
  for metrics within the expression (passed via usingMetrics).

- `searchRegion`: string — Region to evaluate search expressions within.

  **Default:** Deployment region.

  Specifying a searchRegion has no effect to the region used
  for metrics within the expression (passed via usingMetrics).

- `usingMetrics`: { [key: string]: [IMetric](/cdk/api/v2/docs/aws-cdk-lib.aws_cloudwatch.IMetric.html) } — The metrics used in the expression, in a map.

  **Default:** Empty map.

  The key is the identifier that represents the given metric in the
  expression, and the value is the actual Metric object.

  The `period` of each metric in `usingMetrics` is ignored and instead overridden
  by the `period` specified for the `MathExpression` construct. Even if no `period`
  is specified for the `MathExpression`, it will be overridden by the default
  value (`Duration.minutes(5)`).

  Example:

  ```ts
  declare const metrics: elbv2.IApplicationLoadBalancerMetrics;
  new cloudwatch.MathExpression({
    expression:  'm1+m2',
    label: 'AlbErrors',
    usingMetrics: {
      m1: metrics.custom('HTTPCode_ELB_500_Count', {
        period: Duration.minutes(1), // <- This period will be ignored
        statistic: 'Sum',
        label: 'HTTPCode_ELB_500_Count',
      }),
      m2: metrics.custom('HTTPCode_ELB_502_Count', {
        period: Duration.minutes(1), // <- This period will be ignored
        statistic: 'Sum',
        label: 'HTTPCode_ELB_502_Count',
      }),
    },
    period: Duration.minutes(3), // <- This overrides the period of each metric in `usingMetrics`
                                 //    (Even if not specified, it is overridden by the default value)
  });
  ```