Sintaxe de expressão de pesquisa do CloudWatch

Uma expressão de pesquisa válida tem o formato a seguir.

SEARCH(' {Namespace, DimensionName1, DimensionName2, ...} SearchTerm', 'Statistic')

Por exemplo:

SEARCH('{AWS/EC2,InstanceId} MetricName="CPUUtilization"', 'Average')

• A primeira parte da consulta depois da palavra SEARCH, entre chaves, é o metric schema (esquema de métrica) a ser pesquisado. O esquema de métrica contém um namespace de métrica e um ou mais nomes de dimensão. A inclusão de um esquema de métrica em uma consulta de pesquisa é opcional. Se especificado, o esquema de métrica deve conter um namespace e pode conter um ou mais nomes de dimensão que são válidos nesse namespace.

  Você não precisa usar aspas dentro do esquema de métrica, a menos que um nome de dimensão ou namespace inclua espaços ou caracteres não alfanuméricos. Nesse caso, você deve colocar o nome que contém esses caracteres entre aspas duplas.

• O SearchTerm também é opcional, mas uma pesquisa válida deve conter o esquema de métrica, o SearchTerm ou ambos. O SearchTerm geralmente contém um ou mais IDs de métrica, nomes de métrica ou valores de dimensão. O SearchTerm pode incluir vários termos para serem pesquisados, tanto por correspondência parcial como por correspondência exata. Ele também pode conter operadores boolianos.

  Usar um ID de conta em um SearchTerm só funciona em contas configuradas como contas de monitoramento para a observabilidade entre contas do CloudWatch. A sintaxe de um ID de conta no SearchTerm é :aws.AccountId = "444455556666". Você também pode usar 'LOCAL' para especificar a própria conta de monitoramento: :aws.AccountId = 'LOCAL'

  Para obter mais informações, consulte Observabilidade entre contas do CloudWatch.

  O SearchTerm pode incluir um ou mais designadores, como MetricName=, conforme este exemplo, mas o uso de designadores não é obrigatório.

  O esquema de métrica e SearchTerm devem estar juntos entre aspas simples.

• O Statistic é o nome de qualquer estatística válida do CloudWatch. Ele deve ser colocado entre aspas simples. Para obter mais informações, consulte Estatísticas.

O exemplo anterior pesquisa o namespace AWS/EC2 para as métricas que têm InstanceId como nome de uma dimensão. Ele retorna todas as métricas CPUUtilization que encontra, com o gráfico exibindo a estatística Average.

Uma expressão de pesquisa pode encontrar somente métricas que relataram dados nas últimas duas semanas.

Limites da expressão de pesquisa

O tamanho máximo da consulta da expressão de pesquisa é de 1024 caracteres. Você pode ter até 100 expressões de pesquisa em um gráfico. Um gráfico pode exibir até 500 séries temporais.

Expressões de pesquisa do CloudWatch: tokenização

Quando você especifica um SearchTerm, a função de pesquisa busca tokens, que são substrings geradas automaticamente pelo CloudWatch de todos os nomes de métrica, nomes de dimensão, valores de dimensão e namespaces. O CloudWatch gera tokens diferenciados pela capitalização camel-case na string original. Os caracteres numéricos também são usados como o início de novos tokens, e os caracteres não alfanuméricos funcionam como delimitadores, criando tokens antes e depois dos caracteres não alfanuméricos.

Uma string contínua do mesmo tipo do caractere delimitador de token resulta em um token.

Todos os tokens são gerados em letras minúsculas. A tabela a seguir mostra alguns exemplos de tokens gerados.

String original	Tokens gerados
CustomCount1	customcount1, custom, count, 1
SDBFailure	sdbfailure, sdb, failure
Project2-trial333	project2trial333, project, 2, trial, 333

Expressões de pesquisa do CloudWatch: correspondências parciais

Quando você especifica um SearchTerm, o termo de pesquisa também é tokenizado. O CloudWatch localiza métricas com base em correspondências parciais, que são correspondências de um único token gerado a partir do termo de pesquisa para um único token gerado a partir de um namespace, nome ou valor da dimensão ou nome da métrica.

As pesquisas de correspondência parcial de um único token não distinguem letras maiúsculas de minúsculas. Por exemplo, o uso de qualquer um dos seguintes termos de pesquisa pode retornar a métrica CustomCount1:

• count

• Count

• COUNT

No entanto, o uso de couNT como um termo de pesquisa não localiza CustomCount1, pois a capitalização no termo de pesquisa couNT é tokenizada em cou e NT.

As pesquisas também podem corresponder a tokens compostos, que são vários tokens que aparecem consecutivamente no nome original. Para corresponder a um token composto, a pesquisa diferencia maiúsculas de minúsculas. Por exemplo, se o termo original for CustomCount1, pesquisas por CustomCount ou Count1 serão bem-sucedidas, mas pesquisas por customcount ou count1 não.

