CloudWatch search expression syntax

A valid search expression has the following format.

SEARCH(' {Namespace, DimensionName1, DimensionName2, ...} SearchTerm', 'Statistic')

For example:

SEARCH('{AWS/EC2,InstanceId} MetricName="CPUUtilization"', 'Average')

The preceding example searches the AWS/EC2 namespace for any metrics that have InstanceId as a dimension name. It returns all CPUUtilization metrics that it finds, with the graph showing the Average statistic.

A search expression can find only metrics that have reported data within the past two weeks.

Search expression limits

The maximum search expression query size is 1024 characters. You can have as many as 100 search expressions on one graph. A graph can display as many as 500 time series.

CloudWatch search expressions: Tokenization

When you specify a SearchTerm, the search function searches for tokens, which are substrings that CloudWatch automatically generates from full metric names, dimension names, dimension values, and namespaces. CloudWatch generates tokens distinguished by the camel-case capitalization in the original string. Numeric characters also serve as the start of new tokens, and non-alphanumeric characters serve as delimiters, creating tokens before and after the non-alphanumeric characters.

A continuous string of the same type of token delimiter character results in one token.

All generated tokens are in lowercase. The following table shows some examples of tokens generated.

CloudWatch search expressions: Partial matches

When you specify a SearchTerm, the search term is also tokenized. CloudWatch finds metrics based on partial matches, which are matches of a single token generated from the search term to a single token generated from a metric name, namespace, dimension name, or dimension value.

Partial match searches to match a single token are case insensitive. For example, using any of the following search terms can return the CustomCount1 metric:

However, using couNT as a search term doesn't find CustomCount1 because the capitalization in the search term couNT is tokenized into cou and NT.

Searches can also match composite tokens, which are multiple tokens that appear consecutively in the original name. To match a composite token, the search is case sensitive. For example, if the original term is CustomCount1, searches for CustomCount or Count1 are successful, but searches for customcount or count1 aren't.

CloudWatch search expressions: Exact matches

You can define a search to find only exact matches of your search term by using double quotes around the part of the search term that requires an exact match. These double-quotes are enclosed in the single-quotes used around the entire search term. For example, SEARCH(' {MyNamespace}, "CustomCount1" ', 'Maximum') finds the exact string CustomCount1 if it exists as a metric name, dimension name, or dimension value in the namespace named MyNamespace. However, the searches SEARCH(' {MyNamespace}, "customcount1" ', 'Maximum') or SEARCH(' {MyNamespace}, "Custom" ', 'Maximum') do not find this string.

You can combine partial match terms and exact match terms in a single search expression. For example, SEARCH(' {AWS/NetworkELB, LoadBalancer} "ConsumedLCUs" OR flow ', 'Maximum') returns the Elastic Load Balancing metric named ConsumedLCUs as well as all Elastic Load Balancing metrics or dimensions that contain the token flow.

Using exact match is also a good way to find names with special characters, such as non-alphanumeric characters or spaces, as in the following example.

SEARCH(' {"My Namespace", "Dimension@Name"}, "Custom:Name[Special_Characters" ', 'Maximum')

CloudWatch search expressions: Excluding a metric schema

All examples shown so far include a metric schema, in curly braces. Searches that omit a metric schema are also valid.

For example, SEARCH(' "CPUUtilization" ', 'Average') returns all metric names, dimension names, dimension values, and namespaces that are an exact match for the string CPUUtilization. In the AWS metric namespaces, this can include metrics from several services including Amazon EC2, Amazon ECS, SageMaker, and others.

To narrow this search to only one AWS service, the best practice is to specify the namespace and any necessary dimensions in the metric schema, as in the following example. Although this narrows the search to the AWS/EC2 namespace, it would still return results of other metrics if you have defined CPUUtilization as a dimension value for those metrics.

SEARCH(' {AWS/EC2, InstanceType} "CPUUtilization" ', 'Average')

Alternatively you could add the namespace in the SearchTerm as in the following example. But in this example, the search would match any AWS/EC2 string, even if it was a custom dimension name or value.

SEARCH(' "AWS/EC2" MetricName="CPUUtilization" ', 'Average')

CloudWatch search expressions: Specifying property names in the search

The following exact match search for "CustomCount1" returns all metrics with exactly that name.

SEARCH(' "CustomCount1" ', 'Maximum')

But it also returns metrics with dimension names, dimension values, or namespaces of CustomCount1. To structure your search further, you can specify the property name of the type of object that you want to find in your searches. The following example searches all namespaces and returns metrics named CustomCount1.

