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 monitoreo 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 monitoreo: :aws.AccountId = 'LOCAL'

  Para obtener más información, consulte Observabilidad entre cuentas de CloudWatch.

  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.

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(' {MyNamespace}, "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(' {MyNamespace}, "customcount1" ', 'Maximum') o SEARCH(' {MyNamespace}, "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(' {AWS/NetworkELB, LoadBalancer} "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 tokenflow.

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 incluidos Amazon EC2, Amazon ECS, SageMaker, 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\\France Traffic\(Network\)".

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('{AWS/EC2,InstanceId} 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(' {AWS/EC2,InstanceId} network packets ', 'Average') produce los mismos resultados de búsqueda.

Utilice NOT para excluir subconjuntos de datos en los resultados. Por ejemplo, SEARCH(' {AWS/EC2,InstanceId} 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(' {AWS/EC2,InstanceId} 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(' {AWS/Lambda, FunctionName} 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)