# MathExpression

A math expression built with metric(s) emitted by a service.

The math expression is a combination of an expression (x+y) and metrics to apply expression on.
It also contains metadata which is used only in graphs, such as color and label.
It makes sense to embed this in here, so that compound constructs can attach
that metadata to metrics they expose.

MathExpression can also be used for search expressions. In this case,
it also optionally accepts a searchRegion and searchAccount property for cross-environment
search expressions.

This class does not represent a resource, so hence is not a construct. Instead,
MathExpression is an abstraction that makes it easy to specify metrics for use in both
alarms and graphs.

Extends: MathExpression
Implements: IMetric

- Source: [`aws-cloudwatch/lib/metric.ts`](https://github.com/aws/aws-cdk/blob/v2.275.0/packages/aws-cdk-lib/aws-cloudwatch/lib/metric.ts#L771)
- Type last changed: v2.93.0 · 23 Aug 2023

## 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,
});
```

## Initializer

```ts
new MathExpression(props: MathExpressionProps)
```

## Properties

- `color`: string — The hex color code, prefixed with '#' (e.g. '#00ff00'), to use when this metric is rendered on a graph. The `Color` class has a set of standard colors that can be used here.

- `expression`: string — The expression defining the metric.

- `label`: string — Label for this metric when added to a Graph.

- `period`: [Duration](/cdk/api/v2/docs/aws-cdk-lib.Duration.html) — Aggregation period of this metric.

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

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

- `usingMetrics`: { [key: string]: [IMetric](/cdk/api/v2/docs/aws-cdk-lib.aws_cloudwatch.IMetric.html) } — The metrics used in the expression as KeyValuePair <id, metric>.

- `warnings`: string[] — - use warningsV2

- `warningsV2`: { [key: string]: string } — Warnings generated by this math expression.

## Methods

- `createAlarm(scope: Construct, id: string, props: CreateAlarmOptions): Alarm` — Make a new Alarm for this metric.

  Combines both properties that may adjust the metric (aggregation) as well
  as alarm properties.

- `toMetricConfig(): MetricConfig` — Inspect the details of the metric object.

- `toString(): string` — Returns a string representation of an object.

- `with(props: MathExpressionOptions): MathExpression // chainable` — Return a copy of Metric with properties changed.

  All properties except namespace and metricName can be changed.

  **Parameters**

  - `props` — The set of properties to change.