GetAggregatedMetrics

CLASSIC/VPC 환경에서 이용 가능합니다.

Cloud Insight에서 수집된 시계열 메트릭을 집계 조건에 따라 조회합니다.

참고

기존 QueryDataMultiple와의 차이점

항목	QueryDataMultiple	GetAggregatedMetrics
요청/응답 구조	배열 기반으로 요청 순서에 따라 응답 해석 필요	Map 기반으로 요청시 설정한 key 에 따라 응답 해석 가능
조회 기간	하나의 메인 요청의 개별 서브 요청에 대해서 하나의 조회 기간만 허용	하나의 메인 요청의 개별 서브 요청에 대해서 독립적인 조회 기간 허용
집계 방식	Aggregation와 QueryAggregation로 설정 가능. 집계 방법: MIN, MAX, AVG, SUM, COUNT	PerSeriesAggregation 와 CrossSeriesAggregation 로 설정 가능. 집계 방법: MIN, MAX, AVG, SUM
interval	고정 Enum 값(Min1, Min5, Min30, Hour2, Day1)만 사용 가능	`value + unit` 방식으로 유연한 Interval 설정 가능
보관 주기	Interval Enum별로 고정된 보관 주기가 존재하여 조회 가능한 기간이 제한됨	Interval unit 단위(현재는 MINUTE 지원)로 보관 주기가 적용되어, 데이터포인트 한도 내에서 유연한 조회 기간 설정 가능

요청

요청 형식을 설명합니다. 요청 형식은 다음과 같습니다.

메서드	URI
POST	/metrics/aggregation/query

요청 헤더

Cloud Insight API에서 공통으로 사용하는 헤더에 대한 정보는 Cloud Insight 요청 헤더를 참조해 주십시오.

요청 바디

요청 바디에 대한 설명은 다음과 같습니다.

필드	타입	필수 여부	설명
`queries`	Map<String, MetricsAggregationSubQueryRequestDto>	Required	조회 조건 (요청 시 제약 사항은 하단 참고를 참조하십시오.)

참고

요청 시 다음 제약 사항을 참고해 주십시오.

1회 요청 시 최대 20개의 조회 조건을 지정할 수 있습니다.
1회 메인 쿼리 기준으로 최대 144,000개의 데이터 포인트를 조회할 수 있습니다.
개별 조회 조건(서브 쿼리)당 최대 10,080개의 데이터 포인트를 조회할 수 있습니다.

요청 예시

예시 1: 단일 시리즈 조회 (모든 dimension 지정)

모든 dimension을 지정하여 단일 시리즈만 조회하는 경우입니다. 이 경우 perSeriesAggregation만 적용되고, crossSeriesAggregation은 적용되지 않습니다.

curl --location --request POST 'https://cloudinsight.apigw.gov-ntruss.com/api/v2/metrics/aggregation/query' \
--header 'x-ncp-apigw-timestamp: {Timestamp}' \
--header 'x-ncp-iam-access-key: {Access Key}' \
--header 'x-ncp-apigw-signature-v2: {API Gateway Signature}' \
--header 'Content-Type: application/json' \
--data '{
  "queries": {
        "cpuUsage0": {
          "startTime": 1766039400000,
          "endTime": 1766039520000,
          "interval": {
            "value": 1,
            "unit": "MINUTE"
          },
          "productType": "NCP_PRODUCT",
          "productKey": "**********",
          "metric": "used_rto",
          "dimensions": {
            "type": "cpu",
            "instanceNo": "**********",
            "cpu_idx": "0"
          },
          "perSeriesAggregation": "AVG",
          "crossSeriesAggregation": "AVG"
        },
        "cpuUsage1": {
          "startTime": 1766039400000,
          "endTime": 1766039520000,
          "interval": {
            "value": 1,
            "unit": "MINUTE"
          },
          "productType": "NCP_PRODUCT",
          "productKey": "**********",
          "metric": "used_rto",
          "dimensions": {
            "type": "cpu",
            "instanceNo": "**********",
            "cpu_idx": "1"
          },
          "perSeriesAggregation": "AVG",
          "crossSeriesAggregation": "AVG"
        }
  }
}'

예시 2: 다중 시리즈 조회 (dimension 미지정, crossSeriesAggregation 활용)

cpu_idx를 지정하지 않아 여러 CPU 코어의 시리즈가 적용되는 경우입니다. 각 시점별로 여러 시리즈의 값이 crossSeriesAggregation에 따라 집계됩니다.

