# Consultas do PromQL
<a name="CloudWatch-PromQL-Querying"></a>

Quando você ingere métricas do OpenTelemetry no CloudWatch por meio do OpenTelemetry Protocol (OTLP), 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"` | 
| Reservado pela AWS | N/D | `@aws.` | `@aws.account_id="123456789"` | 

## Consulta a métricas fornecidas pela AWS com o PromQL
<a name="CloudWatch-PromQL-Querying-Vended"></a>

Para poder consultar métricas fornecidas pela AWS no PromQL, você primeiro precisa habilitar o enriquecimento do OTel de métricas fornecidas. Consulte : [Habilitação de métricas fornecidas no PromQL](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"` | Região da AWS de onde essa métrica se originou | `us-east-1` | 
| `"@resource.cloud.account.id"` | ID da conta da AWS 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"` | Tag de recurso da AWS | `production` | 
| `"@aws.account"` | Conta da AWS em que essa métrica foi ingerida (rótulo do sistema) | `123456789012` | 
| `"@aws.region"` | Região da AWS 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:

```
histogram_sum({Invocations, FunctionName="my-api-handler"})
```

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

```
histogram_sum(
  {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"})
```