Componentes de consulta y sintaxis de Metrics Insights

La sintaxis de CloudWatch Metrics Insights se detalla a continuación.

SELECT FUNCTION(metricName)
FROM namespace | SCHEMA(...)
[ WHERE labelKey OPERATOR labelValue [AND ... ] ]
[ GROUP BY labelKey [ , ... ] ]
[ ORDER BY FUNCTION() [ DESC | ASC ] ]
[ LIMIT number ]

Las cláusulas posibles de una consulta de Metrics Insights se detallan a continuación. Ninguna de las palabras clave distingue mayúsculas de minúsculas, al contrario de los identificadores como los nombres de las métricas, los espacios de nombres y las dimensiones.

SELECT

Obligatorio. Especifica la función que se va a utilizar para agregar observaciones en cada bucket de tiempo (determinada por el periodo proporcionado). También especifica el nombre de la métrica que se va a consultar.

Los valores válidos de FUNCTION (FUNCIÓN) son AVG, COUNT, MAX, MIN, y SUM.

• AVG calcula el promedio de las observaciones que coinciden con la consulta.

• COUNT devuelve el recuento de las observaciones que coinciden con la consulta.

• MAX devuelve el valor máximo de las observaciones que coinciden con la consulta.

• MIN devuelve el valor mínimo de las observaciones que coinciden con la consulta.

• SUM calcula la suma de las observaciones que coinciden con la consulta.

FROM

Obligatorio. Especifica el origen de la métrica. Puede especificar el espacio de nombres de métrica que contiene la métrica que se va a consultar o una función de tabla de SCHEMA (ESQUEMA). Algunos ejemplos de espacios de nombres de métrica incluyen "AWS/EC2", "AWS/Lambda" y los espacios de nombres de métricas que usted creó para sus métricas personalizadas.

Los espacios de nombres de métrica que incluyen / o cualquier otro carácter que no sea una letra, un número o un guion bajo debe estar rodeado de comillas dobles. Para obtener más información, consulte ¿Dónde se deben colocar comillas o caracteres de escape?.

SCHEMA

Función de tabla opcional que se puede utilizar dentro de una cláusula de FROM (DESDE). Use SCHEMA (ESQUEMA) para reducir el alcance de los resultados de la consulta solo a las métricas que coinciden exactamente con una lista de dimensiones o métricas que no tienen dimensiones.

Si usa una cláusula de SCHEMA (ESQUEMA), esta debe contener al menos un argumento y este primer argumento debe ser el espacio de nombres de métrica que se consulta. Si especifica el SCHEMA (ESQUEMA) solo con este argumento de espacio de nombres, los resultados se reducen únicamente a métricas que no tienen dimensiones.

Si especifica SCHEMA (ESQUEMA) con argumentos adicionales, los argumentos adicionales posteriores al argumento de espacio de nombres deben ser claves de etiqueta. Las claves de etiqueta deben ser nombres de dimensión. Si especifica una o más de estas claves de etiqueta, los resultados se reducen únicamente a las métricas que tienen ese conjunto exacto de dimensiones. El orden de estas claves de etiqueta no es importante.

Por ejemplo:

• SELECCIONAR AVG(CPUUtilization) DESDE “AWS/EC2” coincide con todas las métricas de CPUUtilization en el espacio de nombres de AWS/EC2, independientemente de sus dimensiones, y devuelve una única serie temporal acumulada.

• SELECCIONAR AVG(CPUUtilization) DESDE ESQUEMA DE (“AWS/EC2”) solo coincide con las métricas de CPUUtilization en el espacio de nombres de AWS/EC2 que no tiene ninguna dimensión definida.

• SELECCIONAR AVG(CPUUtilization) DESDE ESQUEMA DE (“AWS/EC2”, InstanceId) solo coincide con las métricas de CPUUtilization que se notificaron a CloudWatch con exactamente una dimensión, InstanceId.

• SELECCIONAR SUM(RequestCount) DESDE ESQUEMA DE (“AWS/ApplicationELB”, LoadBalancer, AvailabilityZone) solo coincide con las métricas de RequestCount que se han notificado a CloudWatch desde AWS/ApplicationELB con exactamente dos dimensiones, LoadBalancer y AvailabilityZone.

WHERE

Opcional. Filtra los resultados solo a aquellas métricas que coinciden con la expresión especificada mediante valores de etiqueta específicos para una o más claves de etiqueta. Por ejemplo, WHERE InstanceType = 'c3.4xlarge' (DONDE InstanceType = 'c3.4xlarge') filtra los resultados únicamente a los tipos de instancia c3.4xlarge y WHERE InstanceType != 'c3.4xlarge' (DONDE InstanceType != 'c3.4xlarge') filtra los resultados en todos los tipos de instancias, excepto c3.4xlarge.

