# Use search expressions in graphs Search expressions are a type of math expression that you can add to CloudWatch graphs. Search expressions enable you to quickly add multiple related metrics to a graph. They also enable you to create dynamic graphs that automatically add appropriate metrics to their display, even if those metrics don't exist when you first create the graph. For example, you can create a search expression that displays the `AWS/EC2 CPUUtilization` metric for all instances in the Region. If you later launch a new instance, the `CPUUtilization` of the new instance is automatically added to the graph. When you use a search expression in a graph, the search finds the search expression in metric names, namespaces, dimension names, and dimension values. You can use Boolean operators for more complex and powerful searches. A search expression can find only metrics that have reported data within the past two weeks. You can't create an alarm based on the **SEARCH** expression. This is because search expressions return multiple time series, and an alarm based on a math expression can watch only one time series. If you are using a monitoring account in CloudWatch cross-account observability, your search expressions can find metrics in the source accounts linked to that monitoring account. **Topics** + [CloudWatch search expression syntax](search-expression-syntax.md) + [CloudWatch search expression examples](search-expression-examples.md) + [Create a CloudWatch graph with a search expression](create-search-expression.md) # 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 first part of the query after the word `SEARCH`, enclosed in curly braces, is the *metric schema* to be searched. The metric schema contains a metric namespace and one or more dimension names. Including a metric schema in a search query is optional. If specified, the metric schema must contain a namespace and can optionally contain one or more dimension names that are valid in that namespace. You don't need to use quote marks inside the metric schema unless a namespace or dimension name includes spaces or non-alphanumeric characters. In that case, you must enclose the name that contains those characters with double quotes. + The `SearchTerm` is also optional, but a valid search must contain either the metric schema, the `SearchTerm`, or both. The `SearchTerm` usually contains one or more account IDs, metric names or dimension values. The `SearchTerm` can include multiple terms to search for, by both partial match and exact match. It can also contain Boolean operators. Using an account ID in a `SearchTerm` works only in accounts that are set up as monitoring accounts for CloudWatch cross-account observability. The syntax for an account ID in `SearchTerm` is `:aws.AccountId = 444455556666`. You can also use `'LOCAL'` to specify the monitoring account itself: `:aws.AccountId = 'LOCAL'` For more information, see [CloudWatch cross-account observability](CloudWatch-Unified-Cross-Account.md). The `SearchTerm` can include one or more designators, such as `MetricName=` as in this example, but using designators isn't required. The metric schema and `SearchTerm` must be enclosed together in a pair of single quote marks. + The `Statistic` is the name of any valid CloudWatch statistic. It must be enclosed by single quotes. For more information, see [Statistics](cloudwatch_concepts.md#Statistic). 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. | Original string | Tokens generated | | --- | --- | | CustomCount1 | `customcount1`, `custom`, `count`, `1` | | SDBFailure | `sdbfailure`, `sdb`, `failure` | | Project2-trial333 | `project2trial333`, `project`, `2`, `trial`, `333` | ## 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: + `count` + `Count` + `COUNT` 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(' \$1MyNamespace\$1, "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(' \$1MyNamespace\$1, "customcount1" ', 'Maximum')** or **SEARCH(' \$1MyNamespace\$1, "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(' \$1AWS/NetworkELB, LoadBalancer\$1 "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 AI, 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\$1\$1France Traffic\$1(Network\$1)"** ## 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('\$1AWS/EC2,InstanceId\$1 network AND packets', 'Average')**. Not using any Boolean operator between search terms implicitly searches them as if there were an `AND` operator, so **SEARCH(' \$1AWS/EC2,InstanceId\$1 network packets ', 'Average')** yields the same search results. Use `NOT` to exclude subsets of data from the results. For example, **SEARCH(' \$1AWS/EC2,InstanceId\$1 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(' \$1AWS/EC2,InstanceId\$1 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(' \$1AWS/Lambda, FunctionName\$1 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) ``` # CloudWatch search expression examples The following examples illustrate more search expression uses and syntax. Let's start with a search for `CPUUtilization` across all instances in the Region and then look at variations. This example displays one line for each instance in the Region, showing the `CPUUtilization` metric from the `AWS/EC2` namespace. ``` SEARCH(' {AWS/EC2,InstanceId} MetricName="CPUUtilization" ', 'Average') ``` Changing `InstanceId` to `InstanceType` changes the graph to show one line for each instance type used in the Region. Data from all instances of each type is aggregated into one line for that instance type. ``` SEARCH(' {AWS/EC2,InstanceType} MetricName="CPUUtilization" ', 'Average') ``` The following example aggregates the `CPUUtilization` by instance type and displays one line for each instance type that includes the string `micro`. ``` SEARCH('{AWS/EC2,InstanceType} InstanceType=micro MetricName="CPUUtilization" ', 'Average') ``` This example narrows the previous example, changing the `InstanceType` to an exact search for t2.micro instances. ``` SEARCH('{AWS/EC2,InstanceType} InstanceType="t2.micro" MetricName="CPUUtilization" ', 'Average') ``` The following search removes the `{metric schema}` part of the query, so the `CPUUtilization` metric from all namespaces appears in the graph. This can return quite a few results because the graph includes multiple lines for the `CPUUtilization` metric from each AWS service, aggregated along different dimensions. ``` SEARCH('MetricName="CPUUtilization" ', 'Average') ``` To narrow these results a bit, you can specify two specific metric namespaces. ``` SEARCH('MetricName="CPUUtilization" AND ("AWS/ECS" OR "AWS/ES") ', 'Average') ``` The preceding example is the only way to do a search of specific multiple namespaces with one search query, as you can specify only one metric schema in each query. However, to add more structure, you could use two queries in the graph, as in the following example. This example also adds more structure by specifying a dimension to use to aggregate the data for Amazon ECS. ``` SEARCH('{AWS/ECS ClusterName}, MetricName="CPUUtilization" ', 'Average') SEARCH(' {AWS/EBS} MetricName="CPUUtilization" ', 'Average') ``` The following example returns the Elastic Load Balancing metric named `ConsumedLCUs` as well as all Elastic Load Balancing metrics or dimensions that contain the token `flow`. ``` SEARCH('{AWS/NetworkELB, LoadBalancer} "ConsumedLCUs" OR flow ', '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') ``` The following example displays all of your custom metrics, excluding metrics generated by AWS services. ``` SEARCH('NOT Namespace=AWS ', 'Average') ``` The following example displays metrics with metric names, namespaces, dimension names, and dimension values that contain the string `Errors` as part of their name. ``` SEARCH('Errors', 'Average') ``` The following example narrows that search to exact matches. For example, this search finds the metric name `Errors` but not metrics named `ConnectionErrors` or `errors`. ``` SEARCH(' "Errors" ', 'Average') ``` The following example shows how to specify names that contain spaces or special characters in the metric schema part of the search term. ``` SEARCH('{"Custom-Namespace", "Dimension Name With Spaces"}, ErrorCount ', 'Maximum') ``` ## CloudWatch cross-account observability search expression examples **CloudWatch cross-account observability examples** If you are signed in to an account that is set up as a monitoring account in CloudWatch cross-account observability, you can use the **SEARCH** function to return metrics from specified source accounts. For more information, see [CloudWatch cross-account observability](CloudWatch-Unified-Cross-Account.md). The following example retrieves all Lambda metrics from the account with the account ID 111122223333. ``` SEARCH(' AWS/Lambda :aws.AccountId = 111122223333 ', 'Average') ``` The following example retrieves all `AWS/EC2` metrics from two accounts: 111122223333 and 777788889999. ``` SEARCH(' AWS/EC2 :aws.AccountId = (111122223333 OR 777788889999) ', 'Average') ``` The following example retrieves all `AWS/EC2` metrics from the source account 111122223333 and from the monitoring account itself. ``` SEARCH(' AWS/EC2 :aws.AccountId = (111122223333 OR 'LOCAL') ', 'Average') ``` The following example retrieves the `SUM` of the `MetaDataToken` metric from the account `444455556666` with the `InstanceId` dimension. ``` SEARCH('{AWS/EC2,InstanceId} :aws.AccountId=444455556666 MetricName=\"MetadataNoToken\"','Sum') ``` # Create a CloudWatch graph with a search expression On the CloudWatch console, you can access search capability when you add a graph to a dashboard, or by using the **Metrics** view. You can't create an alarm based on a **SEARCH** expression. This is because search expressions return multiple time series, and an alarm based on a math expression can watch only one time series. **To add a graph with a search expression to an existing dashboard** 1. Open the CloudWatch console at [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/). 1. In the navigation pane, choose **Dashboards** and select a dashboard. 1. Choose **Add widget**. 1. Choose either **Line** or **Stacked area** and choose **Configure**. 1. On the **Graphed metrics** tab, choose **Add a math expression**. 1. For **Details**, enter the search expression that you want. For example, **SEARCH('\$1AWS/EC2,InstanceId\$1 MetricName="CPUUtilization"', 'Average')** 1. (Optional) To add another search expression or math expression to the graph, choose **Add a math expression** 1. (Optional) After you add a search expression, you can specify a dynamic label to appear on the graph legend for each metric. Dynamic labels display a statistic about the metric and automatically update when the dashboard or graph is refreshed. To add a dynamic label, choose **Graphed metrics** and then **Dynamic labels**. By default, the dynamic values you add to the label appear at the beginning of the label. You can then click the **Label** value for the metric to edit the label. For more information, see [Use dynamic labels](graph-dynamic-labels.md). 1. (Optional) To add a single metric to the graph, choose the **All metrics** tab and drill down to the metric you want. 1. (Optional) To change the time range shown on the graph, choose either **custom** at the top of the graph or one of the time periods to the left of **custom**. 1. (Optional) Horizontal annotations help dashboard users quickly see when a metric has spiked to a certain level or whether the metric is within a predefined range. To add a horizontal annotation, choose **Graph options** and then **Add horizontal annotation**: 1. For **Label**, enter a label for the annotation. 1. For **Value**, enter the metric value where the horizontal annotation appears. 1. For **Fill**, specify whether to use fill shading with this annotation. For example, choose `Above` or `Below` for the corresponding area to be filled. If you specify `Between`, another `Value` field appears, and the area of the graph between the two values is filled. 1. For **Axis**, specify whether the numbers in `Value` refer to the metric associated with the left y-axis or the right y-axis if the graph includes multiple metrics. You can change the fill color of an annotation by choosing the color square in the left column of the annotation. Repeat these steps to add multiple horizontal annotations to the same graph. To hide an annotation, clear the check box in the left column for that annotation. To delete an annotation, choose **x** in the **Actions** column. 1. (Optional) Vertical annotations help you mark milestones in a graph, such as operational events or the beginning and end of a deployment. To add a vertical annotation, choose **Graph options** and then **Add vertical annotation**: 1. For **Label**, enter a label for the annotation. To show only the date and time on the annotation, keep the **Label** field blank. 1. For **Date**, specify the date and time where the vertical annotation appears. 1. For **Fill**, specify whether to use fill shading before or after a vertical annotation or between two vertical annotations. For example, choose `Before` or `After` for the corresponding area to be filled. If you specify `Between`, another `Date` field appears, and the area of the graph between the two values is filled. Repeat these steps to add multiple vertical annotations to the same graph. To hide an annotation, clear the check box in the left column for that annotation. To delete an annotation, choose **x** in the **Actions** column. 1. Choose **Create widget**. 1. Choose **Save dashboard**. **To use the Metrics view to graph searched metrics** 1. Open the CloudWatch console at [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/). 1. In the navigation pane, choose **Metrics**, **All metrics**. 1. In the search field, enter the tokens to search for: for example, **cpuutilization t2.small**. Results that match your search appear. 1. To graph all of the metrics that match your search, choose **Graph search**. or To refine your search, choose one of the namespaces that appeared in your search results. 1. If you selected a namespace to narrow your results, you can do the following: 1. To graph one or more metrics, select the check box next to each metric. To select all metrics, select the check box in the heading row of the table. 1. To refine your search, hover over a metric name and choose **Add to search** or **Search for this only**. 1. To view help for a metric, select the metric name and choose **What is this?**. The selected metrics appear on the graph. 1. (Optional) Select one of the buttons in the search bar to edit that part of the search term. 1. (Optional) To add the graph to a dashboard, choose **Actions** and then **Add to dashboard**.