# Consultas PromQL Al ingerir métricas de OpenTelemetry en CloudWatch mediante el [Punto de conexión de métricas](CloudWatch-OTLPEndpoint.md#CloudWatch-MetricsEndpoint), 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 | `@resource.@` | `@resource.` | `@resource.service.name="myservice"` | | Alcance de la instrumentación | `@instrumentation.@` | `@instrumentation.` | `@instrumentation.@name="otel-go/metrics"` | | Punto de datos | `@datapoint.@` | `@datapoint.` o sin prefijo | `cpu="cpu0"` o `@datapoint.cpu="cpu0"` | | AWSReservado para | N/A | `@aws.` | `@aws.account_id="123456789"` | ## 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](CloudWatch-OTelEnrichment.md). 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 | | --- | --- | --- | | `InstanceId` | Dimensión de CloudWatch original, como atributo de punto de datos | `i-0123456789abcdef0` | | `"@resource.cloud.resource_id"` | ARN completo del recurso | `arn:aws:ec2:us-east-1:123456789012:instance/i-0123456789abcdef0` | | `"@resource.cloud.provider"` | Proveedor de servicios en la nube | `aws` | | `"@resource.cloud.region"` | AWSRegión de en la que se originó esta métrica | `us-east-1` | | `"@resource.cloud.account.id"` | AWSID de cuenta de en el que se originó esta métrica | `123456789012` | | `"@instrumentation.@name"` | Nombre del ámbito de la instrumentación que identifica el servicio de origen | `cloudwatch.aws/ec2` | | `"@instrumentation.cloudwatch.source"` | Identificador del origen del servicio | `aws.ec2` | | `"@instrumentation.cloudwatch.solution"` | Identificador de la solución de enriquecimiento | `CloudWatchOTelEnrichment` | | `"@aws.tag.Environment"` | AWSEtiqueta de recurso de | `production` | | `"@aws.account"` | AWSCuenta de en la que se incorporó esta métrica (etiqueta del sistema) | `123456789012` | | `"@aws.region"` | AWSRegión de en la que se incorporó esta métrica (etiqueta del sistema) | `us-east-1` | 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/](https://grafana.com/grafana/plugins/grafana-amazonprometheus-datasource/); instálelo desde el catálogo de complementos de Grafana antes de agregar el origen de datos. El complemento de AMP v3.0.0 requiere Grafana `>=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](CloudWatch-PromQL.md#CloudWatch-PromQL-IAM). Para configurar Grafana, siga estos pasos. 1. Instale el complemento de origen de datos de **Amazon Managed Service para Prometheus** del catálogo de complementos de Grafana. 1. En Grafana, vaya a **Conexiones**, **Orígenes de datos**, elija **Agregar origen de datos** y seleccione **Amazon Managed Service para Prometheus**. 1. Establezca la **URL** del origen de datos en `https://monitoring.{{AWS Region}}.amazonaws.com`. 1. 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). 1. 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](https://docs.aws.amazon.com/grafana/latest/userguide/amazon-prometheus-data-source.html) 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](CloudWatch-PromQL.md#CloudWatch-PromQL-IAM). Para configurar el origen de datos, complete los siguientes pasos. 1. En el espacio de nombres de Amazon Managed Grafana, agregue un origen de datos de **Amazon Managed Service para Prometheus**. 1. Establezca la **URL** del origen de datos en `https://monitoring.{{AWS Region}}.amazonaws.com`. 1. 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. 1. Elija **Guardar y probar**. ## Consultas con herramientas del MCP El [servidor MCP de CloudWatch](https://awslabs.github.io/mcp/servers/cloudwatch-mcp-server/) proporciona herramientas del protocolo de contexto para modelos (MCP) que permiten a los asistentes de IA y las herramientas de desarrollo consultar los datos de PromQL de CloudWatch en su nombre. Las herramientas del MCP gestionan automáticamente la autenticación y el formato de las solicitudes, por lo que puede centrarse en escribir consultas de PromQL en lugar de administrar las solicitudes HTTP y la firma de SigV4. Las siguientes herramientas de PromQL están disponibles en el servidor MCP de CloudWatch: | Herramienta | Descripción | | --- | --- | | `execute_promql_query` | Ejecuta una consulta PromQL instantánea y devuelve valores métricos en un único momento. | | `execute_promql_range_query` | 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. | | `get_promql_label_values` | Recupera los valores de una etiqueta PromQL específica, como `__name__` para los nombres de métricas o `@resource.service.name` para los servicios. | | `get_promql_series` | Busca series temporales que coincidan con los selectores de etiquetas PromQL y devuelve el conjunto completo de etiquetas de cada serie coincidente. | | `get_promql_labels` | 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](https://awslabs.github.io/mcp/servers/cloudwatch-mcp-server#tools-for-cloudwatch-promql) en la documentación del servidor MCP 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](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html) mediante `monitoring` como el nombre del servicio. El punto de conexión de PromQL sigue el patrón `https://monitoring.{{AWS Region}}.amazonaws.com/api/v1/{{operation}}`. 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 `https://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](CloudWatch-PromQL-APIs.md). Para ver la lista de regiones de AWS en las que están disponibles las consultas de PromQL, consulte [Regiones de AWS compatibles](CloudWatch-PromQL.md#CloudWatch-PromQL-Regions). Para obtener las acciones de IAM necesarias para cada operación, consulte [Permisos de IAM para PromQL](CloudWatch-PromQL.md#CloudWatch-PromQL-IAM).