Abfragekomponenten und -syntax in CloudWatch Metrics Insights - Amazon CloudWatch
Was braucht Anführungszeichen oder Escape-Zeichen?Eine umfangreiche Abfrage erstellen, Schritt für SchrittBeispiele kontoübergreifender Abfragen

Abfragekomponenten und -syntax in CloudWatch Metrics Insights

Die Syntax von CloudWatch Metrics Insights lautet wie folgt.

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

Die möglichen Klauseln in einer Metrics-Insights-Abfrage lauten wie folgt. Bei keinem der Schlüsselwörter wird Groß- und Kleinschreibung berücksichtigt, aber bei den Bezeichnern wie den Namen von Metriken, Namespaces und Dimensionen wird Groß- und Kleinschreibung beachtet.

SELECT

Erforderlich Gibt die Funktion an, die zum Aggregieren von Beobachtungen in jedem Zeit-Bucket verwendet werden soll (durch den angegebenen Zeitraum festgelegt). Gibt auch den Namen der abzufragenden Metrik an.

Die gültigen Werte für FUNCTION sind AVG, COUNT, MAX, MIN und SUM.

  • AAVG berechnet den Durchschnitt der Beobachtungen, die mit der Abfrage übereinstimmen.

  • COUNT gibt die Anzahl der Beobachtungen zurück, die mit der Abfrage übereinstimmen.

  • MAX gibt den Maximalwert der Beobachtungen zurück, die mit der Abfrage übereinstimmen.

  • MIN gibt den Minimalwert der Beobachtungen zurück, die mit der Abfrage übereinstimmen.

  • SUM berechnet die Summe der Beobachtungen, die mit der Abfrage übereinstimmen.

FROM

Erforderlich Gibt die Quelle der Metrik an. Sie können entweder den Metrik-Namespace angeben, der die abzufragende Metrik enthält, oder eine SCHEMA-Tabellenfunktion. Beispiele für Metrik-Namespaces sind "AWS/EC2", "AWS/Lambda" und Metrik-Namespaces, die Sie für Ihre benutzerdefinierten Metriken erstellt haben.

Metrik-Namespaces, die / enthalten oder jedes andere Zeichen, das kein Buchstabe, keine Zahl und kein Unterstrich ist, müssen von doppelten Anführungszeichen umgeben sein. Weitere Informationen finden Sie unter Was braucht Anführungszeichen oder Escape-Zeichen?.

SCHEMA

Eine optionale Tabellenfunktion, die innerhalb einer FROM-Klausel verwendet werden kann. Verwenden Sie SCHEMA, um die Abfrageergebnisse nur auf die Metriken zu reduzieren, die genau mit einer Liste von Dimensionen übereinstimmen, oder auf Metriken, die keine Dimensionen haben.

Wenn Sie eine SCHEMA-Klausel verwenden, muss diese mindestens ein Argument enthalten. Das erste Argument muss der Metrik-Namespace sein, der abgefragt wird. Wenn Sie SCHEMA nur mit diesem Namespace-Argument angeben, werden die Ergebnisse nur auf Metriken beschränkt, die keine Dimensionen haben.

Wenn Sie SCHEMA mit zusätzlichen Argumenten angeben, müssen die zusätzlichen Argumente nach dem Namespace-Argument Bezeichnungsschlüssel sein. Bezeichnungsschlüssel müssen Dimensionsnamen sein. Wenn Sie einen oder mehrere dieser Bezeichnungsschlüssel angeben, werden die Ergebnisse nur auf die Metriken beschränkt, die genau diesen Dimensionssatz aufweisen. Die Reihenfolge dieser Bezeichnungsschlüssel spielt dabei keine Rolle.

