QueryMetrics

La operación QueryMetrics evalúa una consulta instantánea de PromQL en un único momento o evalúa una consulta en un intervalo de tiempo.

La URL de solicitud completa combina el host de supervisión de CloudWatch de la región de AWS con la ruta de operación, por ejemplo, https://monitoring.AWS Region.amazonaws.com/api/v1/query. Para obtener más información sobre los puntos de conexión, la firma y los permisos de IAM necesarios, consulte Consultas PromQL.

Parámetros de consulta de URL

Los siguientes parámetros se pasan en la cadena de consulta de la URL para las solicitudes GET o como campos de cuerpo codificados como formulario para las solicitudes POST.

Duración

En una API compatible con Prometheus, una duration es un número, seguido inmediatamente de una de las siguientes unidades:

Permisos de IAM necesarios

Para llamar a QueryMetrics, la identidad que hace la llamada debe tener las siguientes acciones de IAM:

Para ver la asignación completa de acciones de IAM para todas las operaciones de PromQL, consulte Permisos de IAM para PromQL.

Límite de resultados

Una sola respuesta /api/v1/query o /api/v1/query_range puede devolver hasta 500 series temporales únicas. Para solicitar menos resultados, pase el parámetro limit con un valor comprendido entre 1 y 500. Si no especifica limit, CloudWatch devuelve el máximo.

Cuando las series temporales coincidentes superan el límite, la respuesta se trunca y se incluye un mensaje en el campo warnings de Prometheus estándar. El código de estado HTTP continúa siendo 200.

Para ver la lista completa de los límites de PromQL, incluidos el TPS, la simultaneidad y los periodos de escaneo de 24 horas, consulte Límites y restricciones de PromQL.

Solicitud de ejemplo

La siguiente solicitud POST pasa la expresión PromQL en un cuerpo codificado como formulario. Los caracteres especiales como {, } y " están codificados como porcentaje.

POST /api/v1/query HTTP/1.1
Host: monitoring.us-east-1.amazonaws.com
Content-Type: application/x-www-form-urlencoded
Authorization: AUTHPARAMS
X-Amz-Date: 20260605T193725Z
User-Agent: awscurl/0.36

query=sum(%7B%22http.server.active_requests%22%7D)

La misma llamada con awscurl:

awscurl --service monitoring --region us-east-1 \
    -X POST 'https://monitoring.us-east-1.amazonaws.com/api/v1/query' \
    -H 'Content-Type: application/x-www-form-urlencoded' \
    -d 'query=sum({"http.server.active_requests"})'

Respuesta de ejemplo

Una respuesta correcta utiliza el sobre JSON estándar de Prometheus:

HTTP/1.1 200 OK
x-amzn-RequestId: 12345678-abcd-4442-b8c5-262b45e9b535
Content-Type: application/json

{
    "status": "success",
    "data": {
        "resultType": "vector",
        "result": [
            {
                "metric": {},
                "value": [
                    1780000000.000,
                    "42"
                ]
            }
        ]
    }
}

Cuando el conjunto de resultados supera el límite por llamada, CloudWatch devuelve una matriz result truncada e incluye un mensaje en el campo warnings:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "success",
    "data": {
        "resultType": "vector",
        "result": [ ... up to 500 series ... ]
    },
    "warnings": [
        "result truncated to the maximum of 500 series; refine the query or use the limit parameter"
    ]
}