Cuando ejecute una consulta en una cuenta de supervisión, puede utilizar WHERE AWS.AccountId para limitar los resultados únicamente a la cuenta que especifique. Por ejemplo, las métricas de consulta WHERE AWS.AccountId=444455556666 únicamente de la cuenta 444455556666. Para limitar la consulta solo a las métricas de la propia cuenta de supervisión, utilice WHERE AWS.AccountId=CURRENT_ACCOUNT_ID().

Los valores de etiqueta siempre deben rodearse de comillas simples.

Operadores admitidos

La cláusula WHERE (DONDE) es compatible con los siguientes operadores:

• = El valor de etiqueta debe coincidir con la cadena especificada.

• != El valor de etiqueta no debe coincidir con la cadena especificada.

• AND (Y) Ambas condiciones especificadas deben ser verdaderas para que coincidan. Puede usar varias palabras clave AND (Y) para especificar dos o más condiciones.

GROUP BY

Opcional. Agrupa los resultados de la consulta en varias series temporales y cada una de ellas corresponde a un valor diferente para la clave o claves de etiqueta especificadas. Por ejemplo, si utiliza GROUP BY InstanceId, devuelve una serie temporal diferente para cada valor de InstanceId. El uso de GROUP BY ServiceName, Operation crea una serie temporal diferente para cada combinación posible de los valores de ServiceName y Operation.

Si utiliza la cláusula GROUP BY (AGRUPAR POR), los resultados se ordenan en orden alfabético ascendente de forma predeterminada, a través de la secuencia de etiquetas especificada en la cláusula GROUP BY (AGRUPAR POR). Para cambiar el orden de los resultados, agregue una cláusula ORDER BY (AGRUPAR POR) a su consulta.

Cuando ejecuta una consulta en una cuenta de supervisión, puede utilizar GROUP BY AWS.AccountId para agrupar los resultados en función de las cuentas de las que provienen.

nota

Si algunas de las métricas coincidentes no incluyen una clave de etiqueta especificada en la cláusula GROUP BY (AGRUPAR POR), esto devuelve un grupo nulo denominado Other. Por ejemplo, si especifica GROUP BY ServiceName, Operation y algunas de las métricas devueltas no incluyen ServiceName como dimensión, entonces esas métricas se muestran con el valor Other para ServiceName.

ORDER BY

Opcional. Especifica el orden que se va a utilizar para la serie temporal devuelta, si la consulta devuelve más de una serie temporal. El orden se basa en los valores que encuentra la FUNCTION (FUNCIÓN) que usted especifique en la cláusula ORDER BY (AGRUPAR POR). La FUNCTION (FUNCIÓN) se utiliza para calcular un único valor escalar de cada serie temporal devuelta y ese valor se utiliza para determinar el orden.

También debe especificar si se va a utilizar orden ascendente ASC o descendente DESC. Si omite esto, el valor predeterminado es ascendente ASC.

Por ejemplo, al agregar una cláusula ORDER BY MAX() DESC, los resultados se ordenan según el punto de datos máximo observado dentro del intervalo de tiempo, en orden descendente, lo que significa que la serie temporal que tiene el punto de datos máximo más alto se devuelve primero.

Las funciones válidas que se deben utilizar dentro de una cláusula ORDER BY (AGRUPAR POR) son AVG(), COUNT(), MAX(), MIN(), y SUM().

Si usa una cláusula de AGRUPAR POR con una cláusula de LÍMITE, la consulta resultante será una consulta “Top N”. ORDER BY (AGRUPAR POR) también es útil para consultas que pueden devolver un gran número de métricas porque cada consulta no puede devolver más de 500 series temporales. Si una consulta coincide con más de 500 series temporales y usted utiliza una cláusula de ORDER BY (AGRUPAR POR), las series temporales se ordenan y luego se devuelven las 500 series temporales que aparecen primero en el orden de clasificación.

LIMIT

Opcional. Limita la cantidad de series temporales devueltas según la consulta al valor especificado. El valor máximo que puede especificar es 500 y una consulta que no especifica un LIMIT (LÍMITE) también puede devolver hasta 500 series temporales.

El uso de una cláusula de LÍMITE con una de AGRUPAR POR le proporcionará una consulta “Top N”.

¿Dónde se deben colocar comillas o caracteres de escape?

En una consulta, los valores de etiqueta siempre deben estar rodeados de comillas simples. Por ejemplo, SELECCIONAR MAX(CPUUtilization) DESDE “AWS/EC2” DONDE AutoScalingGroupName = 'my-production-fleet'.

