Componentes e sintaxe de consulta do Metrics Insights

A sintaxe do CloudWatch Metrics Insights é a seguinte.

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

As cláusulas possíveis em uma consulta do Metrics Insights são as seguintes. Nenhuma das palavras-chave diferencia maiúsculas de minúsculas, mas os identificadores como os nomes de métricas, namespaces e dimensões sim.

SELECT

Obrigatório. Especifica a função a ser usada para agregar observações em cada bucket de tempo (determinado pelo período fornecido). Também especifica o nome da métrica a ser consultada.

Os valores válidos para FUNCTION são AVG, COUNT, MAX, MIN e SUM.

• AVG calcula a média das observações correspondidas pela consulta.

• COUNT retorna a contagem das observações correspondidas pela consulta.

• MAX retorna o valor máximo das observações correspondidas pela consulta.

• MIN retorna o valor mínimo das observações correspondidas pela consulta.

• SUM calcula a soma das observações correspondidas pela consulta.

FROM

Obrigatório. Especifica a fonte da métrica. Você pode especificar o namespace da métrica que contém a métrica a ser consultada ou uma função de tabela SCHEMA. Exemplos de namespaces de métrica incluem "AWS/EC2", "AWS/Lambda" e namespaces de métrica criados para suas métricas personalizadas.

Namespaces de métrica que incluem / ou qualquer outro caractere que não seja letra, número ou sublinhado devem ser cercados por aspas duplas. Para ter mais informações, consulte Quando é necessário usar aspas ou caracteres de escape?.

SCHEMA

Uma função de tabela opcional que pode ser usada dentro de uma cláusula FROM. Use SCHEMA para reduzir o escopo dos resultados da consulta apenas para as métricas que correspondem exatamente a uma lista de dimensões ou para métricas que não têm dimensões.

Se você usar uma cláusula SCHEMA, ela deve conter pelo menos um argumento, e o primeiro deles deve ser o namespace de métrica que está sendo consultado. Se você especificar SCHEMA só com o argumento de namespace, os resultados são reduzidos para somente as métricas que não têm dimensões.

Se você especificar SCHEMA com argumentos adicionais, os argumentos adicionais após o argumento de namespace devem ser chaves de rótulo. As chaves de rótulo devem ser nomes de dimensão. Se você especificar uma ou mais chaves de rótulo, os resultados serão definidos apenas para as métricas que têm esse conjunto exato de dimensões. A ordem das chaves de rótulo não tem importância.

Por exemplo:

• SELECT AVG(CPUUtilization) FROM "AWS/EC2" corresponde a todas as métricas CPUUtilization do namespace AWS/EC2, independentemente de suas dimensões, e retorna uma única série temporal agregada.

• SELECT AVG(CPUUtilization) FROM SCHEMA("AWS/EC2") corresponde apenas às métricas de CPUUtilization no namespace AWS/EC2 que não têm nenhuma dimensão definida.

• SELECT AVG(CPUUtilization) FROM SCHEMA("AWS/EC2", InstanceId) corresponde apenas às métricas CPUUtilization que foram relatadas ao CloudWatch com exatamente uma dimensão, InstanceId.

• SELECT SUM(RequestCount) FROM SCHEMA("AWS/ApplicationELB", LoadBalancer, AvailabilityZone) corresponde apenas às métricas RequestCount que foram relatadas ao CloudWatch pelo AWS/ApplicationELB com exatamente duas dimensões, LoadBalancer e AvailabilityZone.

WHERE

Opcional. Filtra os resultados apenas para as métricas que correspondem à expressão especificada usando valores de rótulo específicos para uma ou mais chaves de rótulo. Por exemplo, WHERE InstanceType = 'c3.4xlarge' filtra os resultados somente para os tipos de instância c3.4xlarge, e WHERE InstanceType != 'c3.4xlarge' filtra os resultados para todos os tipos de instância, exceto c3.4xlarge.

Ao executar uma consulta em uma conta de monitoramento, você pode usar WHERE AWS.AccountId para limitar os resultados somente à conta que você especificar. Por exemplo, WHERE AWS.AccountId=444455556666 só consulta métricas da conta 444455556666. Para limitar sua consulta somente a métricas na própria conta de monitoramento, use WHERE AWS.AccountId=CURRENT_ACCOUNT_ID().

Os valores do rótulo devem sempre ser incluídos com aspas simples.

Operadores compatíveis

A cláusula WHERE é compatível com os seguintes operadores:

• = O valor do rótulo deve corresponder à string especificada.

• ! = O valor do rótulo não deve ser correspondente à string especificada.

• AND Ambas as condições especificadas devem ser verdadeiras para serem correspondentes. Você pode usar várias palavras-chave AND para especificar duas ou mais condições.

GROUP BY

Opcional. Agrupa os resultados da consulta em várias séries temporais, cada uma correspondendo a um valor diferente para a chave de rótulo ou chaves especificadas. Por exemplo, o uso de GROUP BY InstanceId retorna uma série temporal diferente para cada valor de InstanceId. O uso do GROUP BY ServiceName, Operation cria uma série temporal diferente para cada combinação possível de valores de ServiceName e Operation.

Com uma cláusula GROUP BY, os resultados são ordenados alfabeticamente em ordem crescente por padrão usando a sequência de rótulos especificada na cláusula GROUP BY. Para alterar a ordem dos resultados, adicione uma cláusula ORDER BY à sua consulta.

