Monitoring API 문제 해결

이 가이드에서는 Monitoring API를 사용할 때 발생할 수 있는 몇 가지 문제에 대해 설명합니다.

Monitoring API는 Cloud API의 집합 중 하나입니다. 이러한 API는 공통적인 오류 코드 집합을 공유합니다. Cloud API에서 정의한 오류 코드 목록과 오류 처리에 대한 일반적인 제안사항은 오류 처리를 참조하세요.

API 탐색기를 디버깅에 사용

API 탐색기는 API 메서드의 참조 페이지에 빌드된 위젯입니다. 필드를 작성하여 메서드를 호출할 수 있으며, 이때 코드를 작성할 필요가 없습니다.

메서드 호출에 문제가 있으면 해당 메서드의 참조 페이지에서 API 탐색기(API 사용해보기) 위젯을 사용하여 문제를 디버깅하세요. 자세한 내용은 API 탐색기를 참조하세요.

일반적인 API 오류

다음은 API 호출에서 볼 수 있는 몇 가지 Monitoring API 오류 및 메시지입니다.

'서버에서 요청된 URL을 찾을 수 없습니다.' 메시지와 함께 404 NOT_FOUND 반환: URL의 일부가 잘못되었습니다. URL을 메서드의 참조 페이지에 표시된 메서드의 URL과 비교하세요. 이 오류는 'projects' 대신 'project'라고 입력하는 등의 맞춤법 오류가 있거나 'timeSeries' 대신 'TimeSeries'로 입력하는 등의 대문자 사용 오류가 있다는 의미일 수 있습니다.
'사용자가 프로젝트(또는 측정항목)에 액세스할 권한이 없습니다.' 메시지와 함께 401 UNAUTHENTICATED 반환: 이 오류 코드는 일반적으로 승인 문제를 나타내지만 프로젝트 ID 또는 측정항목 유형 이름에 오류가 있음을 의미할 수 있습니다. 맞춤법과 대문자 사용을 확인합니다.

API 탐색기를 사용하지 않는 경우, 사용해 보세요. API 호출이 API 탐색기에서 작동하는 경우 API 호출을 실행하는 환경에 승인 문제가 있을 수 있습니다. API 관리자 페이지로 이동하여 프로젝트에 Monitoring API가 사용 설정되어 있는지 확인합니다.
'필드 필터에 잘못된 값이 있습니다.' 메시지와 함께 400 INVALID_ARGUMENT 반환: Monitoring 필터의 맞춤법과 형식이 올바른지 확인합니다. 자세한 내용은 Monitoring 필터를 참조하세요.
"요청에 interval.endTime 필드가 누락되었습니다." 메시지와 함께 400 INVALID_ARGUMENT 반환: 종료 시간이 누락되었거나 존재하지만 형식이 올바르지 않은 경우 이 메시지가 표시됩니다. API 탐색기를 사용하는 경우 시간 필드의 값에 따옴표를 사용하지 마세요.

유효한 시간 사양의 예는 다음과 같습니다.
```
2024-05-11T01:23:45Z
2024-05-11T01:23:45.678Z
2024-05-11T01:23:45.678+05:00
2024-05-11T01:23:45.678-04:30
```

결과 누락

API 호출이 상태 코드 200과 빈 응답을 반환하면 다음을 고려하세요.

호출에서 필터를 사용하는 경우 필터와 일치하는 항목이 없을 수 있습니다. 필터 일치는 대소문자를 구분합니다. 필터 문제를 해결하려면 먼저 metric.type과 같은 필터 구성요소를 하나만 지정하고 결과가 나오는지 확인합니다. 다른 필터 구성요소를 하나씩 추가하며 요청을 작성합니다.

커스텀 측정항목을 사용할 때는 측정항목을 정의하는 프로젝트가 지정되어 있는지 확인합니다.

timeSeries.list 메서드를 사용할 때 데이터 포인트가 누락되는 데는 여러 가지 이유가 있습니다.