Expressões de pesquisa do CloudWatch: correspondências exatas

Você pode definir uma pesquisa para localizar apenas correspondências exatas do termo de pesquisa usando aspas duplas ao redor da parte do termo de pesquisa que requer uma correspondência exata. Essas aspas duplas são inseridas entre as aspas simples usadas em torno de todo o termo de pesquisa. Por exemplo, SEARCH(' {MyNamespace}, "CustomCount1" ', 'Maximum') localizará a string exata CustomCount1 se ela existir como um nome da métrica, nome ou valor da dimensão no namespace chamado MyNamespace. No entanto, as pesquisas SEARCH(' {MyNamespace}, "customcount1" ', 'Maximum') ou SEARCH(' {MyNamespace}, "Custom" ', 'Maximum') não localizam essa string.

Você pode combinar termos de correspondência parcial e termos de correspondência exata em uma única expressão de pesquisa. Por exemplo, SEARCH(' {AWS/NetworkELB, LoadBalancer} "ConsumedLCUs" OR flow ', 'Maximum') retorna a métrica do Elastic Load Balancing chamada ConsumedLCUs e todas as métricas ou dimensões do Elastic Load Balancing que contenham o token flow.

O uso da correspondência exata também é uma boa maneira de localizar nomes com caracteres especiais, como caracteres não alfanuméricos ou espaços, conforme o exemplo a seguir.

SEARCH(' {"My Namespace", "Dimension@Name"}, "Custom:Name[Special_Characters" ', 'Maximum')

Expressões de pesquisa do CloudWatch: excluir um esquema de métrica

Todos os exemplos mostrados até agora incluem um esquema de métrica entre chaves. As pesquisas que omitem um esquema de métrica também são válidas.

Por exemplo, SEARCH(' "CPUUtilization" ', 'Average') retorna todos os nomes de métrica, nomes de dimensão, valores de dimensão e namespaces que são uma correspondência exata para a string CPUUtilization. Nos namespaces de métrica da AWS, isso pode incluir métricas de vários produtos, incluindo Amazon EC2, Amazon ECS, SageMaker, entre outros.

Para restringir essa pesquisa a apenas um serviço da AWS, a prática recomendada é especificar o namespace e todas as dimensões necessárias no esquema de métrica, como no exemplo a seguir. Embora isso restrinja a pesquisa ao namespace AWS/EC2, ela ainda retornaria resultados de outras métricas se você tivesse definido CPUUtilization como um valor da dimensão para essas métricas.

SEARCH(' {AWS/EC2, InstanceType} "CPUUtilization" ', 'Average')

Como alternativa, você pode adicionar o namespace no SearchTerm como no exemplo a seguir. No entanto, neste exemplo, a pesquisa corresponderia a qualquer string AWS/EC2, mesmo se ela fosse um valor ou nome de dimensão personalizados.

SEARCH(' "AWS/EC2" MetricName="CPUUtilization" ', 'Average')

Expressões de pesquisa do CloudWatch: especificar nomes de propriedade na pesquisa

A pesquisa de correspondência exata por "CustomCount1" a seguir retorna todas as métricas exatamente com esse nome.

SEARCH(' "CustomCount1" ', 'Maximum')

No entanto, ela também retorna métricas com nomes de dimensão, valores de dimensão ou namespaces de CustomCount1. Para estruturar ainda mais sua pesquisa, você pode especificar o nome de propriedade do tipo de objeto que deseja localizar nas pesquisas. O exemplo a seguir pesquisa todos os namespaces e retorna métricas chamadas CustomCount1.

SEARCH(' MetricName="CustomCount1" ', 'Maximum')

Você também pode usar pares nome/valor de dimensão e namespaces como nomes de propriedade, conforme os exemplos a seguir. O primeiro desses exemplos também ilustra que você pode usar nomes de propriedade com pesquisas de correspondência parcial.

SEARCH(' InstanceType=micro ', 'Average')

SEARCH(' InstanceType="t2.micro" Namespace="AWS/EC2" ', 'Average')

Expressões de pesquisa do CloudWatch: caracteres não alfanuméricos

Os caracteres não alfanuméricos servem como delimitadores e marcam onde os nomes de métricas, as dimensões, os namespaces e os termos de pesquisa devem ser separados em tokens. Quando os termos são tokenizados, os caracteres não alfanuméricos são removidos e não aparecem nos tokens. Por exemplo, Network-Errors_2 gera os tokens network, errors, e 2.