Ao executar uma consulta em uma conta de monitoramento, você pode usar GROUP BY AWS.AccountId para agrupar os resultados com base nas contas das quais eles se originam.

nota

Se algumas das métricas correspondentes não especificarem uma chave de rótulo específica na cláusula GROUP BY, é retornado um grupo nulo denominado Other. Por exemplo, se você especificar GROUP BY ServiceName, Operation e algumas das métricas retornadas não incluem ServiceName como uma dimensão, essas métricas são exibidas com Other como o valor para ServiceName.

ORDER BY

Opcional. Especifica a ordem a ser usada para a série temporal retornada, se a consulta retornar mais de uma série temporal. A ordem é baseada nos valores encontrados pela FUNCTION que você especifica na cláusula ORDER BY. A FUNCTION é usada para calcular um único valor escalar de cada série temporal retornada, e esse valor é usado para determinar a ordem.

Você também especifica se deve-se usar a ordem crescente ASC ou decrescente DESC. Se você omitir isso, o padrão será crescente ASC.

Por exemplo, adicionar uma cláusula ORDER BY MAX() DESC ordena os resultados pelo ponto de dados máximo observado dentro do intervalo de tempo em ordem decrescente: o que significa que a série temporal que tem o ponto de dados máximo mais alto é retornada primeiro.

As funções válidas para serem usadas em uma cláusula ORDER BY são AVG(), COUNT(), MAX(), MIN() e SUM().

Se você usar uma cláusula ORDER BY com uma cláusula LIMIT, a consulta resultante é uma consulta “Top N”. ORDER BY também é útil para consultas que podem retornar um grande número de métricas, porque cada consulta não pode retornar mais de 500 séries temporais. Se uma consulta corresponder a mais de 500 séries temporais e você usar uma cláusula ORDER BY, as séries temporais são classificadas e, em seguida, as 500 que aparecem primeiro na ordem de classificação são as que são retornadas.

LIMIT

Opcional. Limita o número de séries temporais retornadas pela consulta ao valor que você especificar. O valor máximo que você pode especificar é 500, e uma consulta que não especifica um LIMIT também pode retornar até 500 séries temporais.

O uso de uma cláusula LIMIT com uma cláusula ORDER BY fornece uma consulta “Top N”.

Quando é necessário usar aspas ou caracteres de escape?

Em uma consulta, os valores de rótulo devem sempre estar cercados por aspas simples. Por exemplo, SELECT MAX(CPUUtilization) FROM "AWS/EC2" WHERE AutoScalingGroupName = 'my-production-fleet'.

Namespaces de métricas, nomes de métricas e chaves de rótulo que contenham caracteres diferentes de letras, números e sublinhado (_) devem ser cercados por aspas duplas. Por exemplo, SELECT MAX("My.Metric").

Se um deles contiver aspas duplas ou aspas simples (como Bytes"Input"), você deve fazer o escape de cada aspa com uma barra invertida, como em SELECT AVG("Bytes\"Input\"").

Se um namespace de métrica, nome da métrica ou chave de rótulo contiver uma palavra que seja palavra-chave reservada no Metrics Insights, eles também deverão estar entre aspas duplas. Por exemplo, se você tiver uma métrica chamada LIMIT, você pode usar SELECT AVG("LIMIT"). Também é válido colocar qualquer namespace, nome da métrica ou rótulo entre aspas duplas, mesmo que não inclua uma palavra-chave reservada.

(Para obter uma lista completa de palavras-chave reservadas, consulte Palavras-chave reservadas.

Construir uma consulta avançada passo a passo

Esta seção ilustra a criação de um exemplo completo que usa todas as cláusulas possíveis, passo a passo.

Começamos com a seguinte consulta, que agrega todas as métricas RequestCount do Application Load Balancer coletadas com ambas as dimensões LoadBalancer e AvailabilityZone.

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

Agora, se quisermos ver métricas somente de um balanceador de carga específico, podemos adicionar uma cláusula WHERE para limitar as métricas retornadas somente para aquelas em que o valor da dimensão LoadBalancer é app/load-balancer-1.

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

A consulta anterior agrega as métricas RequestCount de todas as zonas de disponibilidade para esse balanceador de carga em uma série temporal. Se quisermos ver séries temporais diferentes para cada zona de disponibilidade, podemos adicionar uma cláusula GROUP BY.

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

Em seguida, podemos querer ordenar esses resultados para ver os valores mais altos primeiro. A seguinte cláusula ORDER BY ordena a série temporal em ordem decrescente pelo valor máximo relatado por cada série temporal durante o intervalo de tempo da consulta:

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

Finalmente, se estivermos interessados principalmente em um tipo de consulta "Top N", podemos usar uma cláusula LIMIT. Este exemplo final limita os resultados apenas às séries temporais com os cinco maiores valores MAX.

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

Exemplos de consultas entre contas

Esses exemplos são válidos quando executados em uma conta configurada como conta de monitoramento na observabilidade entre contas do CloudWatch.

O exemplo a seguir pesquisa todas as instâncias do Amazon EC2 na conta de origem 123456789012 e retorna a média.

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

O exemplo a seguir consulta a métrica CPUUtilization no AWS/EC2 em todas as contas de origem vinculadas e agrupa os resultados por ID da conta e tipo de instância.

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

O exemplo a seguir consulta a CPUUtilization na própria conta de monitoramento.

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