Zum Beispiel:

  • SELECT AVG(CPUUtilization) FROM "AWS/EC2" entspricht allen CPUUtilization-Metriken im AWS/EC2-Namespace, unabhängig von ihren Dimensionen, und gibt eine einzelne aggregierte Zeitreihe zurück.

  • SELECT AVG(CPUUtilization) FROM SCHEMA("AWS/EC2") entspricht nur den CPUUtilization-Metriken im AWS/EC2-Namespace, für die keine Dimensionen definiert sind.

  • SELECT AVG(CPUUtilization) FROM SCHEMA("AWS/EC2", InstanceId) entspricht nur den CPUUtilization-Metriken, die CloudWatch mit genau einer Dimension (InstanceId) gemeldet wurden.

  • SELECT SUM(RequestCount) FROM SCHEMA("AWS/ApplicationELB", LoadBalancer, AvailabilityZone) entspricht nur den RequestCount-Metriken, die CloudWatch von AWS/ApplicationELB mit genau zwei Dimensionen (LoadBalancer und AvailabilityZone) gemeldet wurden.

WHERE

Optional. Filtert die Ergebnisse nur nach den Metriken, die mit dem angegebenen Ausdruck übereinstimmen, wobei bestimmte Bezeichnungswerte für einen oder mehrere Bezeichnungsschlüssel verwendet werden. Beispiel: WHERE instanceType = 'c3.4xlarge' filtert die Ergebnisse nur auf c3.4xlarge-Instance-Typen und WHERE InstanceType! = 'c3.4xlarge' filtert die Ergebnisse auf alle Instance-Typen außer c3.4xlarge.

Wenn Sie eine Abfrage in einem Überwachungskonto ausführen, können Sie WHERE AWS.AccountId verwenden, um die Ergebnisse auf das von Ihnen angegebene Konto zu beschränken. WHERE AWS.AccountId=444455556666 fragt beispielsweise nur Metriken von Konto 444455556666 ab. Um Ihre Abfrage nur auf Metriken im Überwachungskonto selbst zu beschränken, verwenden Sie WHERE AWS.AccountId=CURRENT_ACCOUNT_ID().

Bezeichnungswerte müssen immer mit einfachen Anführungszeichen eingeschlossen sein.

Verwenden von Tags in WHERE-Klauseln

Mithilfe der Syntax tag.keyName können Sie Ergebnisse nach AWS-Ressourcen-Tags filtern. Tag-Filter folgen denselben Operatorregeln wie Dimensionsfilter. Zum Beispiel:

  • WHERE tag.env = 'prod' filtert nach Metriken aus Ressourcen, die mit env=prod markiert sind

  • WHERE tag.department != 'test' schließt Metriken aus Ressourcen aus, die mit department=test markiert sind

Tag-Filter können mit Dimensionsfiltern kombiniert werden:

WHERE tag.env = 'prod' AND InstanceType = 'm5.large'

Unterstützte Operatoren

Die WHERE-Klausel unterstützt die folgenden Operatoren:

  • = Der Bezeichnungswert muss mit der angegebenen Zeichenfolge übereinstimmen.

  • != Der Bezeichnungswert muss nicht mit der angegebenen Zeichenfolge übereinstimmen.

  • AND Beide angegebenen Bedingungen müssen zutreffend sein, damit sie übereinstimmen. Sie können mehrere AND-Schlüsselwörter verwenden, um zwei oder mehr Bedingungen anzugeben.

GROUP BY

Optional. Gruppiert die Abfrageergebnisse in mehrere Zeitreihen, die jeweils einem anderen Wert für den angegebenen Bezeichnungsschlüssel oder die angegebenen Schlüssel entsprechen. Beispielsweise gibt GROUP BY InstanceId für jeden Wert eine andere Zeitreihe für jeden Wert von InstanceId zurück. Bei Verwendung von GROUP BY ServiceName, Operation wird eine andere Zeitreihe für jede mögliche Kombination der Werte von ServiceName und Operation erstellt.

Mit der Klausel GROUP BY werden die Ergebnisse standardmäßig in alphabetischer aufsteigender Reihenfolge angeordnet, wobei die in der Klausel GROUP BY angegebenen Bezeichnungssequenzen verwendet werden. Fügen Sie die Klausel ORDER BY zu Ihrer Anfrage hinzu, um die Reihenfolge der Ergebnisse zu ändern.

Wenn Sie eine Abfrage in einem Überwachungskonto ausführen, können Sie GROUP BY AWS.AccountId verwenden, um die Ergebnisse anhand der Konten zu gruppieren, von denen sie stammen.

