Consultas do PromQL

Quando você ingere métricas do OpenTelemetry no CloudWatch por meio do Endpoint de métricas, o modelo hierárquico de dados do OTLP é nivelado em rótulos compatíveis com o PromQL. Esta seção descreve a estrutura do rótulo, a sintaxe do PromQL para consultar esses rótulos e a compatibilidade com UTF-8 no PromQL.

Ao usar o PromQL no CloudWatch, a convenção de prefixo @ distingue os rótulos com escopo do OTLP dos rótulos padrão do Prometheus. Os campos dentro de cada escopo usam um prefixo @ duplo (por exemplo,@resource.@schema_url), enquanto os atributos usam um prefixo @ de escopo único, por exemplo, @resource.service.name. Os atributos do ponto de dados também são compatíveis com acesso direto (sem prefixo) para compatibilidade retroativa com consultas padrão do PromQL, por exemplo, {"http.server.active_requests"} e {"@datapoint.@name"="http.server.active_requests"} são equivalentes.

Uma expressão do PromQL está delimitada por chaves, especificando o nome da métrica e um conjunto de correspondências de rótulos. O seguinte exemplo seleciona todas as séries temporais para a métrica http.server.active_requests:

{"http.server.active_requests"}

O seguinte exemplo seleciona todas as séries temporais para a métrica http.server.active_requests em que o atributo do recurso do OpenTelemetry service.name é igual a myservice:

{"http.server.active_requests", "@resource.service.name"="myservice"}

Você pode combinar várias correspondências de rótulos em uma única consulta. O exemplo a seguir seleciona todas as séries temporais da métrica http.server.active_requests em que o atributo do recurso do OpenTelemetry service.name é igual a myservice em todas as regiões dos EUA:

{"http.server.active_requests",
 "@resource.service.name"="myservice",
 "@aws.region"=~"us-.*"}

O exemplo a seguir mostra uma consulta de intervalo. Ele calcula o valor médio de todos os pontos de dados dentro de um intervalo de tempo especificado para cada série temporal:

avg_over_time(
  {"http.server.active_requests",
   "@resource.service.name"="myservice"}[5m]
)

A seguinte tabela resume as convenções de prefixo para cada escopo do OTLP:

Consulta a métricas fornecidas pela AWS com o PromQL

Para poder consultar métricas fornecidas pela AWS no PromQL, você primeiro precisa habilitar o enriquecimento do OTel de métricas fornecidas. Consulte : Métricas fornecidas pela AWS no formato do OpenTelemetry.

Depois de habilitar o enriquecimento do OTel, as métricas fornecidas pela AWS podem ser consultadas por meio do PromQL com rótulos adicionais. O nome da métrica é igual ao nome da métrica original do CloudWatch, e as dimensões originais do CloudWatch estão disponíveis como atributos do ponto de dados. Os seguintes rótulos estão disponíveis (o exemplo abaixo é para uma instância do EC2):

O exemplo a seguir seleciona Invocations para uma função específica do Lambda:

{Invocations, FunctionName="my-api-handler"}

O seguinte exemplo seleciona Errors do Lambda para todas as funções marcadas com uma equipe específica:

{Errors, "@instrumentation.@name"="cloudwatch.aws/lambda", "@aws.tag.Team"="backend"}

O seguinte exemplo calcula o total de Invocations do Lambda agrupado por equipe:

sum by ("@aws.tag.Team")(
    {Invocations, "@instrumentation.@name"="cloudwatch.aws/lambda"}
)

O seguinte exemplo seleciona todas as séries temporais para a métrica CPUUtilization do EC2. O uso de "@instrumentation.@name"="cloudwatch.aws/ec2" é para corresponder exclusivamente à CPUUtilization do EC2 e não de outros serviços da AWS, como o Amazon Relational Database Service:

histogram_avg({CPUUtilization, "@instrumentation.@name"="cloudwatch.aws/ec2"})

Como consultar na Grafana

