Consultar métricas com o PromQL
Tópicos
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. 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) e também para criar alarmes do CloudWatch. Para obter mais informações, consulte Consultas do PromQL e Uso do PromQL em alarmes.
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 |
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, |
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 ( |
Operador de agregação |
Uma função que combina várias séries temporais em menos séries. Os operadores comuns incluem |
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_range) 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_values) 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_range) 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_values) 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_range) 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_values) 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 |
|
ExecuteMetricQueryGet |
|
ExecuteMetricRangeQuery |
|
ExecuteMetricRangeQueryGet |
|
ExecuteMetricSeriesPost |
|
ExecuteMetricSeriesGet |
|
ExecuteMetricLabelsPost |
|
ExecuteMetricLabelsGet |
|
ExecuteMetricLabelValuesGet |
|
