

# Consulta de métricas con PromQL

**Topics**
+ [¿Qué es el lenguaje de consultas Prometheus (PromQL)?](#CloudWatch-PromQL-WhatIs)
+ [Límites y restricciones de PromQL](#CloudWatch-PromQL-Limits)
+ [Regiones de AWS compatibles](#CloudWatch-PromQL-Regions)
+ [Permisos de IAM para PromQL](#CloudWatch-PromQL-IAM)
+ [Consultas PromQL](CloudWatch-PromQL-Querying.md)
+ [Ejecución de consultas PromQL en Query Studio](CloudWatch-PromQL-QueryStudio.md)
+ [Uso de PromQL en las alarmas](CloudWatch-PromQL-Alarms.md)
+ [API compatibles con Prometheus](CloudWatch-PromQL-APIs.md)

## ¿Qué es el lenguaje de consultas Prometheus (PromQL)?
<a name="CloudWatch-PromQL-WhatIs"></a>

El lenguaje de consultas Prometheus (PromQL) es un lenguaje de consulta funcional que permite seleccionar, agregar y transformar datos de series temporales en tiempo real. PromQL se diseñó originalmente para Prometheus y se ha convertido en un popular lenguaje de consulta de métricas.

Amazon CloudWatch es compatible con PromQL para consultar métricas, incluidas las métricas ingeridas a través de OpenTelemetry Line Protocol (OTLP) y las [métricas suministradas por AWS enriquecidas](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/aws-services-cloudwatch-metrics.html). Cuando incorpora métricas de OTLP, CloudWatch preserva la estructura semántica completa de su telemetría, incluidos los atributos de recursos, el ámbito de instrumentación, los atributos de puntos de datos y los metadatos específicos de AWS, y los expone como etiquetas de PromQL consultables.

Con PromQL, puede hacer lo siguiente:
+ Seleccionar series temporales por nombre de métrica y comparador de etiquetas.
+ Aplicar funciones y operadores matemáticos a series temporales.
+ Agregar métricas en todas las dimensiones, como el servicio, la región o la cuenta.
+ Calcular las tasas, los histogramas, los cuantiles y las medias móviles.

Puede utilizar consultas PromQL de forma interactiva en [Ejecución de consultas PromQL en Query Studio](CloudWatch-PromQL-QueryStudio.md) y también para crear CloudWatch Alarms. Para obtener más información, consulte [Consultas PromQL](CloudWatch-PromQL-Querying.md) y [Uso de PromQL en las alarmas](CloudWatch-PromQL-Alarms.md).

**nota**  
CloudWatch utiliza PromQL según la especificación Prometheus 3.0. Esto incluye la compatibilidad con nombres de métricas y etiquetas en UTF-8.

Los siguientes conceptos son fundamentales para trabajar con PromQL en CloudWatch.


| Concepto | Descripción | 
| --- | --- | 
| **Serie temporal** | Un flujo de valores con fecha y hora identificados por un nombre de métrica y un conjunto de pares clave-valor denominados *etiquetas*. Cada combinación única de nombre y etiquetas de la métrica forma una serie temporal distinta. | 
| **Vector instantáneo** | Conjunto de series temporales que contiene una sola muestra para cada serie, y todas comparten la misma marca de tiempo. Las consultas lo devuelven de esta forma: `{"http.server.active_requests", "@resource.service.name"="myservice"}`. | 
| **Vector de rango** | Conjunto de series temporales que contiene un rango de puntos de datos a lo largo del tiempo para cada serie. Se crea agregando un selector de duración entre paréntesis, por ejemplo, `avg_over_time({"http.server.active_requests", "@resource.service.name"="myservice"}[5m])`. | 
| **Etiqueta** | Un par clave-valor que se adjunta a series temporales. En las métricas incorporadas mediante OTLP, las etiquetas se derivan de los atributos de recursos, el ámbito de instrumentación, los atributos de puntos de datos y los metadatos específicos de AWS. | 
| **Comparador de etiquetas** | Expresión entre corchetes que filtra las series temporales por el valor de la etiqueta. Admite coincidencia exacta (`=`), distinto de (`!=`), coincidencia de expresión regular (`=~`) y coincidencia de expresión regular negativa (`!~`). | 
| **Operador de agregación** | Función que combina múltiples series temporales en un número menor de series. Los operadores más comunes incluyen `sum`, `avg`, `min`, `max`, `count` y `topk`. | 

## Límites y restricciones de PromQL
<a name="CloudWatch-PromQL-Limits"></a>

En la siguiente tabla se indican los límites y restricciones de PromQL:


| Límite | Valor | Información adicional | Código de error | 
| --- | --- | --- | --- | 
| Máximo de TPS para solicitudes de consulta por cuenta | 300 | Número máximo de solicitudes de consulta (/query, /query\_range) por segundo permitidas por cuenta. | 422 | 
| Máximo de TPS para solicitudes de detección por cuenta | 10 | Número máximo de solicitudes de detección (/series, /label, /label\_values) por segundo permitidas por cuenta. | 422 | 
| Máximo de solicitudes de consulta simultáneas por cuenta | 30 | Número máximo de consultas (/query, /query\_range) que una cuenta puede tener en marcha de forma activa al mismo tiempo. | 429 | 
| Máximo de solicitudes de detección simultáneas por cuenta | 30 | Número máximo de solicitudes de detección (/series, /labels, /label\_values) que una cuenta puede tener en marcha de forma activa al mismo tiempo. | 429 | 
| Máximo de series devueltas por solicitud de consulta | 500 | Número máximo de series temporales únicas que puede devolver una solicitud de consulta (/query, /query\_range). | 200: respuesta truncada | 
| Máximo de etiquetas devueltas por solicitud de detección | 10 000 | Número máximo de etiquetas únicas que puede devolver una solicitud de detección (/series, /labels, /label\_values). | 200: respuesta truncada | 
| Rango máximo por solicitud | 7 días | Rango de tiempo máximo que puede abarcar una consulta, incluidos los parámetros de intervalo y los periodos de búsqueda retroactiva. | 422 | 
| Máximo de series analizadas por periodo de 24 h | 100 000 | Número máximo de series temporales únicas que se pueden analizar por periodo de 24 horas de puesta en marcha de consultas. | 422 | 
| Máximo de muestras analizadas por periodo de 24 h | 300 000 000 | Número máximo de muestras que se pueden analizar por periodo de 24 horas de puesta en marcha de consultas. | 422 | 
| Máximo de muestras procesadas por periodo de 24 h | 3 000 000 000 | Número máximo de muestras que se pueden procesar por periodo de 24 horas de puesta en marcha de consultas | 422 | 
| Execution timeout (Tiempo de espera hasta ejecución) | 20 segundos | Tiempo máximo que el motor puede dedicar a evaluar una consulta, sin incluir el tiempo en cola ni el tiempo de recuperación de datos del almacenamiento. | 422 | 

## Regiones de AWS compatibles
<a name="CloudWatch-PromQL-Regions"></a>

En la siguiente tabla se indican las regiones de AWS que ofrecen la ingesta de métricas mediante OTLP, las consultas PromQL y Query Studio.


| Nombre de región | Código de región | Ingesta de métricas mediante OTLP | Consulta PromQL | Query Studio | 
| --- | --- | --- | --- | --- | 
| Este de EE. UU. (Norte de Virginia) | us-east-1 | ✓ | ✓ | ✓ | 
| Oeste de EE. UU. (Oregón) | us-west-2 | ✓ | ✓ | ✓ | 
| Europa (Irlanda) | eu-west-1 | ✓ | ✓ | ✓ | 
| Asia-Pacífico (Singapur) | ap-southeast-1 | ✓ | ✓ | ✓ | 
| Asia-Pacífico (Sídney) | ap-southeast-2 | ✓ | ✓ | ✓ | 
| Oeste de EE. UU. (Norte de California) | us-west-1 | ✓ | ✓ | ✓ | 
| Este de EE. UU. (Ohio) | us-east-2 | ✓ | ✓ | ✓ | 
| Europa (Londres) | eu-west-2 | ✓ | ✓ | ✓ | 
| Europa (París) | eu-west-3 | ✓ | ✓ | ✓ | 
| Europa (Fráncfort) | eu-central-1 | ✓ | ✓ | ✓ | 
| Europa (Estocolmo) | eu-north-1 | ✓ | ✓ | ✓ | 
| Europa (Milán) | eu-south-1 | ✓ | ✓ | ✓ | 
| Europa (España) | eu-south-2 | ✓ | ✓ | ✓ | 
| Europa (Zúrich) | eu-central-2 | ✓ | ✓ | ✓ | 
| Asia-Pacífico (Tokio) | ap-northeast-1 | ✓ | ✓ | ✓ | 
| Asia-Pacífico (Seúl) | ap-northeast-2 | ✓ | ✓ | ✓ | 
| Asia-Pacífico (Osaka) | ap-northeast-3 | ✓ | ✓ | ✓ | 
| Asia-Pacífico (Bombay) | ap-south-1 | ✓ | ✓ | ✓ | 
| Asia-Pacífico (Hyderabad) | ap-south-2 | ✓ | ✓ | ✓ | 
| Asia Pacífico (Hong Kong) | ap-east-1 | ✓ | ✓ | ✓ | 
| Asia-Pacífico (Taipéi) | ap-east-2 | ✓ | ✓ | ✓ | 
| Asia-Pacífico (Yakarta) | ap-southeast-3 | ✓ | ✓ | ✓ | 
| Asia-Pacífico (Melbourne) | ap-southeast-4 | ✓ | ✓ | ✓ | 
| Asia-Pacífico (Malasia) | ap-southeast-5 | ✓ | ✓ | ✓ | 
| Asia-Pacífico (Auckland) | ap-southeast-6 | ✓ | ✓ | ✓ | 
| Asia-Pacífico (Tailandia) | ap-southeast-7 | ✓ | ✓ | ✓ | 
| América del Sur (São Paulo) | sa-east-1 | ✓ | ✓ | ✓ | 
| Canadá (centro) | ca-central-1 | ✓ | ✓ | ✓ | 
| Oeste de Canadá (Calgary) | ca-west-1 | ✓ | ✓ | ✓ | 
| África (Ciudad del Cabo) | af-south-1 | ✓ | ✓ | ✓ | 
| México (centro) | mx-central-1 | ✓ | ✓ | ✓ | 

## Permisos de IAM para PromQL
<a name="CloudWatch-PromQL-IAM"></a>

Para hacer consultas PromQL, necesita los permisos `cloudwatch:GetMetricData` y `cloudwatch:ListMetrics`. La siguiente tabla indica las rutas de puntos de conexión de la API compatibles con Prometheus y las acciones de IAM requeridas:


| Ruta de punto de conexión de la API | Métodos HTTP | Acciones obligatorias | 
| --- | --- | --- | 
| `/api/v1/query` | GET, POST | `cloudwatch:GetMetricData`, `cloudwatch:ListMetrics` | 
| `/api/v1/query_range` | GET, POST | `cloudwatch:GetMetricData`, `cloudwatch:ListMetrics` | 
| `/api/v1/series` | GET, POST | `cloudwatch:ListMetrics` | 
| `/api/v1/labels` | GET, POST | `cloudwatch:ListMetrics` | 
| `/api/v1/label/{{label_name}}/values` | GET | `cloudwatch:ListMetrics` | 