Verwenden von Tags in GROUP BY-Klauseln

Mithilfe der Syntax tag.keyName können Sie Ergebnisse nach AWS-Ressourcen-Tag-Werten filtern. Zum Beispiel:

  • GROUP BY tag.environment erstellt separate Zeitreihen für jeden Umgebungs-Tag-Wert

  • GROUP BY tag.team, instanceType gruppiert nach Tag- und nach Dimensionswerten

  • GROUP BY tag.team, AWS.AccountId gruppiert nach Tag und nach verknüpften Quell-AccountIDs

Anmerkung

Wenn einige der übereinstimmenden Metriken keinen bestimmten Bezeichnungsschlüssel enthalten, der in der Klausel GROUP BY angegeben ist, wird eine Nullgruppe mit dem Namen Other zurückgegeben. Wenn Sie beispielsweise GROUP BY ServiceName, Operation angeben und einige der zurückgegebenen Metriken ServiceName nicht als Dimension enthalten, werden diese Metriken so angezeigt, als hätten sie Other als Wert für ServiceName.

ORDER BY

Optional. Gibt die Reihenfolge an, die für die zurückgegebene Zeitreihe verwendet werden soll, wenn die Abfrage mehr als eine Zeitreihe zurückgibt. Die Reihenfolge basiert auf den Werten, die von der FUNCTION gefunden werden, die Sie in der Klausel ORDER BY angegeben haben. Die FUNCTION wird verwendet, um einen einzelnen Skalarwert aus jeder zurückgegebenen Zeitreihe zu berechnen. Dieser Wert wird verwendet, um die Reihenfolge zu bestimmen.

Sie geben auch an, ob aufsteigend (ASC) oder absteigend (DESC) verwendet werden soll. Wenn Sie dies auslassen, ist die Standardeinstellung aufsteigend (ASC).

Fügen Sie zum Beispiel die Klausel ORDER BY MAX() DESC hinzu, werden die Ergebnisse nach dem maximalen Datenpunkt in absteigender Reihenfolge sortiert, der innerhalb des Zeitraums beobachtet wird. Das bedeutet, dass die Zeitreihe mit dem höchsten maximalen Datenpunkt zuerst zurückgegeben wird.

Die gültigen Funktionen, die innerhalb der Klausel ORDER BY verwendet werden, lauten AVG(), COUNT(), MAX(), MIN() und SUM().

Wenn Sie die Klausel ORDER BY mit der Klausel LIMIT verwenden, ist die resultierende Abfrage eine „Top N“-Abfrage. ORDER BY ist auch nützlich für Abfragen, die möglicherweise eine große Anzahl von Metriken zurückgeben, da keine Abfrage mehr als 500 Zeitreihen zurückgeben kann. Wenn eine Abfrage mehr als 500 Zeitreihen entspricht und Sie die Klausel ORDER BY verwenden, werden die Zeitreihen sortiert und die 500 Zeitreihen, die in der Sortierreihenfolge zuerst stehen, werden zurückgegeben.

LIMIT

Optional. Beschränkt die Anzahl der von der Abfrage zurückgegebenen Zeitreihen auf den von Ihnen angegebenen Wert. Der Maximalwert, den Sie angeben können, ist 500, und eine Abfrage, die kein LIMIT angibt, kann ebenfalls maximal 500 Zeitreihen zurückgeben.

Wenn Sie die Klausel LIMIT mit der Klausel ORDER BY verwenden, erhalten Sie eine „Top N“-Abfrage.

Was braucht Anführungszeichen oder Escape-Zeichen?

In einer Abfrage müssen Bezeichnungswerte immer mit einfachen Anführungszeichen eingeschlossen sein. Beispiel: SELECT MAX(CPUUtilization) FROM "AWS/EC2" WHERE AutoScalingGroupName = 'my-production-fleet'.

Metrik-Namespaces, Metriknamen und Bezeichnungsschlüssel, die andere Zeichen als Buchstaben, Zahlen und Unterstriche (_) enthalten, müssen mit doppelten Anführungszeichen eingeschlossen sein. Beispiel: SELECT MAX("My.Metric").

