Composants et syntaxe des requêtes dans CloudWatch Metrics Insights - Amazon CloudWatch
Qu'est-ce qui nécessite des guillemets ou des caractères d'échappement ?Créer une requête riche étape par étapeExemple de requête entre comptes

Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

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 intervalle de temps (déterminé par la période fournie). Spécifie également le nom de la métrique à interroger.

Les valeurs valides pour FUNCTION (FONCTION) sont AVG, COUNT, MAX, MIN et SUM.

  • 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 qui contient la métrique à interroger, soit une fonction de table SCHEMA (SCHÉMA). 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, consultez Qu'est-ce qui nécessite des guillemets ou des caractères d'échappement ?.

SCHEMA (SCHÉMA)

Une fonction de table facultative pouvant être utilisée dans une clause FROM (À PARTIR DE). Utilisez SCHEMA (SCHÉMA) pour réduire les résultats de la requête aux métriques qui correspondent parfaitement à une liste de dimensions, ou aux métriques qui n'ont pas de dimensions.

Si vous utilisez une clause SCHEMA (SCHÉMA), elle doit contenir au moins un argument, et ce premier argument doit être l'espace de noms de la métrique interrogée. Si vous spécifiez SCHEMA (SCHÉMA) avec cet argument d'espace de noms uniquement, les résultats sont limités à des métriques qui n'ont aucune dimension.

Si vous spécifiez SCHEMA (SCHÉMA) avec des arguments supplémentaires, les arguments supplémentaires 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 :

  • SELECT AVG (CPUUtilization) FROM « AWS/ EC2 » fait correspondre 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.

  • SELECT AVG (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.

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

  • SELECT SUM (RequestCount) FROM SCHEMA (« AWS/ApplicationElb » LoadBalancer,, AvailabilityZone) correspond uniquement aux RequestCount métriques signalées à CloudWatch from AWS/ApplicationELB avec exactement deux dimensions, et. LoadBalancer AvailabilityZone

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 clause WHERE (OÙ) 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.

  • AND (ET) Les deux conditions spécifiées doivent être vraies pour correspondre. Vous pouvez utiliser plusieurs mots-clés AND (ET) afin de spécifier deux conditions ou plus.

GROUP BY

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 GROUP BY (REGROUPER PAR), les résultats sont classés par ordre alphabétique croissant par défaut, en utilisant la séquence d'étiquettes spécifiée dans la clause GROUP BY (REGROUPER PAR). Pour modifier l'ordre des résultats, ajoutez une clause ORDER BY (CLASSER PAR) à 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 GROUP BY (REGROUPER PAR), 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.

ORDER BY

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 la clause FUNCTION (FONCTION) que vous spécifiez dans la clause ORDER BY (CLASSER PAR). La clause FUNCTION (FONCTION) est utilisée pour calculer une valeur scalaire unique à partir de chaque série temporelle renvoyée, et cette valeur est utilisée pour déterminer l'ordre.

Vous spécifiez également s'il faut utiliser l'ordre croissant ASC ou décroissant DESC. Si vous l'omettez, la valeur par défaut est croissante, 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 ORDER BY (CLASSER PAR) sont AVG(), COUNT(), MAX(), MIN() et SUM().

Si vous utilisez une clause ORDER BY (CLASSER PAR) avec une clause LIMIT (LIMITE), la requête résultante est une requête « Top N ». ORDER BY (CLASSER PAR) est également utile pour les requêtes qui peuvent renvoyer un grand nombre de métriques, car chaque requête ne peut pas renvoyer plus de 500 séries temporelles. Si une requête correspond à plus de 500 séries temporelles et que vous utilisez une clause ORDER BY (CLASSER PAR), les séries temporelles sont triées, puis les 500 séries temporelles qui arrivent 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 de LIMIT (LIMITE) ne peut pas non plus renvoyer plus de 500 séries temporelles.

L'utilisation d'une clause LIMIT (LIMITE) avec une clause ORDER BY (CLASSER PAR) 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, SELECT MAX (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, SELECT MAX("My.Metric").

Si l'un d'entre eux contient un guillemet double ou un guillemet simple lui-même (par exemple : Bytes"Input"), vous devez séparer chaque guillemet par une barre oblique inverse, comme dans SELECT AVG("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 les métriques uniquement à partir d'un équilibreur de charge spécifique, nous pouvons ajouter une clause WHERE (OÙ) pour limiter les métriques renvoyées en ne retenant que les métriques pour lesquelles la valeur de la dimension LoadBalancer est app/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 différentes séries temporelles pour chaque zone de disponibilité, nous pouvons ajouter une clause GROUP BY (REGROUPER PAR).

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 ORDER BY (CLASSER PAR) suivante classe les séries temporelles par ordre décroissant, en fonction de la valeur maximale signalée par chaque série temporelle 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 avant tout intéressés par un type de requête « Top N », nous pouvons utiliser une clause LIMIT (LIMITE). 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()