class SearchExpression

Language	Type name
.NET	`Amazon.CDK.AWS.CloudWatch.SearchExpression`
Go	`github.com/aws/aws-cdk-go/awscdk/v2/awscloudwatch#SearchExpression`
Java	`software.amazon.awscdk.services.cloudwatch.SearchExpression`
Python	`aws_cdk.aws_cloudwatch.SearchExpression`
TypeScript (source)	`aws-cdk-lib` » `aws_cloudwatch` » `SearchExpression`

Implements IMetric

A CloudWatch search expression for dynamically finding and graphing multiple related metrics.

Search expressions allow you to search for and graph multiple related metrics from a single expression. This is particularly useful in dynamic environments where the exact metric names or dimensions may not be known at deployment time.

Example:

const searchExpression = new cloudwatch.SearchExpression({
  expression: "SEARCH('{AWS/EC2,InstanceId} CPUUtilization', 'Average', 300)",
  label: 'EC2 CPU Utilization',
  period: Duration.minutes(5),
});

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

Example

const cpuUtilization = new cloudwatch.SearchExpression({
  expression: "SEARCH('{AWS/EC2,InstanceId} MetricName=\"CPUUtilization\"', 'Average', 900)",
  label: 'EC2 CPU Utilization',
  color: '#ff7f0e',
});

Initializer

new SearchExpression(props: SearchExpressionProps)

Parameters

props SearchExpressionProps

Properties

Name	Type	Description
expression	`string`	The search expression defining the metrics to be retrieved.
period	`Duration`	The aggregation period for the metrics produced by the Search Expression.
color?	`string`	Hex color code (e.g. '#00ff00'), to use when rendering the resulting metrics in a graph. If multiple time series are returned, color is assigned to the first metric, color for the other metrics is automatically assigned.
label?	`string`	The label is used as a prefix for the title of each metric returned by the search expression.
searchAccount?	`string`	Account to evaluate search expressions within.
searchRegion?	`string`	Region to evaluate search expressions within.
warnings?⚠️	`string[]`	Warnings generated by this search expression.
warningsV2?	`{ [string]: string }`	Warnings generated by this search expression.

expression

Type: string

The search expression defining the metrics to be retrieved.

period

Type: Duration

The aggregation period for the metrics produced by the Search Expression.

color?

Type: string (optional)

Hex color code (e.g. '#00ff00'), to use when rendering the resulting metrics in a graph. If multiple time series are returned, color is assigned to the first metric, color for the other metrics is automatically assigned.

label?

Type: string (optional)

The label is used as a prefix for the title of each metric returned by the search expression.

searchAccount?

Type: string (optional)

Account to evaluate search expressions within.

searchRegion?

Type: string (optional)

Region to evaluate search expressions within.

warnings?⚠️

⚠️ Deprecated: - use warningsV2

Type: string[] (optional)

Warnings generated by this search expression.

warningsV2?

Type: { [string]: string } (optional)

Warnings generated by this search expression.

Methods

Name	Description
toMetricConfig()	Inspect the details of the metric object.
toString()	Returns a string representation of an object.
with(props)	Return a copy of SearchExpression with properties changed.

toMetricConfig()

public toMetricConfig(): MetricConfig

Returns

MetricConfig

Inspect the details of the metric object.

toString()

public toString(): string

Returns

string

Returns a string representation of an object.

with(props)

public with(props: SearchExpressionOptions): SearchExpression

Parameters

props SearchExpressionOptions — The set of properties to change.

Returns

SearchExpression

Return a copy of SearchExpression with properties changed.

All properties except expression can be changed.