QueryMetrics

A operação QueryMetrics avalia uma consulta instantânea do PromQL em um único momento ou em um intervalo de tempo.

O URL completo da solicitação combina o host de monitoramento do CloudWatch para a região da AWS com o caminho da operação, por exemplo https://monitoring.AWS Region.amazonaws.com/api/v1/query. Para obter mais informações sobre endpoints, assinaturas e as permissões necessárias do IAM, consulte Consultas do PromQL.

Parâmetros da consulta de URL

Os parâmetros a seguir são transmitidos na string de consulta de URL para solicitações GET ou como campos de corpo codificados em formulário para solicitações POST.

Duração

A duration em uma API compatível com o Prometheus é um número, seguido imediatamente por uma das seguintes unidades:

Permissões obrigatórias do IAM

Para chamar QueryMetrics, a identidade de chamada deve ter as duas ações do IAM a seguir:

Para obter o mapeamento completo das ações do IAM para todas as operações do PromQL, consulte Permissões do IAM para o PromQL.

Limite de resultados

Uma única resposta /api/v1/query ou /api/v1/query_range pode retornar até 500 séries temporais exclusivas. Para solicitar menos resultados, passe o parâmetro limit com um valor de 1 para 500. Caso você não especifique limit, o CloudWatch retornará até o máximo.

Quando as séries correspondentes excedem o limite, a resposta é truncada e uma mensagem é incluída no campo warnings padrão do Prometheus. O código de status do HTTP permanece em 200.

Para obter a lista completa dos limites do PromQL, incluindo TPS, simultaneidade e janelas de verificação de 24 horas, consulte Limites e restrições do PromQL.

Exemplo de solicitação

A solicitação POST a seguir passa a expressão PromQL em um corpo codificado em formulário. Caracteres especiais como {, } e " são codificados por porcentagem.

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)

A mesma chamada com 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"})'

Exemplo de resposta

Uma resposta bem-sucedida usa o envelope JSON padrão do 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"
                ]
            }
        ]
    }
}

Quando o conjunto de resultados excede o limite por chamada, o CloudWatch retorna uma matriz result truncada e inclui uma mensagem no 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"
    ]
}