이 가이드에서는 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 탐색기를 사용하는 경우 시간 필드의 값에 따옴표를 사용하지 마세요.
호출에서 필터를 사용하는 경우 필터와 일치하는 항목이 없을 수 있습니다. 필터 일치는 대소문자를 구분합니다. 필터 문제를 해결하려면 먼저 metric.type과 같은 필터 구성요소를 하나만 지정하고 결과가 나오는지 확인합니다. 다른 필터 구성요소를 하나씩 추가하며 요청을 작성합니다.
데이터가 아직 Monitoring으로 전파되지 않았을 수 있습니다.
자세한 내용은 측정항목 데이터의 지연 시간을 참조하세요.
간격이 잘못되었습니다.
종료 시간이 올바른지 확인합니다.
시작 시간이 올바르고 종료 시간보다 이전인지 확인합니다. 시작 시간이 누락되었거나 형식이 잘못된 경우 API는 시작 시간을 종료 시간으로 설정합니다. GAUGE 측정항목의 경우 이 시간 간격은 시작 및 종료 시간이 간격의 종료 시간과 정확히 같은 포인트와만 일치합니다. 시간 간격에 대해 측정하는 CUMULATIVE 또는 DELTA 측정항목의 경우 일치하는 포인트가 없습니다.
자세한 내용은 시간 간격을 참조하세요.
API 재시도 오류
두 개의 Cloud API 오류 코드는 요청을 재시도하는 것이 유용할 수 있는 상황을 나타냅니다.
503 UNAVAILABLE: 문제가 단기적이거나 일시적인 상태인 경우 재시도가 유용합니다.
429 RESOURCE_EXHAUSTED: 재시도는 지연 후 n초당 n회 호출과 같은 시간 기반 할당량이 있는 장기 실행 백그라운드 작업에 유용합니다. 단기 또는 일시적인 조건이거나 볼륨 기반 할당량을 소진한 경우 재시도가 유용하지 않습니다. 일시적인 상황일 때는 오류를 허용하는 것이 좋습니다. 할당량 관련 문제의 경우 할당량 사용을 줄이거나 할당량 상향 조정을 요청하세요.
요청을 재시도할 수 있는 코드를 작성할 때는 먼저 요청이 안전하게 재시도되는지 확인하세요.
재시도하기에 요청이 안전한가요?
요청이 멱등성을 갖는 경우에는 재시도하는 것이 안전합니다. 멱등성 작업은 상태 변경이 현재 상태에 종속되지 않는 작업입니다.
예를 들면 다음과 같습니다.
x 읽기는 멱등성을 가집니다. 값이 변경되지 않습니다.
x를 10으로 설정하면 멱등성을 가집니다. 값이 10이 아닌 경우 상태를 변경할 수 있지만 현재 값은 중요하지 않습니다. 값을 설정하려고 하는 횟수가 중요하지 않습니다.
x를 늘리는 것은 멱등성을 갖지 않습니다. 새 값은 현재 값에 따라 다릅니다.
지수 백오프로 재시도
요청을 재시도하는 코드를 구현할 때는 새 요청을 무기한 빠르게 실행하는 것이 바람직하지 않습니다. 시스템이 오버로드되었으면 이 방식을 사용하면 문제의 원인이 됩니다.
대신 잘린 지수 백오프 방식을 사용하세요.
실제 사용 불능이 아닌 일시적인 과부하로 인해 요청이 실패하면 해결 방법은 부하를 줄이는 것입니다. 잘린 지수 백오프는 다음과 같은 일반 패턴을 따릅니다.
재시도할 때까지 대기하는 시간이나 실행하려는 횟수를 지정합니다. 이 한도를 초과하면 서비스를 사용할 수 없는 것으로 간주하고 이러한 조건을 애플리케이션에 따라 적절히 처리하세요. 이것이 백오프가 잘리는 이유이며, 일정 시점에서 재시도를 중지합니다.
재시도 빈도를 백오프하기 위해 점점 더 긴 일시중지로 요청을 재시도합니다. 요청이 성공하거나 지정된 한도에 도달할 때까지 재시도합니다.
간격은 일반적으로 재시도 횟수의 거듭제곱 함수로 증가하여 지수 백오프가 됩니다.
지수 백오프를 구현하는 방법에는 여러 가지가 있습니다.
다음은 최소 지연 1000ms에 증가하는 백오프 지연을 추가하는 예시입니다. 초기 백오프 지연은 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회 시도 후 또는 시간이 애플리케이션에 합당한 값을 초과하는 경우 중지하여 재시도 주기를 자를 수 있습니다.
[[["이해하기 쉬움","easyToUnderstand","thumb-up"],["문제가 해결됨","solvedMyProblem","thumb-up"],["기타","otherUp","thumb-up"]],[["이해하기 어려움","hardToUnderstand","thumb-down"],["잘못된 정보 또는 샘플 코드","incorrectInformationOrSampleCode","thumb-down"],["필요한 정보/샘플이 없음","missingTheInformationSamplesINeed","thumb-down"],["번역 문제","translationIssue","thumb-down"],["기타","otherDown","thumb-down"]],["최종 업데이트: 2025-09-03(UTC)"],[],[],null,["# Troubleshoot the Monitoring API\n\nThis guide explains some of the issues that might arise when you use\nthe Monitoring API.\n\nThe Monitoring API is one of the set of Cloud APIs.\nThese APIs share a common set of error codes. For a list of the error\ncodes defined by the Cloud APIs and general suggestions on\nhandling the errors, see [Handling errors](/apis/design/errors#handling_errors).\n\nUse APIs Explorer for debugging\n-------------------------------\n\nAPIs Explorer is a widget built into the reference pages for API methods.\nIt lets you invoke the method by filling out fields; it doesn't require you\nto write code.\n\nIf you are having trouble with a method invocation, use the APIs Explorer\n(**Try this API** ) widget on the reference page for that method to\ndebug your problem. For more information, see\n[APIs Explorer](/monitoring/api/apis-explorer).\n\nGeneral API errors\n------------------\n\nHere are some of the Monitoring API errors and messages you might\nsee from your API calls:\n\n- `404 NOT_FOUND` with \"The requested URL was not found on this server\":\n Some part of the URL is incorrect. Compare the URL against\n the URL for the method shown on the method's reference page.\n This error might mean that there is a spelling error,\n such as \"project\" instead of \"projects\", or a capitalization error,\n such as \"TimeSeries\" instead of \"timeSeries\".\n\n- `401 UNAUTHENTICATED` with \"User is not authorized to access the project\n (or metric)\": This error code typically indicate an authorization problem,\n but it can mean that there is an error in the project ID or metric type\n name. Verify the spelling and capitalization.\n\n\n If you aren't using APIs Explorer, then try using it. When your API\n call works in APIs Explorer, there is probably an authorization\n issue in the environment where you're making the API call. Go to the\n [API manager page](https://console.cloud.google.com/apis/enabled) to verify\n that the Monitoring API is enabled for your project.\n- `400 INVALID_ARGUMENT` with \"Field filter had an invalid value\": Verify the\n spelling and formatting of the monitoring filter. For more information, see\n [Monitoring Filters](/monitoring/api/v3/filters).\n\n- `400 INVALID_ARGUMENT` with \"Request was missing field interval.endTime\":\n You see this message when the end time missing, or when it is present but\n not properly formatted.\n If you are using APIs Explorer, then don't quote the value of the time\n field.\n\n\n Here are some examples of valid time specifications: \n\n ```\n 2024-05-11T01:23:45Z\n 2024-05-11T01:23:45.678Z\n 2024-05-11T01:23:45.678+05:00\n 2024-05-11T01:23:45.678-04:30\n ```\n\nMissing results\n---------------\n\nWhen an API call returns the status code `200` and an empty response, consider\nthe following:\n\n- When the call uses a filter, the filter might not have matched anything. The filter match is case-sensitive. To resolve filter problems, start by specifying only one filter component, such as `metric.type`, and verify that you get results. Add the other filter components one by one to build up your request.\n\n\u003c!-- --\u003e\n\n- When working with a custom metric, verify that that the project which defines the metric is specified.\n\nThere are several reasons why data points might be missing when you use the\n[`timeSeries.list`](/monitoring/api/ref_v3/rest/v3/projects.timeSeries/list) method:\n\n- The data might have aged out.\n For more information, see [Data retention](/monitoring/quotas#data_retention_policy).\n\n- The data might not have propagated to Monitoring yet.\n For more information, see [Latency of metric data](/monitoring/api/v3/latency-n-retention).\n\n- The interval is invalid:\n\n - Verify that the end time is correct.\n - Verify that the start time is correct and that it is earlier than the end time. When the start time is missing or malformed, the API sets the start-time to the end-time. For `GAUGE` metrics, this time interval only matches points whose start and end times are exactly the interval's end time. For `CUMULATIVE` or `DELTA` metrics, which measure across time intervals, no points are matched. For more information, see [Time intervals](/monitoring/custom-metrics/reading-metrics#time_intervals).\n\nRetrying API errors\n-------------------\n\nTwo of the Cloud APIs error codes indicate circumstances in\nwhich it might be useful to retry the request:\n\n- `503 UNAVAILABLE`: retries are useful when the problem is a short-lived or transient condition.\n- `429 RESOURCE_EXHAUSTED`: retries are useful, after a delay, for long-running background jobs with time-based quota such as *n* calls per *t* seconds. Retries aren't useful when the problem is a short-lived or transient condition, or when you've exhausted a volume-based quota. For transient conditions, consider tolerating the failure. For quota-related issues, consider reducing your quota usage or requesting a quota increase.\n\nWhen writing code that might retry requests, first ensure that the request\nis safe to retry.\n\n### Is the request safe to retry?\n\nIf your request is idempotent, then it is safe to retry. An *idempotent*\naction is one where any change in state does not depend on the current state.\nFor example:\n\n- Reading *x* is idempotent; there is no change to the value.\n- Setting *x* to 10 is idempotent; this might change the state, if the value isn't already 10, but it doesn't matter what the current value is. And it doesn't matter how many times you attempt to set the value.\n- Incrementing *x* is *not* idempotent; the new value depends on the current value.\n\n### Retry with exponential backoff\n\nWhen implementing code to retry requests, you don't want to rapidly issue\nnew requests indefinitely. If a system is overloaded, this approach\ncontributes to the problem.\n\nInstead, use a *truncated exponential backoff* approach.\nWhen requests fail because of transient overloads rather than true\nunavailability, the solution is reduce the load. A truncated exponential\nbackoff follows this general pattern:\n\n- Establish how long you are willing to wait while retrying or how\n many attempts you are willing to make. When this limit is exceeded,\n consider the service unavailable and handle that\n condition appropriately for your application. This is what makes\n the backoff *truncated*; you stop retrying at some point.\n\n- Retry the request with increasingly long pauses to *back off* the\n frequency of retries. Retry until the request succeeds or your\n established limit is reached.\n\n The interval is typically increased by some function of the power of\n the retry count, making it an *exponential* backoff.\n\nThere are many ways to implement an exponential backoff.\nThe following is an example that adds an increasing backoff delay\nto a minimum delay of 1000ms. The initial backoff delay is 2ms, and it\nincreases to 2^*retry_count*^ms with each attempt.\n\nThe following table shows the retry intervals using the initial values:\n\n- Minimum delay = 1s = 1000ms\n- Initial backoff = 2ms\n\nYou can truncate the retry cycle by stopping either after *n* attempts\nor when the time spent exceeds a reasonable value for your application.\n\nFor more information, see the Wikipedia article\n[Exponential backoff](https://en.wikipedia.org/wiki/Exponential_backoff)."]]
