Composants et syntaxe des requêtes dans CloudWatch Metrics Insights

CloudWatch La syntaxe de Metrics Insights est la suivante.

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

Les clauses possibles dans une requête Metrics Insights sont les suivantes. Aucun des mots-clés n'est sensible à la casse, mais les identificateurs tels que les noms des métriques, des espaces de noms et des dimensions sont sensibles à la casse.

SELECT

Obligatoire. Spécifie la fonction à utiliser pour agréger les observations dans chaque compartiment temporel (déterminé par la période fournie). Spécifie également le nom de la métrique à interroger.

Les valeurs valides pour FUNCTIONsont AVGCOUNT,MAX,MIN, etSUM.

• AVG calcule la moyenne des observations correspondant à la requête.

• COUNT renvoie le nombre d'observations correspondant à la requête.

• MAX renvoie la valeur maximale des observations correspondant à la requête.

• MIN renvoie la valeur minimale des observations correspondant à la requête.

• SUM calcule la somme des observations correspondant à la requête.

FROM

Obligatoire. Spécifie la source de la métrique. Vous pouvez spécifier soit l'espace de noms de métrique contenant la métrique à interroger, soit une SCHEMAfonction de table. Voici des exemples d'espaces de noms de métriques : "AWS/EC2", "AWS/Lambda", et des espaces de noms de métriques que vous avez créés pour vos métriques personnalisées.

Les espaces de noms de métriques qui incluent / ou tout autre caractère qui n'est pas une lettre, un chiffre ou un tiret bas doivent être entourés de guillemets doubles. Pour de plus amples informations, veuillez consulter Qu'est-ce qui nécessite des guillemets ou des caractères d'échappement ?.

SCHEMA

Fonction de table facultative qui peut être utilisée dans une FROMclause. SCHEMAÀ utiliser pour limiter les résultats de la requête aux mesures qui correspondent exactement à une liste de dimensions, ou aux mesures qui n'en ont aucune.

Si vous utilisez une SCHEMAclause, elle doit contenir au moins un argument, et ce premier argument doit être l'espace de noms de la métrique interrogé. Si vous spécifiez uniquement SCHEMAavec cet argument d'espace de noms, les résultats sont limités aux mesures qui n'ont aucune dimension.

Si vous spécifiez SCHEMAavec des arguments supplémentaires, les arguments supplémentaires situés après l'argument d'espace de noms doivent être des clés d'étiquette. Les clés d'étiquette doivent être des noms de dimension. Si vous spécifiez une ou plusieurs de ces clés d'étiquette, les résultats sont limités uniquement aux métriques qui possèdent cet ensemble exact de dimensions. L'ordre de ces clés d'étiquette n'a pas d'importance.

Par exemple :

• SELECTAVG(CPUUtilization) FROM «AWS/EC2» correspond à toutes les CPUUtilization métriques de l'espace de AWS/EC2 noms, quelles que soient leurs dimensions, et renvoie une seule série chronologique agrégée.

• SELECTAVG(CPUUtilization) FROM SCHEMA (»AWS/EC2«) correspond uniquement aux CPUUtilization métriques de l'espace de AWS/EC2 noms dont aucune dimension n'est définie.

• SELECTAVG(CPUUtilization) FROM SCHEMA (»AWS/EC2«, InstanceId) ne correspond qu'aux CPUUtilization métriques signalées CloudWatch avec exactement une dimension,InstanceId.

• SELECTSUM(RequestCount) FROM SCHEMA (» AWS /Application ELB «, LoadBalancer, AvailabilityZone) correspond uniquement aux RequestCount métriques signalées CloudWatch à form AWS/ApplicationELB avec exactement deux dimensions, LoadBalancer etAvailabilityZone.

WHERE

Facultatif. Filtre les résultats en ne retenant que les métriques qui correspondent à l'expression spécifiée à l'aide de valeurs d'étiquette spécifiques pour une ou plusieurs clés d'étiquette. Par exemple, WHERE InstanceType = 'c3.4xlarge' filtre les résultats uniquement pour les types d'c3.4xlargeinstances, et ! WHERE InstanceType = 'c3.4xlarge' filtre les résultats pour tous les types d'instances sauf. c3.4xlarge