curl --location --request POST 'https://cloudinsight.apigw.gov-ntruss.com/api/v2/metrics/aggregation/query' \
--header 'x-ncp-apigw-timestamp: {Timestamp}' \
--header 'x-ncp-iam-access-key: {Access Key}' \
--header 'x-ncp-apigw-signature-v2: {API Gateway Signature}' \
--header 'Content-Type: application/json' \
--data '{
  "queries": {
        "cpuUsageAvg": {
          "startTime": 1766039400000,
          "endTime": 1766039520000,
          "interval": {
            "value": 1,
            "unit": "MINUTE"
          },
          "productType": "NCP_PRODUCT",
          "productKey": "**********",
          "metric": "used_rto",
          "dimensions": {
            "type": "cpu",
            "instanceNo": "**********"
          },
          "perSeriesAggregation": "AVG",
          "crossSeriesAggregation": "AVG"
        },
        "cpuUsageMax": {
          "startTime": 1766039400000,
          "endTime": 1766039520000,
          "interval": {
            "value": 1,
            "unit": "MINUTE"
          },
          "productType": "NCP_PRODUCT",
          "productKey": "**********",
          "metric": "used_rto",
          "dimensions": {
            "type": "cpu",
            "instanceNo": "**********"
          },
          "perSeriesAggregation": "AVG",
          "crossSeriesAggregation": "MAX"
        }
  }
}'

참고

예시 2 설명

cpu_idx를 지정하지 않아 cpu_idx:0, cpu_idx:1 등 여러 CPU 코어의 데이터가 대상이 됩니다.
cpuUsageAvg: 각 시점별로 여러 CPU 코어의 사용률을 평균(AVG)하여 반환합니다.
cpuUsageMax: 각 시점별로 여러 CPU 코어의 사용률 중 최댓값(MAX)을 반환합니다.
예를 들어, 특정 시점에 cpu_idx:0이 0.535, cpu_idx:1이 0.351인 경우:
- crossSeriesAggregation: AVG → (0.535 + 0.351) / 2 = 0.443
- crossSeriesAggregation: MAX → max(0.535, 0.351) = 0.535

응답

응답 형식을 설명합니다.

응답 바디

응답 바디에 대한 설명은 다음과 같습니다.

필드	타입	필수 여부	설명
`results`	Object	-	쿼리 결과
`results.{queryKey}`	Object	-	`queries` 요청에서 지정한 key에 대한 조회 결과
`results.{queryKey}.dataPoints`	Array	-	조회 결과 데이터 포인트 목록 [타임스탬프(Unix Timestamp, ms), 데이터 값] 형태로 표시

응답 상태 코드

네이버 클라우드 플랫폼에서 공통으로 사용하는 응답 상태 코드에 대한 정보는 Cloud Insight API 응답 상태 코드를 참조해 주십시오.

응답 예시

예시 1 응답 (단일 시리즈 조회)

{
  "results": {
    "cpuUsage0": {
      "dataPoints": [
        [
          1766039400000,
          0.535207
        ],
        [
          1766039460000,
          0.467446
        ],
        [
          1766039520000,
          0.619454
        ]
      ]
    },
    "cpuUsage1": {
      "dataPoints": [
        [
          1766039400000,
          0.351229
        ],
        [
          1766039460000,
          0.385389
        ],
        [
          1766039520000,
          0.284043
        ]
      ]
    }
  }
}

예시 2 응답 (다중 시리즈 조회, crossSeriesAggregation 적용)

{
  "results": {
    "cpuUsageAvg": {
      "dataPoints": [
        [
          1766039400000,
          0.443218
        ],
        [
          1766039460000,
          0.426418
        ],
        [
          1766039520000,
          0.451749
        ]
      ]
    },
    "cpuUsageMax": {
      "dataPoints": [
        [
          1766039400000,
          0.535207
        ],
        [
          1766039460000,
          0.467446
        ],
        [
          1766039520000,
          0.619454
        ]
      ]
    }
  }
}

참고

응답 값 설명

예시 2의 응답에서 cpuUsageAvg의 값(0.443218)은 cpu_idx:0(0.535207)과 cpu_idx:1(0.351229)의 평균입니다.
cpuUsageMax의 값(0.535207)은 두 CPU 코어 중 최대값입니다.