O termo de pesquisa pode incluir qualquer caractere não alfanumérico. Se esses caracteres aparecerem no termo de pesquisa, eles poderão especificar tokens compostos em uma correspondência parcial. Por exemplo, todas as pesquisas a seguir localizariam métricas chamadas Network-Errors-2 ou NetworkErrors2.

network/errors
network+errors
network-errors
Network_Errors

Quando você estiver fazendo uma pesquisa de valor exato, qualquer caractere não alfanumérico usado na pesquisa exata deverá ser o caractere correto que aparece na string que está sendo pesquisada. Por exemplo, se você quiser encontrar Network-Errors-2, a pesquisa por "Network-Errors-2" será bem-sucedida, mas uma pesquisa por "Network_Errors_2" não.

Quando você realizar uma pesquisa de correspondência exata, os caracteres a seguir deverão ser recuados com uma barra invertida.

" \ ( )

Por exemplo, para encontrar o nome da métrica Europe\France Traffic(Network) por correspondência exata, use o termo de pesquisa "Europe\\France Traffic\(Network\)"

Expressões de pesquisa do CloudWatch: operadores boolianos

A pesquisa oferece suporte ao uso de operadores boolianos AND, OR e NOT no SearchTerm. Os operadores boolianos são inseridos entre aspas simples usadas ao redor de todo o termo de pesquisa. Os operadores boolianos fazem distinção de maiúsculas e minúsculas, portanto and, or e not não são válidos como operadores boolianos.

Você pode usar o AND explicitamente na pesquisa, como o SEARCH('{AWS/EC2,InstanceId} network AND packets', 'Average'). Não usar nenhum operador booliano entre os termos de pesquisa vai fazer com que eles sejam implicitamente pesquisados como se houvesse um operador do AND, portanto, o SEARCH(' {AWS/EC2,InstanceId} network packets ', 'Average') gera os mesmos resultados de pesquisa.

Use NOT para excluir subconjuntos de dados dos resultados. Por exemplo, o SEARCH(' {AWS/EC2,InstanceId} MetricName="CPUUtilization" NOT i-1234567890123456 ', 'Average') retorna o CPUUtilization para todas as suas instâncias, exceto para a instância do i-1234567890123456. Você também pode usar uma cláusula NOT como o único termo de pesquisa. Por exemplo, o SEARCH( 'NOT Namespace=AWS ', 'Maximum') gera todas as suas métricas personalizadas (métricas com namespaces que não incluem o AWS).

Você pode usar várias expressões NOT em uma consulta. Por exemplo, o SEARCH(' {AWS/EC2,InstanceId} MetricName="CPUUtilization" NOT "ProjectA" NOT "ProjectB" ', 'Average') retorna o CPUUtilization de todas as instâncias na região, exceto para aquelas com valores de dimensão do ProjectA ou do ProjectB.

Você pode combinar operadores boolianos para realizar pesquisas mais eficientes e detalhadas, conforme os exemplos a seguir. Use parênteses para agrupar os operadores.

Os dois exemplos a seguir retornam todos os nomes de métricas que contêm ReadOps de ambos os namespaces do EC2 e do EBS.

SEARCH(' (EC2 OR EBS) AND MetricName=ReadOps ', 'Maximum')

SEARCH(' (EC2 OR EBS) MetricName=ReadOps ', 'Maximum')

O exemplo a seguir restringe a pesquisa anterior a somente os resultados que incluem ProjectA, o que pode ser o valor de uma dimensão.

SEARCH(' (EC2 OR EBS) AND ReadOps AND ProjectA ', 'Maximum')

O exemplo a seguir usa agrupamentos aninhados. Ele retorna métricas do Lambda para Errors de todas as funções, e Invocations de funções com nomes que incluem as strings ProjectA ou ProjectB.

SEARCH(' {AWS/Lambda,FunctionName} MetricName="Errors" OR (MetricName="Invocations" AND (ProjectA OR ProjectB)) ', 'Average')

Expressões de pesquisa do CloudWatch: usar expressões matemáticas

Você pode usar uma expressão de pesquisa dentro de expressões matemáticas em um gráfico.

Por exemplo, SUM(SEARCH(' {AWS/Lambda, FunctionName} MetricName="Errors" ', 'Sum')) retorna a soma da métrica Errors de todas as funções do Lambda.

O uso de linhas separadas para a expressão de pesquisa e a expressão matemática pode gerar resultados mais úteis. Por exemplo, suponha que você use as duas expressões a seguir em um gráfico. A primeira linha exibe linhas Errors separadas para cada uma das funções do Lambda. O ID dessa expressão é e1. A segunda linha adiciona outra linha que mostra a soma dos erros de todas as funções.

SEARCH(' {AWS/Lambda, FunctionName}, MetricName="Errors" ', 'Sum')
SUM(e1)