# Consultas do PromQL
Quando você ingere métricas do OpenTelemetry no CloudWatch por meio do [Endpoint de métricas](CloudWatch-OTLPEndpoint.md#CloudWatch-MetricsEndpoint), 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.
**nota**
O PromQL no Prometheus 3 é compatível com caracteres UTF-8 completos em nomes de métricas e nomes de rótulos. Isso é particularmente importante para métricas do OTLP, porque as convenções semânticas do OpenTelemetry usam pontos em nomes de atributos, como `service.name`. Anteriormente, esses pontos eram substituídos por sublinhados durante a conversão, causando discrepâncias entre o que era definido nas convenções do OTel e o que era consultável no Prometheus.
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:
| Escopo do OTLP | Prefixo de campos | Prefixo de atributos | Exemplo |
| --- | --- | --- | --- |
| Recurso | `@resource.@` | `@resource.` | `@resource.service.name="myservice"` |
| Escopo da instrumentação | `@instrumentation.@` | `@instrumentation.` | `@instrumentation.@name="otel-go/metrics"` |
| Pontos de dados | `@datapoint.@` | `@datapoint.` ou direto | `cpu="cpu0"` ou `@datapoint.cpu="cpu0"` |
| AWSReservado pela | N/D | `@aws.` | `@aws.account_id="123456789"` |
## 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](CloudWatch-OTelEnrichment.md).
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):
| Rótulo do PromQL | Descrição | Exemplo |
| --- | --- | --- |
| `InstanceId` | Dimensão original do CloudWatch, como atributo de ponto de dados | `i-0123456789abcdef0` |
| `"@resource.cloud.resource_id"` | ARN completo do recurso | `arn:aws:ec2:us-east-1:123456789012:instance/i-0123456789abcdef0` |
| `"@resource.cloud.provider"` | Provedor de nuvem | `aws` |
| `"@resource.cloud.region"` | AWSRegião da de onde essa métrica se originou | `us-east-1` |
| `"@resource.cloud.account.id"` | AWSID da conta da de onde essa métrica se originou | `123456789012` |
| `"@instrumentation.@name"` | Nome do escopo da instrumentação identificando o serviço de origem | `cloudwatch.aws/ec2` |
| `"@instrumentation.cloudwatch.source"` | Identificador do serviço de origem | `aws.ec2` |
| `"@instrumentation.cloudwatch.solution"` | Identificador da solução de enriquecimento | `CloudWatchOTelEnrichment` |
| `"@aws.tag.Environment"` | AWSTag de recurso da | `production` |
| `"@aws.account"` | AWSConta da em que essa métrica foi ingerida (rótulo do sistema) | `123456789012` |
| `"@aws.region"` | AWSRegião da em que essa métrica foi ingerida (rótulo do sistema) | `us-east-1` |
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/](https://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](CloudWatch-PromQL.md#CloudWatch-PromQL-IAM).
Para configurar a Grafana, siga as etapas a seguir.
1. Instale o plug-in de fonte de dados do **Amazon Managed Service for Prometheus** a partir do catálogo de plug-ins da Grafana.
1. Na Grafana, acesse **Conexões**, **Fontes de dados**, escolha **Adicionar fonte de dados** e selecione **Amazon Managed Service for Prometheus**.
1. Defina o **URL** da fonte de dados como `https://monitoring.{{AWS Region}}.amazonaws.com`.
1. Defina a **Região** como sua região da AWS. Escolha um **provedor de autenticação** apropriado para seu ambiente (cadeia de credenciais padrão, chaves de acesso ou perfil do IAM do espaço de trabalho).
1. Escolha **Salvar e testar**.
## 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](https://docs.aws.amazon.com/grafana/latest/userguide/amazon-prometheus-data-source.html) 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](CloudWatch-PromQL.md#CloudWatch-PromQL-IAM).
Para configurar a fonte de dados, siga as etapas a seguir.
1. Em seu espaço de trabalho do Amazon Managed Grafana, adicione uma como fonte de dados do **Amazon Managed Service for Prometheus**.
1. Defina o **URL** da fonte de dados como `https://monitoring.{{AWS Region}}.amazonaws.com`.
1. Defina a **Região** como sua região da AWS. O Amazon Managed Grafana injeta credenciais do perfil do IAM do espaço de trabalho automaticamente; você não precisa configurar chaves estáticas.
1. Escolha **Salvar e testar**.
## Como consultar com ferramentas do MCP
O [servidor MCP do CloudWatch](https://awslabs.github.io/mcp/servers/cloudwatch-mcp-server/) 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:
| Ferramenta | Descrição |
| --- | --- |
| `execute_promql_query` | Executa uma consulta PromQL instantânea, retornando valores métricos em um único momento. |
| `execute_promql_range_query` | Executa uma consulta de intervalo do ProMQL em uma janela de tempo, retornando dados de séries temporais para análise de tendências e gráficos. |
| `get_promql_label_values` | Recupera valores para um rótulo específico do PromQL, como `__name__` para nomes de métricas ou `@resource.service.name` para serviços. |
| `get_promql_series` | Encontra séries temporais correspondentes aos seletores de rótulos do PromQL e retorna o conjunto completo de rótulos de cada série correspondente. |
| `get_promql_labels` | Lista todos os nomes de rótulos do PromQL disponíveis para ajudar a descobrir a estrutura de rótulos de suas métricas. |
Para detalhes completos sobre parâmetros, configuração e instruções de configuração, consulte [Tools for CloudWatch ProMQL](https://awslabs.github.io/mcp/servers/cloudwatch-mcp-server#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](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html) 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](CloudWatch-PromQL-APIs.md). Para ver a lista de regiões da AWS em que a consulta PromQL está disponível, consulte [Regiões do AWS compatíveis](CloudWatch-PromQL.md#CloudWatch-PromQL-Regions). Para as ações do IAM necessárias para cada operação, consulte [Permissões do IAM para o PromQL](CloudWatch-PromQL.md#CloudWatch-PromQL-IAM).