Consultas PromQL
Al ingerir métricas de OpenTelemetry en CloudWatch mediante el Punto de conexión de métricas, el modelo de datos OTLP jerárquico se aplana en etiquetas compatibles con PromQL. En esta sección se describe la estructura de las etiquetas, la sintaxis de PromQL para consultar estas etiquetas y la compatibilidad con UTF-8 en PromQL.
nota
PromQL en Prometheus 3 admite caracteres UTF-8 completos en nombres de métricas y etiquetas. Esto es especialmente importante en el caso de las métricas de OTLP, ya que las convenciones semánticas de OpenTelemetry utilizan puntos en los nombres de los atributos, por ejemplo, service.name. Anteriormente, estos puntos se sustituían por guiones bajos durante la traducción, lo que provocaba discrepancias entre lo que se definía en las convenciones de OpenTelemetry y lo que se podía consultar en Prometheus.
Cuando se utiliza PromQL en CloudWatch, la convención de prefijo @ distingue las etiquetas con ámbito de OTLP de las etiquetas estándar de Prometheus. Los campos dentro de cada ámbito utilizan un prefijo doble @ (por ejemplo, @resource.@schema_url), mientras que los atributos utilizan un prefijo de ámbito simple @, por ejemplo, @resource.service.name. Los atributos de puntos de datos también admiten acceso sin prefijo para mantener la compatibilidad con las consultas PromQL estándar; por ejemplo, {"http.server.active_requests"} y {"@datapoint.@name"="http.server.active_requests"} son equivalentes.
Las expresiones PromQL se escriben entre corchetes y especifican el nombre de la métrica y un conjunto opcional de comparadores de etiquetas. En el siguiente ejemplo, se seleccionan todas las series temporales de la métrica http.server.active_requests:
{"http.server.active_requests"}
En el siguiente ejemplo, se seleccionan todas las series temporales de la métrica http.server.active_requests en las que el atributo de recurso de OpenTelemetry service.name equivale a myservice:
{"http.server.active_requests", "@resource.service.name"="myservice"}
Puede combinar varios comparadores de etiquetas en una sola consulta. En el siguiente ejemplo, se seleccionan todas las series temporales de la métrica http.server.active_requests en las que el atributo de recurso de OpenTelemetry service.name equivale a myservice en todas las regiones de EE. UU.:
{"http.server.active_requests", "@resource.service.name"="myservice", "@aws.region"=~"us-.*"}
En el siguiente ejemplo, se muestra una consulta de rango. Calcula el valor promedio de todos los puntos de datos dentro de un rango de tiempo específico para cada serie temporal:
avg_over_time( {"http.server.active_requests", "@resource.service.name"="myservice"}[5m] )
En la tabla siguiente se resumen las convenciones de prefijo de cada ámbito de OTLP:
| Alcance de OTLP | Prefix de campos | Prefijo de atributos | Ejemplo |
|---|---|---|---|
Recurso |
|
|
|
Alcance de la instrumentación |
|
|
|
Punto de datos |
|
|
|
AWSReservado para |
N/A |
|
|
Consulta de métricas suministradas por AWS con PromQL
Para poder consultar las métricas suministradas por AWS en PromQL, primero debe habilitar el enriquecimiento de OpenTelemetry de las métricas suministradas. Consulte : Métricas suministradas de AWS en formato OpenTelemetry.
Tras habilitar el enriquecimiento de OpenTelemetry, las métricas suministradas por AWS se pueden consultar mediante PromQL con etiquetas adicionales. El nombre de la métrica es el mismo que el nombre de la métrica de CloudWatch original, y las dimensiones de CloudWatch originales están disponibles como atributos de puntos de datos. Están disponibles las siguientes etiquetas (el siguiente ejemplo es para una instancia de EC2):
| Etiqueta PromQL | Descripción | Ejemplo |
|---|---|---|
|
Dimensión de CloudWatch original, como atributo de punto de datos |
|
|
ARN completo del recurso |
|
|
Proveedor de servicios en la nube |
|
|
AWSRegión de en la que se originó esta métrica |
|
|
AWSID de cuenta de en el que se originó esta métrica |
|
|
Nombre del ámbito de la instrumentación que identifica el servicio de origen |
|
|
Identificador del origen del servicio |
|
|
Identificador de la solución de enriquecimiento |
|
|
AWSEtiqueta de recurso de |
|
|
AWSCuenta de en la que se incorporó esta métrica (etiqueta del sistema) |
|
|
AWSRegión de en la que se incorporó esta métrica (etiqueta del sistema) |
|
El siguiente ejemplo selecciona Invocations para una función de Lambda específica:
{Invocations, FunctionName="my-api-handler"}
El siguiente ejemplo selecciona Errors de Lambda para todas las funciones etiquetadas con un equipo específico:
{Errors, "@instrumentation.@name"="cloudwatch.aws/lambda", "@aws.tag.Team"="backend"}
El siguiente ejemplo calcula la cantidad total de Invocations de Lambda agrupadas por equipo:
sum by ("@aws.tag.Team")( {Invocations, "@instrumentation.@name"="cloudwatch.aws/lambda"} )
El siguiente ejemplo selecciona todas las series temporales de la métrica CPUUtilization de EC2. El uso de "@instrumentation.@name"="cloudwatch.aws/ec2" es para identificar de forma exclusiva la métrica CPUUtilization de EC2 y no de otros servicios de AWS, como Amazon Relational Database Service:
histogram_avg({CPUUtilization, "@instrumentation.@name"="cloudwatch.aws/ec2"})
Consultas desde Grafana
Para consultar los datos de PromQL de CloudWatch desde Grafana, puede agregar el complemento de origen de datos de Amazon Managed Service para Prometheus y apuntarlo al punto de conexión de supervisión de CloudWatch. La firma con SigV4 está integrada en el complemento y siempre está habilitada, por lo que no hay que activarla. El complemento está publicado en grafana.com/grafana/plugins/grafana-amazonprometheus-datasource/>=11.6.11 <12 || >=12.0.10 <12.1 || >=12.1.7
<12.2 || >=12.2.5.
Requisitos previos de IAM: la entidad principal de IAM cuyas credenciales utiliza Grafana debe tener cloudwatch:GetMetricData (necesario para las consultas instantáneas y de intervalo) y cloudwatch:ListMetrics (necesario para la detección de series y etiquetas). Para obtener más información, consulte Permisos de IAM para PromQL.
Para configurar Grafana, siga estos pasos.
-
Instale el complemento de origen de datos de Amazon Managed Service para Prometheus del catálogo de complementos de Grafana.
-
En Grafana, vaya a Conexiones, Orígenes de datos, elija Agregar origen de datos y seleccione Amazon Managed Service para Prometheus.
-
Establezca la URL del origen de datos en
https://monitoring..AWS Region.amazonaws.com -
Establezca la Región en su región de AWS. Elija un proveedor de autenticación adecuado para el entorno (cadena de credenciales predeterminada, claves de acceso o rol de IAM del espacio de trabajo).
-
Elija Guardar y probar.
Consultas desde Amazon Managed Grafana
Para consultar los datos de PromQL de CloudWatch desde un espacio de trabajo de Amazon Managed Grafana, puede agregar un origen de datos de Amazon Managed Service para Prometheus que apunte al punto de conexión de supervisión de CloudWatch. Este complemento de origen de datos firma automáticamente las solicitudes con SigV4 mediante el rol de IAM del espacio de trabajo; SigV4 siempre está habilitado y no es necesario configurarlo. El complemento está disponible en la versión 12 y posteriores de Amazon Managed Grafana. Para obtener más información, consulte Conexión a un origen de datos de Amazon Managed Service para Prometheus en la Guía del usuario de Amazon Managed Grafana.
Requisitos previos de IAM: el rol de IAM del espacio de trabajo de Amazon Managed Grafana debe tener cloudwatch:GetMetricData (necesario para las consultas instantáneas y de intervalo) y cloudwatch:ListMetrics (necesario para la detección de series y etiquetas). Para obtener más información, consulte Permisos de IAM para PromQL.
Para configurar el origen de datos, complete los siguientes pasos.
-
En el espacio de nombres de Amazon Managed Grafana, agregue un origen de datos de Amazon Managed Service para Prometheus.
-
Establezca la URL del origen de datos en
https://monitoring..AWS Region.amazonaws.com -
Establezca la Región en su región de AWS. Amazon Managed Grafana inyecta automáticamente las credenciales del rol de IAM del espacio de trabajo, de modo que no es necesario configurar claves estáticas.
-
Elija Guardar y probar.
Consultas con herramientas del MCP
El servidor MCP de CloudWatch
Las siguientes herramientas de PromQL están disponibles en el servidor MCP de CloudWatch:
| Herramienta | Descripción |
|---|---|
|
Ejecuta una consulta PromQL instantánea y devuelve valores métricos en un único momento. |
|
Ejecuta una consulta de rangos PromQL en un intervalo de tiempo y devuelve datos de series temporales para el análisis de tendencias y la representación gráfica. |
|
Recupera los valores de una etiqueta PromQL específica, como |
|
Busca series temporales que coincidan con los selectores de etiquetas PromQL y devuelve el conjunto completo de etiquetas de cada serie coincidente. |
|
Enumera todos los nombres de etiquetas PromQL disponibles para permitirle detectar la estructura de etiquetas de las métricas. |
Para obtener información completa sobre los parámetros, la configuración y las instrucciones de configuración, consulte Herramientas para PromQL de CloudWatch
Consultas con la API HTTP
Para consultar los datos de PromQL de CloudWatch mediante programación, también puede llamar directamente a los puntos de conexión HTTP compatibles con Prometheus. Las solicitudes se deben firmar con AWS Signature Version 4 mediante monitoring como el nombre del servicio.
El punto de conexión de PromQL sigue el patrón https://monitoring.. Por ejemplo, para la región Este de EE. UU. (Norte de Virginia) (us-east-1), el punto de conexión de una consulta instantánea es AWS
Region.amazonaws.com/api/v1/operationhttps://monitoring.us-east-1.amazonaws.com/api/v1/query.
Para ver la referencia completa de la API, incluidas las operaciones compatibles, los parámetros de solicitud y los formatos de respuesta, consulte API compatibles con Prometheus. Para ver la lista de regiones de AWS en las que están disponibles las consultas de PromQL, consulte Regiones de AWS compatibles. Para obtener las acciones de IAM necesarias para cada operación, consulte Permisos de IAM para PromQL.