SEARCH(' MetricName="CustomCount1" ', 'Maximum')

You can also use namespaces and dimension name/value pairs as property names, as in the following examples. The first of these examples also illustrates that you can use property names with partial match searches as well.

SEARCH(' InstanceType=micro ', 'Average')

SEARCH(' InstanceType="t2.micro" Namespace="AWS/EC2" ', 'Average')

CloudWatch search expressions: Non-alphanumeric characters

Non-alphanumeric characters serve as delimiters, and mark where the names of metrics, dimensions, namespaces, and search terms are to be separated into tokens. When terms are tokenized, non-alphanumeric characters are stripped out and don't appear in the tokens. For example, Network-Errors_2 generates the tokens network, errors, and 2.

Your search term can include any non-alphanumeric characters. If these characters appear in your search term, they can specify composite tokens in a partial match. For example, all of the following searches would find metrics named either Network-Errors-2 or NetworkErrors2.

network/errors
network+errors
network-errors
Network_Errors

When you're doing an exact value search, any non-alphanumeric characters used in the exact search must be the correct characters that appear in the string being searched for. For example, if you want to find Network-Errors-2, searching for "Network-Errors-2" is successful, but a search for "Network_Errors_2" isn't.

When you perform an exact match search, the following characters must be escaped with a backslash.

" \ ( )

For example, to find the metric name Europe\France Traffic(Network) by exact match, use the search term "Europe\\France Traffic\(Network\)"

CloudWatch search expressions: Boolean operators

Search supports the use of the Boolean operators AND, OR, and NOT within the SearchTerm. Boolean operators are enclosed in the single quote marks that you use to enclose the entire search term. Boolean operators are case sensitive, so and, or, and not aren't valid as Boolean operators.

You can use AND explicitly in your search, such as SEARCH('{AWS/EC2,InstanceId} network AND packets', 'Average'). Not using any Boolean operator between search terms implicitly searches them as if there were an AND operator, so SEARCH(' {AWS/EC2,InstanceId} network packets ', 'Average') yields the same search results.

Use NOT to exclude subsets of data from the results. For example, SEARCH(' {AWS/EC2,InstanceId} MetricName="CPUUtilization" NOT i-1234567890123456 ', 'Average') returns the CPUUtilization for all your instances, except for the instance i-1234567890123456. You can also use a NOT clause as the only search term. For example, SEARCH( 'NOT Namespace=AWS ', 'Maximum') yields all your custom metrics (metrics with namespaces that don't include AWS).

You can use multiple NOT phrases in a query. For example, SEARCH(' {AWS/EC2,InstanceId} MetricName="CPUUtilization" NOT "ProjectA" NOT "ProjectB" ', 'Average') returns the CPUUtilization of all instances in the Region, except for those with dimension values of ProjectA or ProjectB.

You can combine Boolean operators for more powerful and detailed searches, as in the following examples. Use parentheses to group the operators.

Both of the next two examples return all metric names containing ReadOps from both the EC2 and EBS namespaces.

SEARCH(' (EC2 OR EBS) AND MetricName=ReadOps ', 'Maximum')

SEARCH(' (EC2 OR EBS) MetricName=ReadOps ', 'Maximum')

The following example narrows the previous search to only results that include ProjectA, which could be the value of a dimension.

SEARCH(' (EC2 OR EBS) AND ReadOps AND ProjectA ', 'Maximum')

The following example uses nested grouping. It returns Lambda metrics for Errors from all functions, and Invocations of functions with names that include the strings ProjectA or ProjectB.

SEARCH(' {AWS/Lambda,FunctionName} MetricName="Errors" OR (MetricName="Invocations" AND (ProjectA OR ProjectB)) ', 'Average')

CloudWatch search expressions: Using math expressions

You can use a search expression within a math expressions in a graph.

For example, SUM(SEARCH(' {AWS/Lambda, FunctionName} MetricName="Errors" ', 'Sum')) returns the sum of the Errors metric of all your Lambda functions.

Using separate lines for your search expression and math expression might yield more useful results. For example, suppose that you use the following two expressions in a graph. The first line displays separate Errors lines for each of your Lambda functions. The ID of this expression is e1. The second line adds another line showing the sum of the errors from all of the functions.

SEARCH(' {AWS/Lambda, FunctionName}, MetricName="Errors" ', 'Sum')
SUM(e1)