View a markdown version of this page

GetSeries - Amazon CloudWatch
Parámetros de consulta de URLPermisos de IAM necesariosLímite de resultadosSolicitudes de ejemploRespuesta de ejemplo

GetSeries

La operación GetSeries devuelve la lista de series temporales cuyas etiquetas coinciden con uno o más selectores.

Verbos HTTP válidos

GET, POST

URI válido

/api/v1/series

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/series. 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.

Parámetro Descripción

match[]

Obligatorio. Un selector de series que filtra las series temporales que se devolverán. Cada selector debe incluir una coincidencia exacta (=) en el nombre de la métrica, por ejemplo, {"http.server.active_requests"} o {__name__="http.server.active_requests"}. No se admiten los selectores sin un comparador igual que el nombre de la métrica. Además de la coincidencia exacta, los comparadores de etiquetas también admiten distinto de (!=), coincidencia de expresión regular (=~) y coincidencia de expresión regular negativa (!~). Especifique match[] una o más veces para combinar los selectores. Para obtener más información sobre la sintaxis de los selectores, consulte Consultas PromQL.

start

Obligatorio. Inicio del intervalo de tiempo que se debe tener en cuenta, como una marca de tiempo RFC 3339 o una marca de tiempo de Unix.

end

Obligatorio. Final del intervalo de tiempo que se debe tener en cuenta, como una marca de tiempo RFC 3339 o una marca de tiempo de Unix.

limit

Opcional. Número máximo de series temporales únicas que se devolverán, de 1 a 10000. Si no especifica limit, CloudWatch devuelve el máximo (10 000). Consulte Límite de resultados.

Permisos de IAM necesarios

Para llamar a GetSeries, la identidad que hace la llamada debe tener la siguiente acción de IAM:

  • cloudwatch:ListMetrics

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/series puede devolver hasta 10 000 series temporales únicas. Para solicitar menos resultados, pase el parámetro limit con un valor comprendido entre 1 y 10000. 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.

Solicitudes de ejemplo

La siguiente solicitud POST utiliza un selector de coincidencias exactas. El selector, start y end se pasan como campos codificados como formulario en el cuerpo de la solicitud. Los caracteres especiales como {, }, " y , están codificados como porcentaje. El valor match[] decodificado es {"http.server.active_requests","@resource.service.name"="myservice"}.

POST /api/v1/series 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

match%5B%5D=%7B%22http.server.active_requests%22%2C%22%40resource.service.name%22%3D%22myservice%22%7D&start=1780662000&end=1780665600

La siguiente solicitud POST utiliza un selector de coincidencias de expresión regular. El valor match[] decodificado es {"http.server.active_requests","@aws.region"=~"us-.*"}.

POST /api/v1/series 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

match%5B%5D=%7B%22http.server.active_requests%22%2C%22%40aws.region%22%3D~%22us-.*%22%7D&start=1780662000&end=1780665600

La misma llamada con awscurl:

awscurl --service monitoring --region us-east-1 \
    -X POST 'https://monitoring.us-east-1.amazonaws.com/api/v1/series' \
    -H 'Content-Type: application/x-www-form-urlencoded' \
    -d 'match[]={"http.server.active_requests","@aws.region"=~"us-.*"}&start=1780662000&end=1780665600'

Respuesta de ejemplo

Una respuesta correcta utiliza el sobre JSON estándar de Prometheus. El campo data es una matriz de mapas de etiquetas, uno por cada serie coincidente.

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

{
    "status": "success",
    "data": [
        {
            "__name__": "http.server.active_requests",
            "@resource.service.name": "myservice",
            "@aws.region": "us-east-1"
        },
        {
            "__name__": "http.server.active_requests",
            "@resource.service.name": "myservice",
            "@aws.region": "us-west-2"
        }
    ]
}