데이터가 오래되었을 수 있습니다. 자세한 내용은 데이터 보관을 참조하세요.
데이터가 아직 Monitoring으로 전파되지 않았을 수 있습니다. 자세한 내용은 측정항목 데이터의 지연 시간을 참조하세요.
간격이 잘못되었습니다.
- 종료 시간이 올바른지 확인합니다.
- 시작 시간이 올바르고 종료 시간보다 이전인지 확인합니다. 시작 시간이 누락되었거나 형식이 잘못된 경우 API는 시작 시간을 종료 시간으로 설정합니다. GAUGE 측정항목의 경우 이 시간 간격은 시작 및 종료 시간이 간격의 종료 시간과 정확히 같은 포인트와만 일치합니다. 시간 간격에 대해 측정하는 CUMULATIVE 또는 DELTA 측정항목의 경우 일치하는 포인트가 없습니다. 자세한 내용은 시간 간격을 참조하세요.

API 재시도 오류

두 개의 Cloud API 오류 코드는 요청을 재시도하는 것이 유용할 수 있는 상황을 나타냅니다.

503 UNAVAILABLE: 문제가 단기적이거나 일시적인 상태인 경우 재시도가 유용합니다.
429 RESOURCE_EXHAUSTED: 재시도는 지연 후 n초당 n회 호출과 같은 시간 기반 할당량이 있는 장기 실행 백그라운드 작업에 유용합니다. 단기 또는 일시적인 조건이거나 볼륨 기반 할당량을 소진한 경우 재시도가 유용하지 않습니다. 일시적인 상황일 때는 오류를 허용하는 것이 좋습니다. 할당량 관련 문제의 경우 할당량 사용을 줄이거나 할당량 상향 조정을 요청하세요.

요청을 재시도할 수 있는 코드를 작성할 때는 먼저 요청이 안전하게 재시도되는지 확인하세요.

재시도하기에 요청이 안전한가요?

요청이 멱등성을 갖는 경우에는 재시도하는 것이 안전합니다. 멱등성 작업은 상태 변경이 현재 상태에 종속되지 않는 작업입니다. 예를 들면 다음과 같습니다.

x 읽기는 멱등성을 가집니다. 값이 변경되지 않습니다.
x를 10으로 설정하면 멱등성을 가집니다. 값이 10이 아닌 경우 상태를 변경할 수 있지만 현재 값은 중요하지 않습니다. 값을 설정하려고 하는 횟수가 중요하지 않습니다.
x를 늘리는 것은 멱등성을 갖지 않습니다. 새 값은 현재 값에 따라 다릅니다.

지수 백오프로 재시도

요청을 재시도하는 코드를 구현할 때는 새 요청을 무기한 빠르게 실행하는 것이 바람직하지 않습니다. 시스템이 오버로드되었으면 이 방식을 사용하면 문제의 원인이 됩니다.

대신 잘린 지수 백오프 방식을 사용하세요. 실제 사용 불능이 아닌 일시적인 과부하로 인해 요청이 실패하면 해결 방법은 부하를 줄이는 것입니다. 잘린 지수 백오프는 다음과 같은 일반 패턴을 따릅니다.

재시도할 때까지 대기하는 시간이나 실행하려는 횟수를 지정합니다. 이 한도를 초과하면 서비스를 사용할 수 없는 것으로 간주하고 이러한 조건을 애플리케이션에 따라 적절히 처리하세요. 이것이 백오프가 잘리는 이유이며, 일정 시점에서 재시도를 중지합니다.
재시도 빈도를 백오프하기 위해 점점 더 긴 일시중지로 요청을 재시도합니다. 요청이 성공하거나 지정된 한도에 도달할 때까지 재시도합니다.

간격은 일반적으로 재시도 횟수의 거듭제곱 함수로 증가하여 지수 백오프가 됩니다.

지수 백오프를 구현하는 방법에는 여러 가지가 있습니다. 다음은 최소 지연 1000ms에 증가하는 백오프 지연을 추가하는 예시입니다. 초기 백오프 지연은 2ms이며 각 시도마다 2^retry_countms로 증가합니다.

다음 표에서는 초기 값을 사용한 재시도 간격을 보여줍니다.

최소 지연 시간 = 1초 = 1000ms
초기 백오프 = 2ms

재시도 횟수	추가 지연(ms)	이후 재시도(ms)
0	2⁰ = 1	1001
1	2¹ = 2	1002
2	2² = 4	1004
3	2³ = 8	1008
4	2⁴ = 16	1016
...	...	...
n	2ⁿ	1000 + 2ⁿ

n회 시도 후 또는 시간이 애플리케이션에 합당한 값을 초과하는 경우 중지하여 재시도 주기를 자를 수 있습니다.

자세한 내용은 Wikipedia 문서 지수 백오프를 참조하세요.