Los espacios de nombres de métrica, los nombres de métricas y las claves de etiqueta que contienen caracteres que no son letras, números y guiones bajos (_) deben estar rodeados de comillas dobles. Por ejemplo, SELECCIONAR MAX(“My.Metric”).

Si uno de ellos contiene comillas dobles o comillas simples en sí (como Bytes"Input"), debe escapar cada comilla con una barra invertida, como en SELECCIONAR AVG(“Bytes\“Input\””).

Si un espacio de nombres de métrica, un nombre de métrica o una clave de etiqueta contienen una palabra que es una palabra clave reservada en Metrics Insights, también debe rodearse de comillas dobles. Por ejemplo, si tiene una métrica denominada LIMIT, utilizaría SELECT AVG("LIMIT"). También es válido incluir cualquier espacio de nombres, nombre de métrica o etiqueta entre comillas dobles, incluso si no contiene una palabra clave reservada.

Para obtener una lista completa de palabras clave reservadas, consulte Palabras clave reservadas.

Crear una consulta enriquecida paso a paso

En esta sección se ilustra la creación de un ejemplo completo en el que se utilizan todas las cláusulas posibles, paso a paso.

Iniciamos con la siguiente consulta, que acumula todas las métricas de RequestCount del Application Load Balancer que se recopilan con ambas dimensiones: LoadBalancer y AvailabilityZone.

SELECT SUM(RequestCount) 
FROM SCHEMA("AWS/ApplicationELB", LoadBalancer, AvailabilityZone)

Ahora, si deseamos ver métricas solo de un balanceador de carga específico, podemos agregar una cláusula WHERE (DONDE) para limitar las métricas devueltas solo a aquellas métricas donde el valor de la dimensión LoadBalancer es app/load-balancer-1.

SELECT SUM(RequestCount) 
FROM SCHEMA("AWS/ApplicationELB", LoadBalancer, AvailabilityZone)
WHERE LoadBalancer = 'app/load-balancer-1'

La consulta mencionada acumula las métricas RequestCount de todas las zonas de disponibilidad para este equilibrador de carga en una serie temporal. Si queremos ver series temporales diferentes para cada zona de disponibilidad, podemos agregar una cláusula GROUP BY (AGRUPAR POR).

SELECT SUM(RequestCount) 
FROM SCHEMA("AWS/ApplicationELB", LoadBalancer, AvailabilityZone)
WHERE LoadBalancer = 'app/load-balancer-1'
GROUP BY AvailabilityZone

A continuación, es posible que deseemos ordenar estos resultados para ver los valores más altos en primer lugar. La siguiente cláusula ORDER BY (AGRUPAR POR) ordena la serie temporal en orden descendente, según el valor máximo notificado por cada serie temporal durante el intervalo de tiempo de consulta:

SELECT SUM(RequestCount) 
FROM SCHEMA("AWS/ApplicationELB", LoadBalancer, AvailabilityZone)
WHERE LoadBalancer = 'app/load-balancer-1'
GROUP BY AvailabilityZone
ORDER BY MAX() DESC

Por último, si nuestro interés principal es un tipo de consulta “Top N”, podemos utilizar una cláusula LÍMITE. Este último ejemplo limita los resultados únicamente a las series temporales con los cinco valores MAX más altos.

SELECT SUM(RequestCount) 
FROM SCHEMA("AWS/ApplicationELB", LoadBalancer, AvailabilityZone)
WHERE LoadBalancer = 'app/load-balancer-1'
GROUP BY AvailabilityZone
ORDER BY MAX() DESC
LIMIT 5

Ejemplos de consultas entre cuentas

Estos ejemplos son válidos cuando se ejecutan en una cuenta configurada como cuenta de supervisión en la observabilidad entre cuentas de CloudWatch.

En el siguiente ejemplo se buscan todas las instancias de Amazon EC2 de la cuenta de origen 123456789012 y se indica un promedio.

SELECT AVG(CpuUtilization) 
FROM "AWS/EC2" 
WHERE AWS.AccountId ='123456789012'

En el siguiente ejemplo, se consulta la métrica de CPUUtilization en AWS/EC2 en todas las cuentas de origen vinculadas y se agrupan los resultados por ID de cuenta y tipo de instancia.

SELECT AVG(CpuUtilization) 
FROM "AWS/EC2" 
GROUP BY AWS.AccountId, InstanceType

En el siguiente ejemplo, se consulta CPUUtilization en la propia cuenta de supervisión.

SELECT AVG(CpuUtilization) 
FROM "AWS/EC2" 
WHERE AWS.AccountId = CURRENT_ACCOUNT_ID()