# Sintaxis de la expresión de búsqueda de CloudWatch
Una expresión de búsqueda válida tiene el siguiente formato.
```
SEARCH(' {Namespace, DimensionName1, DimensionName2, ...} SearchTerm', 'Statistic')
```
Por ejemplo:
```
SEARCH('{AWS/EC2,InstanceId} MetricName="CPUUtilization"', 'Average')
```
+ La primera parte de la consulta detrás de la palabra `SEARCH`, incluida entre llaves, es el *esquema de la métrica* que se va a buscar. El esquema de la métrica contiene un espacio de nombres de métricas y uno o varios nombres de dimensión. La inclusión de un esquema de métrica en una consulta de búsqueda es opcional. Si se especifica, el esquema de la métrica debe contener un espacio de nombres y puede contener uno o varios nombres de dimensión que sean válidos en ese espacio de nombres.
No es necesario utilizar comillas dentro del esquema de la métrica, a menos que un espacio de nombres o un nombre de dimensión incluya espacios o caracteres no alfanuméricos. En tal caso, debe entrecomillar el nombre que contiene los caracteres con comillas dobles.
+ `SearchTerm` también es opcional, pero una búsqueda válida debe contener el esquema de la métrica, `SearchTerm` o ambos. `SearchTerm` contiene normalmente uno o más ID de cuenta, nombres de métrica o valores de dimensión. `SearchTerm` puede incluir varios términos de búsqueda, tanto para coincidencias parciales como exactas. También puede contener operadores booleanos.
El uso de un ID de cuenta en `SearchTerm` solo funciona en las cuentas que estén configuradas como cuentas de supervisión para la observabilidad entre cuentas de CloudWatch. La sintaxis de un ID de cuenta en `SearchTerm` es `:aws.AccountId = 444455556666`. También puede usar `'LOCAL'` para especificar la propia cuenta de supervisión: `:aws.AccountId = 'LOCAL'`
Para obtener más información, consulte [Observabilidad entre cuentas de CloudWatch](CloudWatch-Unified-Cross-Account.md).
`SearchTerm` puede incluir uno o varios indicadores, como `MetricName=` como en este ejemplo, pero el uso de indicadores no es obligatorio.
El esquema de la métrica y `SearchTerm` deben incluirse entre un par de comillas simples.
+ `Statistic` es el nombre de cualquier estadística de CloudWatch válida. Debe ir entre comillas simples. Para obtener más información, consulte [Statistics](cloudwatch_concepts.md#Statistic).
El ejemplo anterior busca el espacio de nombres de `AWS/EC2` para cualquier métrica que tenga `InstanceId` como nombre de dimensión. Devuelve todas las métricas `CPUUtilization` que encuentra y el gráfico muestra la estadística `Average`.
Una expresión de búsqueda solo puede encontrar métricas que hayan registrado datos en las últimas dos semanas.
**Límites de la expresión de búsqueda**
El tamaño máximo de una consulta de expresión de búsqueda es de 1024 caracteres. Puede tener 100 expresiones de búsqueda como máximo en un gráfico. Un gráfico puede mostrar hasta 500 series temporales.
## Expresiones de búsqueda de CloudWatch: tokenización
Cuando especifica un `SearchTerm`, la función de búsqueda busca *tokens*, que son subcadenas que CloudWatch genera automáticamente a partir de los nombres de métricas, los nombres de dimensiones, los valores de las dimensiones y los espacios de nombres completos. CloudWatch genera tokens que se distinguen por la notación camello en la cadena original. Los caracteres numéricos sirven también como inicio de nuevos tokens y los caracteres no alfanuméricos sirven como delimitadores, de manera que los tokens se crean antes y después de los caracteres alfanuméricos.
Una cadena continua del mismo tipo de carácter delimitador de token produce un solo token.
Todos los tokens generados están en minúsculas. En la siguiente tabla se muestran algunos ejemplos de tokens generados.
| Cadena original | Tokens generados |
| --- | --- |
| CustomCount1 | `customcount1`, `custom`, `count`, `1` |
| SDBFailure | `sdbfailure`, `sdb`, `failure` |
| Project2-trial333 | `project2trial333`, `project`, `2`, `trial`, `333` |
## Expresiones de búsqueda de CloudWatch: concordancias parciales
Cuando se especifica un `SearchTerm` , el término de búsqueda también está tokenizado. CloudWatch encuentra métricas en función de las concordancias parciales, que son concordancias de un token único generado de un término de búsqueda con un token único generado a partir de un nombre de métrica, un espacio de nombres, un nombre de dimensión o de un valor de dimensión.
Las búsquedas de coincidencias parciales que buscan un solo token no distinguen entre mayúsculas y minúsculas. Por ejemplo, cualquiera de los siguientes términos de búsqueda puede devolver la métrica `CustomCount1`:
+ `count`
+ `Count`
+ `COUNT`
Sin embargo, si se utiliza `couNT` como un término de búsqueda, no se encuentra `CustomCount1`, ya que el uso de mayúsculas y minúsculas en el término de búsqueda `couNT` se ha tokenizado en `cou` y `NT`.
Las búsquedas también buscan tokens compuestos, que son varios tokens que aparecen de manera consecutiva en el nombre original. Para buscar un token compuesto coincidente, la búsqueda distingue entre mayúsculas y minúsculas. Por ejemplo, si el término original es `CustomCount1`, las búsquedas de `CustomCount` o `Count1` devuelven resultados, pero no así las búsquedas de `customcount` o `count1`.
## Expresiones de búsqueda de CloudWatch: concordancias exactas
Puede definir una búsqueda para que busque solo coincidencias exactas del término de búsqueda utilizando dobles comillas en la parte del término de búsqueda que requiere una coincidencia exacta. Estas comillas dobles se incluyen entre las comillas simples utilizadas alrededor de todo el término de búsqueda. Por ejemplo, **SEARCH(' \$1MyNamespace\$1, "CustomCount1" ', 'Maximum')** encuentra la cadena exacta `CustomCount1` si existe como un nombre de métrica, nombre de dimensión o valor de dimensión en el espacio de nombres denominado `MyNamespace`. Sin embargo, las búsquedas **SEARCH(' \$1MyNamespace\$1, "customcount1" ', 'Maximum')** o **SEARCH(' \$1MyNamespace\$1, "Custom" ', 'Maximum')** no encuentran esta cadena.
Puede combinar términos de coincidencia parcial y términos de coincidencia exacta en la misma expresión de búsqueda. Por ejemplo, **SEARCH(' \$1AWS/NetworkELB, LoadBalancer\$1 "ConsumedLCUs" OR flow ', 'Maximum')** devuelve la métrica Elastic Load Balancing llamada `ConsumedLCUs` además de todas las métricas de Elastic Load Balancing o las dimensiones que contienen el token`flow`.
El uso de coincidencias exactas también es una buena forma de buscar nombres con caracteres especiales, como caracteres no alfanuméricos o espacios, tal y como se muestra en el siguiente ejemplo.
```
SEARCH(' {"My Namespace", "Dimension@Name"}, "Custom:Name[Special_Characters" ', 'Maximum')
```
## Expresiones de búsqueda de CloudWatch: exclusión de un esquema de métrica
Todos los ejemplos mostrados hasta ahora incluyen un esquema de métrica entre llaves. Las búsquedas que omiten un esquema de métrica también son válidas.
Por ejemplo, **SEARCH(' "CPUUtilization" ', 'Average')** devuelve todos los nombres de métrica, nombres de dimensión, valores de dimensión y espacios de nombres que coinciden exactamente con la cadena `CPUUtilization`. En los espacios de nombres de métricas de AWS, se pueden incluir métricas de varios servicios como Amazon EC2, Amazon ECS, SageMaker AI, entre otros.
Para acotar esta búsqueda a un solo servicio de AWS, la práctica recomendada es especificar el espacio de nombres y todas las dimensiones necesarias en el esquema de la métrica, tal y como se muestra en el siguiente ejemplo. Aunque esto acota la búsqueda al espacio de nombres `AWS/EC2`, devolvería igualmente resultados de otras métricas si ha definido `CPUUtilization` como un valor de dimensión para dichas métricas.
```
SEARCH(' {AWS/EC2, InstanceType} "CPUUtilization" ', 'Average')
```
También podría añadir el espacio de nombres al `SearchTerm` tal y como se muestra en el siguiente ejemplo. Sin embargo, en este ejemplo, la búsqueda coincidiría con cualquier cadena `AWS/EC2`, incluso si se tratase de un nombre o valor de dimensión personalizado.
```
SEARCH(' "AWS/EC2" MetricName="CPUUtilization" ', 'Average')
```
## Expresiones de búsqueda de CloudWatch: especificación de los nombres de las propiedades en la búsqueda
La siguiente búsqueda de coincidencia exacta de `"CustomCount1"` devuelve todas las métricas que tienen ese nombre exacto.
```
SEARCH(' "CustomCount1" ', 'Maximum')
```
Pero también devuelve métricas con nombres de dimensión, valores de dimensión o espacios de nombres `CustomCount1`. Para estructurar aún más la búsqueda, puede especificar el nombre de propiedad del tipo de objeto que desea buscar en sus búsquedas. En el siguiente ejemplo, se busca en todos los espacios de nombres y se devuelven las métricas denominadas `CustomCount1`.
```
SEARCH(' MetricName="CustomCount1" ', 'Maximum')
```
También puede utilizar pares de nombre-valor de espacios de nombres y dimensiones como nombres de propiedad, tal y como se muestra en los siguientes ejemplos. El primero de estos ejemplos ilustra que puede utilizar también nombres de propiedad con búsquedas de coincidencia parcial.
```
SEARCH(' InstanceType=micro ', 'Average')
```
```
SEARCH(' InstanceType="t2.micro" Namespace="AWS/EC2" ', 'Average')
```
## Expresiones de búsqueda de CloudWatch: caracteres no alfanuméricos
Los caracteres no alfanuméricos sirven como delimitadores e indican dónde los nombres de métricas, dimensiones, espacios de nombres y términos de búsqueda se dividen en tokens. Cuando los términos están tokenizados, los caracteres no alfanuméricos se eliminan y no aparecen en los tokens. Por ejemplo, `Network-Errors_2` genera los tokens `network`, `errors` y `2`.
El término de búsqueda puede incluir cualquier carácter no alfanumérico. Si estos caracteres aparecen en su término de búsqueda, pueden especificar tokens compuestos en una coincidencia parcial. Por ejemplo, todas las búsquedas siguientes buscarían métricas llamadas `Network-Errors-2` o `NetworkErrors2`.
```
network/errors
network+errors
network-errors
Network_Errors
```
Cuando realiza una búsqueda de un valor exacto, todos los caracteres no alfanuméricos utilizados en la búsqueda exacta deben ser los caracteres correctos que aparecen en la cadena que se busca. Por ejemplo, si desea buscar `Network-Errors-2`, la búsqueda de `"Network-Errors-2"` devuelve resultados, pero no así la búsqueda `"Network_Errors_2"`.
Cuando realiza una búsqueda de coincidencia exacta, los siguientes caracteres deben incluirse entre caracteres de escape con una barra diagonal invertida.
```
" \ ( )
```
Por ejemplo, para buscar una coincidencia exacta del nombre de la métrica `Europe\France Traffic(Network)`, utilice el término de búsqueda **"Europe\$1\$1France Traffic\$1(Network\$1)"**.
## Expresiones de búsqueda de CloudWatch: operadores booleanos
La búsqueda permite el uso de los operadores booleanos `AND`, `OR` y `NOT` dentro del `SearchTerm`. Los operadores booleanos se incluyen entre las comillas simples que utiliza para entrecomillar todo el término de búsqueda. Los operadores booleanos distinguen entre mayúsculas y minúsculas, por lo que `and`, `or` y `not` no son válidos como operadores booleanos.
Puede utilizar `AND` explícitamente en la búsqueda, como **SEARCH('\$1AWS/EC2,InstanceId\$1 network AND packets', 'Average')**. Si no se utilizan operadores booleanos entre los términos de búsqueda, las búsquedas se realizan como si hubiera un operador `AND`, por lo que **SEARCH(' \$1AWS/EC2,InstanceId\$1 network packets ', 'Average')** produce los mismos resultados de búsqueda.
Utilice `NOT` para excluir subconjuntos de datos en los resultados. Por ejemplo, **SEARCH(' \$1AWS/EC2,InstanceId\$1 MetricName="CPUUtilization" NOT i-1234567890123456 ', 'Average')** devuelve la métrica `CPUUtilization` de todas las instancias, excepto de la instancia `i-1234567890123456`. También puede utilizar una cláusula `NOT` como el único término de búsqueda. Por ejemplo, **SEARCH( 'NOT Namespace=AWS ', 'Maximum')** devuelve todas las métricas personalizadas (las métricas con espacios de nombres que no incluyen `AWS`).
Puede utilizar varias frases `NOT` en una consulta. Por ejemplo, **SEARCH(' \$1AWS/EC2,InstanceId\$1 MetricName="CPUUtilization" NOT "ProjectA" NOT "ProjectB" ', 'Average')** devuelve la métrica `CPUUtilization` de todas las instancias de la región, excepto de aquellas con los valores de dimensión `ProjectA` o `ProjectB`.
Puede combinar operadores booleanos para realizar búsquedas más eficaces y detalladas, tal y como se muestra en los siguientes ejemplos. Utilice paréntesis para agrupar los operadores.
Los dos ejemplos siguientes devuelven todos los nombres de métrica que contienen `ReadOps` de los espacios de nombres de EC2 y EBS.
```
SEARCH(' (EC2 OR EBS) AND MetricName=ReadOps ', 'Maximum')
```
```
SEARCH(' (EC2 OR EBS) MetricName=ReadOps ', 'Maximum')
```
El siguiente ejemplo acota la búsqueda anterior a solo los resultados que incluyen `ProjectA`, que podría ser el valor de una dimensión.
```
SEARCH(' (EC2 OR EBS) AND ReadOps AND ProjectA ', 'Maximum')
```
En el ejemplo siguiente se utiliza la agrupación anidada. Devuelve las métricas Lambda para `Errors` de todas las funciones y las `Invocations` de las funciones con nombres que incluyen las cadenas de `ProjectA` o `ProjectB`.
```
SEARCH(' {AWS/Lambda,FunctionName} MetricName="Errors" OR (MetricName="Invocations" AND (ProjectA OR ProjectB)) ', 'Average')
```
## Expresiones de búsqueda de CloudWatch: uso de expresiones matemáticas
Puede utilizar una expresión de búsqueda dentro de una expresión matemática en un gráfico.
Por ejemplo, **SUM(SEARCH(' \$1AWS/Lambda, FunctionName\$1 MetricName="Errors" ', 'Sum'))** devuelve la suma de la métrica `Errors` de todas las funciones de Lambda.
El uso de líneas distintas para la expresión de búsqueda y la expresión matemática podría producir resultados más útiles. Suponga, por ejemplo, que usa las siguientes dos expresiones en un gráfico. La primera línea muestra líneas `Errors` distintas para cada una de las funciones de Lambda. El ID de esta expresión es `e1`. La segunda línea añade otra línea que muestra la suma de los errores de todas las funciones.
```
SEARCH(' {AWS/Lambda, FunctionName}, MetricName="Errors" ', 'Sum')
SUM(e1)
```