Lorsque vous exécutez une requête dans un compte de surveillance, vous pouvez l’utiliser WHERE AWS.AccountId pour limiter les résultats au compte que vous spécifiez. Par exemple, WHERE AWS.AccountId=444455556666 n’interroge les métriques que pour le compte 444455556666. Pour limiter votre requête aux seuls indicateurs du compte de surveillance lui-même, utilisez WHERE AWS.AccountId=CURRENT_ACCOUNT_ID().

Les valeurs des étiquettes doivent toujours être entourées de guillemets simples.

Opérateurs pris en charge

La WHEREclause prend en charge les opérateurs suivants :

• = La valeur de l'étiquette doit correspondre à la chaîne spécifiée.

• != La valeur de l'étiquette ne doit pas correspondre à la chaîne spécifiée.

• ANDLes deux conditions spécifiées doivent être vraies pour correspondre. Vous pouvez utiliser plusieurs ANDmots clés pour définir au moins deux conditions.

GROUPPAR

Facultatif. Regroupe les résultats de la requête en plusieurs séries temporelles, chacune correspondant à une valeur différente pour la ou les clés d'étiquette spécifiées. Par exemple, l'utilisation de GROUP BY InstanceId renvoie une série temporelle différente pour chaque valeur de InstanceId. L'utilisation de GROUP BY ServiceName, Operation crée une série temporelle différente pour chaque combinaison possible des valeurs de ServiceName et Operation.

Avec une clause GROUPBY, les résultats sont classés par défaut par ordre alphabétique croissant, en utilisant la séquence d'étiquettes spécifiée dans la clause GROUPBY. Pour modifier l'ordre des résultats, ajoutez une clause ORDERBY à votre requête.

Lorsque vous exécutez une requête dans un compte de surveillance, vous pouvez l’utiliser GROUP BY AWS.AccountId pour regrouper les résultats en fonction des comptes dont ils proviennent.

Note

Si certaines des métriques correspondantes n'incluent pas de clé d'étiquette spécifique spécifiée dans la clause GROUPBY, un groupe nul nommé Other est renvoyé. Par exemple, si vous spécifiez GROUP BY ServiceName, Operation et que certaines des métriques renvoyées ne comprennent pas ServiceName en tant que dimension, alors ces métriques sont affichées comme ayant Other comme valeur pour ServiceName.

ORDERPAR

Facultatif. Spécifie l'ordre à utiliser pour les séries temporelles renvoyées si la requête renvoie plusieurs séries temporelles. L'ordre est basé sur les valeurs trouvées par celles FUNCTIONque vous spécifiez dans la clause ORDERBY. Le FUNCTIONest utilisé pour calculer une valeur scalaire unique à partir de chaque série chronologique renvoyée, et cette valeur est utilisée pour déterminer l'ordre.

Vous spécifiez également si vous souhaitez utiliser l'ordre croissant ASCou décroissant DESC. Si vous l'omettez, la valeur par défaut est ascendante ASC.

Par exemple, l'ajout d'une clause ORDER BY MAX() DESC classe les résultats en fonction du point de données maximal observé dans la plage temporelle, dans l'ordre décroissant. En d'autres mots, la série temporelle ayant le point de données maximal le plus élevé est renvoyée en premier.

Les fonctions valides à utiliser dans une clause ORDERBY sont AVG()COUNT(),MAX(),MIN(), etSUM().

Si vous utilisez une clause ORDERBY avec une LIMITclause, la requête qui en résulte est une requête « Top N ». ORDERBY est également utile pour les requêtes susceptibles de renvoyer un grand nombre de métriques, car chaque requête ne peut pas renvoyer plus de 500 séries chronologiques. Si une requête correspond à plus de 500 séries chronologiques et que vous utilisez une clause ORDERBY, les séries temporelles sont triées, puis les 500 séries temporelles qui apparaissent en premier dans l'ordre de tri sont celles qui sont renvoyées.