Você pode consultar dados do CloudWatch ProMQL da Grafana adicionando o plug-in de fonte de dados do Amazon Managed Service for Prometheus e apontando-o para o endpoint de monitoramento do CloudWatch. A assinatura SigV4 é incorporada ao plug-in e está sempre ativada, portanto, não há nenhuma opção para ativá-la. O plug-in é publicado em grafana.com/grafana/plugins/grafana-amazonprometheus-datasource/; instale-o a partir do catálogo de plug-ins da Grafana antes de adicionar a fonte de dados. O plugin AMP v3.0.0 requer a Grafana >=11.6.11 <12 || >=12.0.10 <12.1 || >=12.1.7 <12.2 || >=12.2.5.

Pré-requisitos do IAM: a entidade principal do IAM cujas credenciais a Grafana usa deve ter tanto cloudwatch:GetMetricData (obrigatório para consultas instantâneas e de intervalo) quanto cloudwatch:ListMetrics (necessário para descoberta de séries e rótulos). Para obter detalhes, consulte Permissões do IAM para o PromQL.

Para configurar a Grafana, siga as etapas a seguir.

Como consultar no Amazon Managed Grafana

É possível consultar dados do CloudWatch PromQL de um espaço de trabalho Amazon Managed Grafana adicionando uma fonte de dados do Amazon Managed Service for Prometheus que aponta para o endpoint de monitoramento do CloudWatch. Esse plug-in de fonte de dados assina solicitações com o SigV4 usando o perfil do IAM do espaço de trabalho automaticamente; o SigV4 está sempre ativado, sem nenhuma opção para configurar. O plug-in está disponível no Amazon Managed Grafana versão 12 e posterior. Para ober mais informações, consulte Conecte-se a uma fonte de dados do Amazon Managed Service for Prometheus no Guia do usuário do Amazon Managed Grafana.

Pré-requisitos do IAM: o perfil do IAM do espaço de trabalho do Amazon Managed Grafana deve ter tanto cloudwatch:GetMetricData (necessária para consultas instantâneas e de alcance) quanto cloudwatch:ListMetrics (necessária para descoberta de séries e rótulos). Para obter detalhes, consulte Permissões do IAM para o PromQL.

Para configurar a fonte de dados, siga as etapas a seguir.

Como consultar com ferramentas do MCP

O servidor MCP do CloudWatch fornece ferramentas do protocolo de contexto para modelos (MCP) que permitem que assistentes de IA e ferramentas de desenvolvimento consultem dados do CloudWatch ProMQL em seu nome. As ferramentas MCP lidam com a autenticação e a formatação de solicitações automaticamente, para que você possa se concentrar em escrever consultas ProMQL em vez de gerenciar solicitações HTTP e assinaturas SigV4.

As seguintes ferramentas do ProMQL estão disponíveis no servidor MCP do CloudWatch:

Para detalhes completos sobre parâmetros, configuração e instruções de configuração, consulte Tools for CloudWatch ProMQL na documentação do servidor MCP do CloudWatch.

Como consultar com a API HTTP

Você também pode consultar dados do CloudWatch ProMQL programaticamente chamando diretamente os endpoints HTTP compatíveis com o Prometheus. As solicitações devem ser assinadas com o AWS Signature Version 4 usando monitoring como nome do serviço.

O endpoint do PromQL segue o padrão https://monitoring.AWS Region.amazonaws.com/api/v1/operation. Por exemplo, para a região Leste dos EUA (Norte da Virgínia) (us-east-1), o endpoint para uma consulta instantânea é https://monitoring.us-east-1.amazonaws.com/api/v1/query.

Para obter a referência completa da API, incluindo operações suportadas, parâmetros de solicitação e formatos de resposta, consulte APIs compatíveis com o Prometheus. Para ver a lista de regiões da AWS em que a consulta PromQL está disponível, consulte Regiões do AWS compatíveis. Para as ações do IAM necessárias para cada operação, consulte Permissões do IAM para o PromQL.