Wenn eine dieser Abfragen ein doppeltes Anführungszeichen oder ein einzelnes Anführungszeichen enthält (z. B. Bytes"Input"), muss jedem Anführungszeichen ein umgekehrter Schrägstrich vorangestellt werden, siehe SELECT AVG("Bytes\"Input\"").

Wenn ein Metrik-Namespace, ein Metrikname oder ein Bezeichnungsschlüssel ein Wort enthält, das ein reserviertes Schlüsselwort in Metrics Insights ist, muss dieses auch in doppelten Anführungszeichen eingeschlossen sein. Wenn Sie beispielsweise eine Metrik mit dem Namen LIMIT haben, würden Sie SELECT AVG("LIMIT") benutzen. Es ist auch möglich, einen Namespace, einen Metriknamen oder eine Bezeichnung in doppelte Anführungszeichen einzuschließen, auch wenn kein reserviertes Schlüsselwort enthalten ist.

Eine vollständige Liste der reservierten Wörter finden Sie unter Reservierte Schlüsselwörter.

Eine umfangreiche Abfrage erstellen, Schritt für Schritt

Dieser Abschnitt veranschaulicht das Erstellen eines vollständigen Beispiels, das Schritt für Schritt alle möglichen Klauseln verwendet.

Sie können mit der folgenden Abfrage beginnen, die alle RequestCount-Metriken im Application Load Balancer aggregiert, die mit den beiden Dimensionen LoadBalancer und AvailabilityZone erfasst werden.

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

Wenn Sie nur Metriken von einem bestimmten Load Balancer sehen möchten, können Sie die Klausel WHERE hinzufügen, um die zurückgegebenen Werte auf Metriken zu beschränken, bei denen der Wert der LoadBalancer-Dimension app/load-balancer-1 ist.

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

Die vorhergehende Abfrage aggregiert die RequestCount-Metriken aus allen Availability Zones für diesen Load Balancer in eine Zeitreihe. Wenn Sie verschiedene Zeitreihen für jede Availability Zone sehen möchten, können wir die Klausel GROUP BY hinzufügen.

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

Als Nächstes können Sie die Ergebnisse so anordnen, dass zuerst die höchsten Werte angezeigt werden. Die folgende ORDER BY-Klausel ordnet die Zeitreihe in absteigender Reihenfolge um den Maximalwert an, den jede Zeitreihe während des Abfragezeitraums gemeldet hat:

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

Sie können auch Tags verwenden, um die Ergebnisse weiter zu filtern. Wenn Sie beispielsweise nur Ergebnisse für Load Balancer sehen möchten, die mit einer bestimmten Umgebung markiert sind, können wir der WHERE-Klausel eine Tag-Filterung hinzufügen:

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

Sie können die Ergebnisse auch nach Tag-Werten gruppieren – anstelle von oder zusätzlich zu Dimensionen. Beispielgruppierung nach dem Anwendungs-Tag:

SELECT SUM(RequestCount) FROM SCHEMA("AWS/ApplicationELB", LoadBalancer, AvailabilityZone) WHERE tag.Environment = 'prod' GROUP BY tag.Application ORDER BY MAX() DESC

Wenn wir in erster Linie an einer „Top N“-Abfrage interessiert sind, können wir eine LIMIT-Klausel verwenden. Dieses letzte Beispiel beschränkt die Ergebnisse auf die Zeitreihe mit den fünf höchsten MAX-Werten.

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

Beispiele kontoübergreifender Abfragen

Diese Beispiele sind gültig, wenn sie in einem Konto ausgeführt werden, das als Überwachungskonto in der kontoübergreifenden Beobachtbarkeit von CloudWatch eingerichtet ist.

Im folgenden Beispiel werden alle Amazon-EC2-Instances im Quellkonto 123456789012 durchsucht und der Durchschnitt zurückgegeben.

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

Im folgenden Beispiel wird die CPUUtilization-Metrik in AWS/EC2 in allen verknüpften Quellkonten abgefragt und die Ergebnisse nach Konto-ID und Instance-Typ gruppiert.

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

Im folgenden Beispiel wird die CPUUtilization im Überwachungskonto selbst abgefragt.

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