LIMIT

Facultatif. Limite le nombre de séries temporelles renvoyées par la requête à la valeur que vous spécifiez. La valeur maximale que vous pouvez spécifier est 500, et une requête qui ne spécifie pas a ne LIMITpeut pas non plus renvoyer plus de 500 séries chronologiques.

L'utilisation d'une LIMITclause avec une clause ORDERBY vous donne une requête « Top N ».

Qu'est-ce qui nécessite des guillemets ou des caractères d'échappement ?

Dans une requête, les valeurs d'étiquette doivent toujours être entourées de guillemets simples. Par exemple, SELECTMAX(CPUUtilization) FROM "AWS/EC2" WHERE AutoScalingGroupName = 'my-production-fleet'.

Les espaces de noms de métriques, les noms de métriques et les clés d'étiquette contenant des caractères autres que des lettres, des chiffres et des tirets bas (_) doivent être entourés de guillemets doubles. Par exemple, SELECTMAX(« My.Metric »).

Si l'un d'entre eux contient lui-même un guillemet double ou un guillemet simple (par exempleBytes"Input"), vous devez éviter chaque guillemet par une barre oblique inverse, comme dans SELECTAVG(« Bytes \" Input \ "»).

Si un espace de noms de métrique, un nom de métrique ou une clé d'étiquette contient un mot qui est un mot-clé réservé dans Metrics Insights, ceux-ci doivent également être entre guillemets doubles. Par exemple, si vous disposez d'une métrique nommée LIMIT, vous devez utiliser SELECT AVG("LIMIT"). Il est également valable de placer n'importe quel espace de noms, nom de métrique ou étiquette entre guillemets doubles, même s'il n'inclut pas de mot-clé réservé.

Pour obtenir la liste complète des mots-clés réservés, consultez Mots-clés réservés.

Créer une requête riche étape par étape

Cette section illustre la création d'un exemple complet qui utilise toutes les clauses possibles, étape par étape.

Nous démarrons par la requête suivante, qui rassemble l'ensemble des métriques RequestCount de l'Application Load Balancer qui sont collectées avec les deux dimensions LoadBalancer et AvailabilityZone.

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

Désormais, si nous voulons voir uniquement les métriques provenant d'un équilibreur de charge spécifique, nous pouvons ajouter une WHEREclause pour limiter les métriques renvoyées uniquement aux métriques dont la valeur de la LoadBalancer dimension se situeapp/load-balancer-1.

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

La requête précédente agrège les métriques RequestCount de toutes les zones de disponibilité de cet équilibreur de charge en une seule série temporelle. Si nous voulons voir des séries temporelles différentes pour chaque zone de disponibilité, nous pouvons ajouter une clause GROUPBY.

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

Ensuite, nous pourrions vouloir classer ces résultats pour voir d'abord les valeurs les plus élevées. La clause ORDERBY suivante classe les séries chronologiques par ordre décroissant, en fonction de la valeur maximale indiquée par chaque série chronologique pendant la période de requête :

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

Enfin, si nous sommes principalement intéressés par une requête de type « Top N », nous pouvons utiliser une LIMITclause. Cet exemple final limite les résultats aux séries temporelles avec les cinq valeurs MAX les plus élevées.

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

Exemple de requête entre comptes

Ces exemples sont valides lorsqu'ils sont exécutés dans un compte configuré en tant que compte de surveillance dans le cadre de l' CloudWatch observabilité entre comptes.

L'exemple suivant recherche toutes les EC2 instances Amazon du compte source 123456789012 et renvoie la moyenne.

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

L’exemple suivant interroge la métrique CPUUtilization dans AWS/EC2 pour tous les comptes source liés et regroupe les résultats par ID de compte et type d’instance.

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

L’exemple suivant interroge le CPUUtilization dans le compte de surveillance lui-même.

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