Monitoring API 문제해결

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

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

디버깅에 API 탐색기 사용

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

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

일반적인 API 오류

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

  • 404 NOT_FOUND

    • '서버에서 요청된 URL을 찾을 수 없습니다.': URL의 일부가 잘못되었습니다. URL을 메서드의 참조 페이지에 표시된 메서드의 URL과 비교하세요. 철자 오류('project' 대신 'projects')와 대소문자 문제('timeSeries' 대신 'TimeSeries')가 있는지 확인합니다.

    • '프로젝트/PROJECT_ID가 작업공간이 아닙니다': 이것은 사용 중인 Google Cloud 프로젝트가 Cloud Monitoring 작업공간의 일부가 아님을 의미합니다. 작업공간은 Google Cloud 프로젝트의 모니터링 정보를 구성하는 데 사용되며, 대부분의 Monitoring API 메서드는 작업공간의 일부여야 합니다. 자세한 내용은 작업공간을 참조하세요.

  • 401 UNAUTHENTICATED '사용자가 프로젝트(또는 측정항목)에 액세스할 권한이 없습니다.' 이는 승인 문제일 수 있지만 단순히 프로젝트 ID 또는 측정항목 유형 이름을 잘못 입력했음을 의미할 수도 있습니다. 맞춤법과 대소문자를 확인합니다.

    API 탐색기를 사용하지 않는 경우 사용해 보세요. API 호출이 API 탐색기에서 작동하는 경우 API 호출에 사용 중인 환경에 승인 문제가 있을 수 있습니다. API 관리자 페이지에서 프로젝트에 Monitoring API v3이 사용 설정되어 있는지 확인하세요.

  • 400 INVALID_ARGUMENT '필드 필터에 잘못된 값이 있습니다': Monitoring 필터의 맞춤법과 형식이 올바른지 확인합니다. 자세한 내용은 Monitoring 필터를 참조하세요.

  • 400 INVALID_ARGUMENT '요청에 interval.endTime 필드가 누락되었습니다': 종료 시간이 누락되었거나 존재하지만 형식이 올바르지 않은 경우 이 메시지가 표시됩니다. API 탐색기를 사용하는 경우 시간 필드의 값에 따옴표를 사용하지 않습니다.

    올바른 시간 사양의 예는 다음과 같습니다.

    2016-05-11T01:23:45Z
    2016-05-11T01:23:45.678Z
    2016-05-11T01:23:45.678+05:00
    2016-05-11T01:23:45.678-04:30
    

결과 누락

API 호출이 상태 코드 200 및 빈 응답을 반환하는 경우 다음과 같은 몇 가지 가능성이 있습니다.

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

  • 커스텀 측정항목을 사용하는 경우 커스텀 측정항목이 정의된 프로젝트를 지정하지 않았을 수 있습니다.

timeSeries.list를 사용하여 시계열 데이터를 가져오고 일부 데이터 포인트가 누락된 것으로 보이는 경우 다음과 같은 추가 원인을 확인합니다.

  • 데이터가 몇 주 이상 된 경우 만료되었을 수 있습니다. 자세한 내용은 데이터 보관을 참조하세요.

  • 데이터가 방금 기록되었다면 아직 Monitoring에 있지 않을 수 있습니다. 자세한 내용은 측정항목 데이터의 지연 시간을 참조하세요.

  • 시간 간격을 올바르게 지정했는지 확인합니다.

    • 종료 시간이 올바른지 확인합니다.
    • 시작 시간이 올바른지, 종료 시간보다 이전인지 확인합니다. 시작 시간이 누락되었거나 잘못된 형식인 경우 기본적으로 종료 시간 값으로 설정되며, 시간 간격은 시작 및 종료 시간이 간격의 종료 시간과 정확히 일치하는 포인트만 일치시킵니다. (특정 시점을 측정하는 GAUGE 측정항목에는 유효하지만 시간 간격에 대해 측정되는 CUMULATIVE 또는 DELTA 측정항목에는 유효하지 않음) 자세한 내용은 시간 간격을 참조하세요.

API 재시도 오류

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

  • 503 UNAVAILABLE: 문제가 일시적이거나 일시적인 상태인 경우 재시도가 유용합니다.
  • 429 RESOURCE_EXHAUSTED: 재시도는 지연 후 시간 기반 할당량이 있는 장기 실행 백그라운드 작업에만 유용합니다. 예를 들어 t초당 n 호출로 제한되는 경우입니다. 하지만 볼륨 기반 할당량을 소진했다면 재시도가 도움이 되지 않습니다. 이럴 때는 할당량을 늘려야 합니다.

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

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

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

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

지수 백오프로 다시 시도하세요.

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

대신 잘린 지수 백오프 방식을 사용합니다. True 사용 불능 상황이 아닌 일시적인 과부하로 인해 요청이 실패하는 경우 솔루션 부하가 줄어듭니다. 잘린 지수 백오프는 다음과 같은 일반적인 패턴을 따릅니다.

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

  • 재시도 빈도를 백오프하기 위해 점점 더 긴 일시중지로 요청을 재시도합니다. 요청이 성공하거나 지정된 한도에 도달할 때까지 재시도합니다.

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

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

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

  • 최소 지연 시간 = 1초 = 1000ms
  • 초기 백오프 = 2ms
재시도 횟수 추가 지연(ms) 이후 재시도(ms)
0 20 = 1 1001
1 21 = 2 1002
2 22 = 4 1004
3 23 = 8 1008
4 24 = 16 1016
... ... ...
n 2n 1000 + 2n

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

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