# Consultar métricas com o PromQL **Topics** + [O que é o Prometheus Query Language (PromQL)?](#CloudWatch-PromQL-WhatIs) + [Limites e restrições do PromQL](#CloudWatch-PromQL-Limits) + [Regiões do AWS compatíveis](#CloudWatch-PromQL-Regions) + [Permissões do IAM para o PromQL](#CloudWatch-PromQL-IAM) + [Consultas do PromQL](CloudWatch-PromQL-Querying.md) + [Execução de consultas do PromQL no Query Studio (versão de pré-visualização)](CloudWatch-PromQL-QueryStudio.md) + [Uso do PromQL em alarmes](CloudWatch-PromQL-Alarms.md) **nota** A ingestão de métricas do OTLP, a consulta do PromQL, o enriquecimento de métricas fornecidas pela AWS do OTel e o Query Studio estão em versão de pré-visualização pública, são gratuitos e estão sujeitos a alterações. ## O que é o Prometheus Query Language (PromQL)? O Prometheus Query Language (PromQL) é uma linguagem de consulta funcional que permite selecionar, agregar e transformar dados de séries temporais em tempo real. O PromQL foi originalmente projetado para o Prometheus e tornou-se uma linguagem de consulta popular para métricas. O Amazon CloudWatch é compatível com o PromQL para consultar métricas, incluindo métricas ingeridas por meio do OpenTelemetry Line Protocol (OTLP) e [métricas enriquecidas fornecidas pela AWS](https://docs.aws.amazon.com//AmazonCloudWatch/latest/monitoring/aws-services-cloudwatch-metrics.html). Quando você ingere métricas do OTLP, o CloudWatch preserva a estrutura semântica completa da sua telemetria, incluindo atributos de recursos, escopo de instrumentação, atributos de ponto de dados e metadados específicos da AWS, e os expõe como rótulos consultáveis do PromQL . Com o PromQL, você pode fazer o seguinte: + Selecione séries temporais por nome de métrica e correspondências de rótulos. + Aplique funções e operadores matemáticos em séries temporais. + Agregue métricas em todas as dimensões, como serviço, região ou conta. + Calcule taxas, histogramas, quantis e médias móveis. Você pode usar consultas do PromQL de forma interativa em [Execução de consultas do PromQL no Query Studio (versão de pré-visualização)](CloudWatch-PromQL-QueryStudio.md) e também para criar alarmes do CloudWatch. Para obter mais informações, consulte [Consultas do PromQL](CloudWatch-PromQL-Querying.md) e [Uso do PromQL em alarmes](CloudWatch-PromQL-Alarms.md). **nota** O CloudWatch usa o PromQL com base na especificação do Prometheus 3.0. Isso inclui suporte para nomes de métricas UTF-8 e nomes de rótulos. Os conceitos a seguir são fundamentais para trabalhar com o PromQL no CloudWatch. | Conceito | Descrição | | --- | --- | | **Séries temporais** | Um fluxo de valores com carimbo de data e hora identificados por um nome de métrica e um conjunto de pares de chave/valor denominados *rótulos*. Cada combinação exclusiva de nome e rótulos de métricas forma uma série temporal distinta. | | **Vetor instantâneo** | Um conjunto de séries temporais que contém uma única amostra para cada série, todas compartilhando o mesmo carimbo de data e hora. Retornado por consultas como `{"http.server.active_requests", "@resource.service.name"="myservice"}`. | | **Vetor de intervalo** | Um conjunto de séries temporais contendo um intervalo de pontos de dados ao longo do tempo para cada série. Criado anexando um seletor de duração de tempo entre colchetes, por exemplo, `avg_over_time({"http.server.active_requests", "@resource.service.name"="myservice"}[5m])`. | | **Rótulo** | Um par de chave/valor anexado a uma série temporal. Nas métricas ingeridas pelo OTLP, os rótulos são derivados dos atributos do recurso, do escopo da instrumentação, dos atributos do ponto de dados e dos metadados específicos da AWS. | | **Correspondência de rótulos** | Uma expressão delimitada por chaves que filtra as séries temporais pelo valor do rótulo. Compatível com correspondência exata (`=`), não igual (`!=`), correspondência regex (`=~`) e correspondência regex negativa (`!~`). | | **Operador de agregação** | Uma função que combina várias séries temporais em menos séries. Os operadores comuns incluem `sum`, `avg`, `min`, `max`, `count` e `topk`. | ## Limites e restrições do PromQL A seguinte tabela lista os limites e as restrições para o PromQL: | Limite | Valor | Mais informações | Código de erro | | --- | --- | --- | --- | | TPS máximo para solicitações de consulta por conta | 300 | Número máximo de solicitações de consulta (/query, /query\$1range) por segundo permitido por conta. | 422 | | TPS máximo para solicitações de descoberta por conta | 10 | Número máximo de solicitações de descoberta (/series, /label, /label\$1values) por segundo permitido por conta. | 422 | | Máximo de solicitações de consulta simultâneas por conta | 30 | Número máximo de consultas (/query, /query\$1range) que uma conta pode ter executando ativamente ao mesmo tempo. | 429 | | O máximo de solicitações de descoberta simultâneas por conta | 30 | Número máximo de solicitações de descoberta (/series, /labels, /label\$1values) que uma conta pode ter executando ativamente ao mesmo tempo. | 429 | | Número máximo de séries retornadas por solicitação de consulta | 500 | Número máximo de séries temporais exclusivas que uma solicitação de consulta (/query, /query\$1range) pode retornar. | 200: resposta truncada | | Máximo de rótulos retornados por solicitação de descoberta | 10.000 | Número máximo de rótulos exclusivos que uma solicitação de descoberta (/series, /labels, /label\$1values) pode retornar. | 200: resposta truncada | | Intervalo máximo por solicitação | 7 dias | Intervalo de tempo máximo que uma consulta pode abranger, incluindo parâmetros de intervalo e períodos de lookback. | 422 | | Máximo de séries a serem verificadas por janela de 24 horas | 100.000 | Número máximo de séries temporais únicas que podem ser verificadas por janela de 24 horas de execução de consulta. | 422 | | Máximo de amostras verificadas por janela de 24 horas | 300.000.000 | Número máximo de amostras que podem ser verificadas por janela de 24 horas de execução de consulta. | 422 | | Máximo de amostras processadas por janela de 24 horas | 3.000.000.000 | Número máximo de amostras que podem ser processadas por janela de 24 horas de execução de consulta. | 422 | | Execution timeout (Tempo limite de execução) | 20 segundos | Tempo máximo que o mecanismo pode gastar avaliando uma consulta, excluindo o tempo gasto na fila e buscando dados do armazenamento. | 422 | ## Regiões do AWS compatíveis A tabela a seguir lista as regiões da AWS em que a ingestão de métricas do OTLP, a consulta do PromQL e o Query Studio estão disponíveis. | Nome da região | Código da região | Métricas de ingestão do OTLP | Consulta do PromQL | Query Studio | | --- | --- | --- | --- | --- | | Leste dos EUA (Norte da Virgínia) | us-east-1 | ✓ | ✓ | ✓ | | Oeste dos EUA (Oregon) | us-west-2 | ✓ | ✓ | ✓ | | Europa (Irlanda) | eu-west-1 | ✓ | ✓ | ✓ | | Ásia-Pacífico (Singapura) | ap-southeast-1 | ✓ | ✓ | ✓ | | Ásia-Pacífico (Sydney) | ap-southeast-2 | ✓ | ✓ | ✓ | ## Permissões do IAM para o PromQL Para executar consultas do PromQL, você precisa de ambas as permissões `cloudwatch:GetMetricData` e `cloudwatch:ListMetrics`. A tabela a seguir lista as novas operações da API do PromQL e suas ações necessárias do IAM: | Operação de API | Ações necessárias | | --- | --- | | ExecuteMetricQueryPost | `cloudwatch:GetMetricData`, `cloudwatch:ListMetrics` | | ExecuteMetricQueryGet | `cloudwatch:GetMetricData`, `cloudwatch:ListMetrics` | | ExecuteMetricRangeQuery | `cloudwatch:GetMetricData`, `cloudwatch:ListMetrics` | | ExecuteMetricRangeQueryGet | `cloudwatch:GetMetricData`, `cloudwatch:ListMetrics` | | ExecuteMetricSeriesPost | `cloudwatch:ListMetrics` | | ExecuteMetricSeriesGet | `cloudwatch:ListMetrics` | | ExecuteMetricLabelsPost | `cloudwatch:ListMetrics` | | ExecuteMetricLabelsGet | `cloudwatch:ListMetrics` | | ExecuteMetricLabelValuesGet | `cloudwatch:ListMetrics` |