View a markdown version of this page

QueryMetrics - Amazon CloudWatch
URL 쿼리 파라미터필수 IAM 권한결과 제한샘플 요청샘플 응답

QueryMetrics

QueryMetrics 작업은 단일 시점 동안 PromQL 인스턴트 쿼리를 평가하거나 일정 기간 동안 쿼리를 평가합니다.

유효한 HTTP 동사

GET, POST

유효한 URI

/api/v1/query - 단일 시점의 인스턴트 쿼리를 평가합니다.

/api/v1/query_range - 일정 기간 동안 쿼리를 평가합니다.

전체 요청 URL은 AWS 리전의 CloudWatch 모니터링 호스트를 https://monitoring.AWS Region.amazonaws.com/api/v1/query와 같은 작업 경로와 결합합니다. 엔드포인트, 서명, 필수 IAM 권한에 대한 자세한 정보는 PromQL 쿼리 섹션을 참조하세요.

URL 쿼리 파라미터

다음 파라미터는 GET 요청의 경우 URL 쿼리 문자열로, POST 요청의 경우 양식 인코딩 본문 필드로 전달됩니다.

파라미터 적용 대상 설명

query

둘 다

필수 사항입니다. 평가할 PromQL 표현식 문자열입니다. 표현식은 {"http.server.active_requests"} 또는 {__name__="http.server.active_requests"} 등의 이름으로 지표를 선택해야 합니다. 지표 이름 없이 레이블로만 시리즈를 선택하는 것은 지원되지 않습니다.

time

/api/v1/query

선택 사항. RFC 3339 타임스탬프 또는 Unix 타임스탬프로서의 평가 타임스탬프입니다. 기본값은 현재 서버 시간입니다.

start

/api/v1/query_range

필수 사항입니다. RFC 3339 타임스탬프 또는 Unix 타임스탬프로의 시간 범위 시작입니다.

end

/api/v1/query_range

필수 사항입니다. RFC 3339 타임스탬프 또는 Unix 타임스탬프로의 시간 범위 종료입니다.

step

/api/v1/query_range

필수 사항입니다. duration 형식 또는 초 단위 부동 소수점으로 나타내는 쿼리 해결 단계 폭입니다.

limit

둘 다

선택 사항. 반환할 최대 고유 시계열 수(1~500)입니다. limit를 지정하지 않으면 CloudWatch는 최대 수(500)까지 반환합니다. 결과 제한을(를) 참조하세요.

지속 시간

Prometheus 호환 API의 duration은 숫자이며, 그 뒤에 바로 다음 단위 중 하나가 따라옵니다.

  • ms밀리초

  • s초

  • m분

  • h시간

  • d일(항상 하루를 24시간으로 가정)

  • w주(항상 한 주를 7일로 가정)

  • y년(항상 1년을 365일로 가정)

필수 IAM 권한

QueryMetrics를 호출하려면 호출 ID에 다음 두 가지 IAM 작업이 있어야 합니다.

  • cloudwatch:GetMetricData

  • cloudwatch:ListMetrics

모든 PromQL 작업에 대한 전체 IAM 작업 매핑은 PromQL에 대한 IAM 권한 섹션을 참조하세요.

결과 제한

단일 /api/v1/query 또는 /api/v1/query_range 응답은 최대 500개의 고유한 시계열을 반환할 수 있습니다. 더 적은 결과를 요청하려면 값(1~500)이 있는 limit 파라미터를 전달합니다. limit를 지정하지 않으면 CloudWatch는 최대 수까지 반환합니다.

일치하는 시리즈가 한도를 초과하면 응답이 잘리고 메시지가 표준 Prometheus warnings 필드에 포함됩니다. HTTP 상태 코드는 200으로 유지됩니다.

TPS, 동시성 및 24시간 스캔 기간을 포함한 PromQL 제한의 전체 목록은 PromQL 한도 및 제한 사항 섹션을 참조하세요.

샘플 요청

다음 POST 요청은 양식 인코딩 본문에서 PromQL 표현식을 전달합니다. {, }, "와 같은 특수 문자는 백분율로 인코딩됩니다.

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)

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"})'

샘플 응답

성공적인 응답은 표준 Prometheus JSON 봉투를 사용합니다.

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"
                ]
            }
        ]
    }
}

결과 집합이 호출당 한도를 초과하면 CloudWatch는 잘린 result 배열을 반환하고 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"
    ]
}