排解 Monitoring API 問題

如要診斷 API 錯誤、修正指標擷取遭拒的問題，以及解決使用 Monitoring API 時查詢結果缺漏的問題，請參閱本指南中的疑難排解技巧和錯誤解決方法。

Monitoring API 是 Cloud API 的一部分。 如需共用錯誤代碼清單和一般處理建議，請參閱「處理錯誤」。

使用 API Explorer 進行偵錯

APIs Explorer 是內建於 API 方法參考資料頁面的小工具。您只要填寫欄位即可叫用方法，不必編寫程式碼。

如果方法呼叫發生問題，請使用該方法參考資料頁面上的 APIs Explorer (「Try this API」) 小工具，偵錯問題。詳情請參閱 API Explorer。

一般 API 和驗證錯誤

本節列出各種 Monitoring API 方法可能傳回的錯誤代碼。

401 UNAUTHENTICATED

401 UNAUTHENTICATED 錯誤代碼表示 OAuth2 或 IAM 憑證缺漏、過期或無效。

這個錯誤代碼的兩個常見錯誤訊息為 Request is missing required authentication credential 和 User is not authorized to access the project (or metric)。

  • 原因：缺少 Authorization: Bearer <token> 標頭、OAuth2 或 OIDC 權杖過期，或服務帳戶憑證無效。
  • 解決方法：使用應用程式預設憑證 (ADC) 或 gcloud auth print-access-token 重新整理驗證權杖。此外，請確認服務帳戶金鑰是否有效。
如果您未使用 APIs Explorer，請試用。如果 API 呼叫在 APIs Explorer 中運作正常，您發出 API 呼叫的環境可能存在授權問題。前往 API 管理頁面，確認專案已啟用 Monitoring API。

403 PERMISSION_DENIED，以存取專案和帳單

403 PERMISSION_DENIED 錯誤代碼表示您沒有執行要求動作的必要權限。

這個錯誤代碼可能會搭配多種不同的錯誤訊息。常見的錯誤訊息有兩種： Billing check failed for project [PROJECT_ID]和 Billing account disabled：

  • 原因：專案的 Cloud Billing 已停用或暫停。Google Cloud 如要擷取自訂指標，必須有運作中的帳單帳戶。
  • 解決方法：在 Google Cloud 控制台中，將有效的 Cloud Billing 帳戶連結至專案。

如果在寫入指標資料時收到這個錯誤代碼，請參閱「403 PERMISSION_DENIED 寫入指標資料時」一節。

404 NOT_FOUND

404 NOT_FOUND 錯誤代碼表示目標專案 ID 不存在，或系統無法辨識區域或位置。

以下列出這個錯誤代碼的常見錯誤訊息：

  • Project [PROJECT_ID] not found

    • 原因：要求 URI 中指定的專案不存在或已遭刪除。
    • 解決方法：檢查專案 ID 的拼字，並確認專案在 Google Cloud 控制台中處於啟用狀態。

  • Unavailable region or location 或 Unrecognized region or location

    • 原因：受監控的資源位置或區域標籤無效或無法辨識。
    • 解決方法：使用有效的 Google Cloud 區域和可用區名稱，例如 us-central1 或 us-central1-a。

  • The requested URL was not found on this server

    • 原因：網址中的資源路徑有誤。
    • 解決方法：請比較網址與方法參考頁面顯示的方法網址。這項錯誤可能表示有拼字錯誤 (例如「project」而非「projects」)，或是大小寫錯誤 (例如「TimeSeries」而非「timeSeries」)。

500 INTERNAL、503 UNAVAILABLE、504 DEADLINE_EXCEEDED

這些錯誤代碼有兩種常見的錯誤訊息：Internal error encountered. Please retry after a few seconds 和 The service is currently unavailable。

  • 原因：後端基礎架構發生暫時性錯誤、網路問題，或是內部資料庫分割區重新平衡。
  • 解決方法：在重試時實作截斷的指數輪詢，並加入隨機延遲，從 1 秒開始，最長可達 32 秒。將 RPC 用戶端期限設為 15 秒以上。 詳情請參閱「重試 API 錯誤」。

缺少結果

如果 API 呼叫傳回狀態碼 200 和空白回應，請考慮下列事項：

  • 如果通話使用篩選器，篩選器可能沒有比對到任何內容。篩選器比對會區分大小寫。如要解決篩選器問題，請先只指定一個篩選器元件 (例如 metric.type)，並確認是否能取得結果。逐一新增其他篩選器元件，建構要求。
  • 使用自訂指標時，請確認已指定定義指標的專案。

使用 timeSeries.list 方法時，資料點可能會遺漏，原因如下：

  • 資料可能已過時。 詳情請參閱「資料保留」。

  • 資料可能尚未傳播至監控服務。 詳情請參閱「指標資料的延遲時間」。

  • 間隔無效：

    • 確認結束時間是否正確。
    • 確認開始時間正確無誤，且早於結束時間。如果缺少開始時間或格式錯誤，API 會將開始時間設為結束時間。如果是 GAUGE 指標，這個時間間隔只會比對開始和結束時間完全符合間隔結束時間的點。如果是評估時間間隔的 CUMULATIVE 或 DELTA 指標，系統不會比對任何點。詳情請參閱「時間間隔」。

查詢指標資料時發生錯誤

本節提供相關資訊，說明使用 timeSeries.list 方法等方式讀取指標資料時可能發生的錯誤。

400 INVALID_ARGUMENT 查詢指標資料時

400 INVALID_ARGUMENT 錯誤代碼表示發生某種用戶端驗證錯誤。與錯誤代碼相關聯的錯誤訊息會提供更詳細的資訊，且適用於特定 API 方法。

舉例來說，查詢指標資料時，您可能會收到下列訊息：

  • Field filter had an invalid value 或 Field filter had an invalid value of "[FILTER]": [EXPLANATION]

    • 原因：表示監控篩選器有問題。
    • 解決方法：如要解決這個問題，請檢查篩選器的拼字和格式。詳情請參閱「監控篩選器」。

  • Request was missing field interval.endTime 或 Field interval.endTime had an invalid value

    • 原因：表示要求缺少結束時間，或值格式有誤。

    • 解決方法：如果您使用 API Explorer，請勿為時間欄位的值加上引號。有效格式包括：

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

寫入指標資料時發生錯誤

本節提供使用 timeSeries.create 方法寫入指標資料時可能發生的錯誤相關資訊，包括：

  • 錯誤代碼摘要。
  • 與各個錯誤代碼相關的錯誤訊息清單。這些項目包含原因和解決資訊。一般 API 錯誤也適用於 create 方法。

如果未啟用 Monitoring 的資料存取稽核記錄，timeSeries.create 方法的失敗情形可能不會顯示。不過，您可以採取下列行動：

  • 使用 Metrics Explorer 取得錯誤率相關資訊。請使用下列設定：

    • 指標： monitoring.googleapis.com/api/request_count
    • 篩選器： method = "google.monitoring.v3.MetricService.CreateTimeSeries"
    • 匯總：按 response_code 分組

  • 使用 Logs Explorer 查詢管理員活動記錄。系統嘗試自動建立指標描述元時，如果該動作失敗，就會建立這類記錄。如要查看這些記錄項目，請將 PROJECT_ID 替換為專案 ID，然後執行下列查詢： Google Cloud 

    logName="projects/PROJECT_ID/logs/cloudaudit.googleapis.com%2Factivity"
protoPayload.serviceName="monitoring.googleapis.com"
protoPayload.methodName="google.monitoring.v3.MetricService.CreateMetricDescriptor"
severity>=ERROR

  • 使用 Logs Explorer 查詢用戶端記錄。

如果您為 Cloud Monitoring 啟用資料存取稽核記錄，系統就會為每次資料存取作業寫入記錄項目。具體來說，這些記錄項目包含無法寫入的點數，以及失敗原因的詳細資料：

  • 如要瞭解如何啟用資料存取稽核記錄，請參閱「設定資料存取稽核記錄」。

  • 如要查看這些記錄項目，請使用Logs Explorer，並在將 PROJECT_ID 取代為Google Cloud 專案 ID 後執行下列查詢：

    logName="projects/PROJECT_ID/logs/cloudaudit.googleapis.com%2Fdata_access"
protoPayload.serviceName="monitoring.googleapis.com"
protoPayload.methodName="google.monitoring.v3.MetricService.CreateTimeSeries"
severity>=ERROR

timeSeries.create 錯誤代碼摘要

HTTP 代碼 gRPC 狀態碼 主要原因
400 INVALID_ARGUMENT 酬載驗證失敗 - 批量大小、標籤大小或金鑰、時間戳記排序、結構定義或類型不符、分配直方圖結構。
400 FAILED_PRECONDITION 超過取樣率、不支援的指標類型，或在保留期限外延遲抵達。
401 UNAUTHENTICATED 缺少、過期或無效的 OAuth2 或 IAM 憑證。
403 PERMISSION_DENIED 缺少 roles/monitoring.metricWriter IAM 角色、Cloud Billing 已停用，或未經授權嘗試寫入保留的系統指標網域。
404 NOT_FOUND 目標專案 ID 不存在，或無法辨識區域/位置。
429 RESOURCE_EXHAUSTED 監控資源超出有效時間序列基數限制、達到專案指標描述元限制，或超出 API 要求比率限制。
500 INTERNAL 內部儲存空間或結構定義服務故障。
503 UNAVAILABLE 後端服務暫時無法使用。
504 DEADLINE_EXCEEDED 要求逾時，因此無法將資料點寫入儲存節點。

400 INVALID_ARGUMENT 寫入指標資料時

400 INVALID_ARGUMENT 表示要求結構、指標中繼資料、標籤定義、時間戳記對齊或點值發生用戶端驗證錯誤。

要求結構和批次處理違規

以下列出與結構和批次處理違規事項相關的錯誤訊息：

  • Request was missing field timeSeries

    • 原因：要求中的 time_series 陣列為空白。
    • 解決方法：在每個要求中加入至少一個 TimeSeries 物件。

  • The maximum number of TimeSeries objects per Create request is 200

    • 原因：要求包含超過 200 個 TimeSeries 物件。
    • 解決方法：每個要求批次寫入的時間序列不得超過 200 個。

  • Field points had an invalid value: Only one point can be written per TimeSeries per request

    • 原因：單一 TimeSeries 物件的 points 欄位包含多個項目。
    • 解決方法：每個要求中，每個 TimeSeries 物件只能提供一個 Point。如要為同一項指標在不同時間點寫入多個資料點，請分別傳送要求。

  • Duplicate TimeSeries encountered. Only one point can be written per TimeSeries per request

    • 原因：同一要求中的兩個以上 TimeSeries 物件共用相同的指標類型、指標標籤和受監控資源標籤。
    • 解決方法：在用戶端批次中移除重複的時間序列，確保每個要求最多只會出現一次不重複的時間序列。

  • user defined metrics are not supported on the metric domain "[DOMAIN]"

    • 原因：指定網域不支援使用者定義的指標。
    • 解決方法：無。

標籤和命名限制

以下列出與標籤和命名限制相關的錯誤訊息：

  • Field metric.labels had an invalid value of "[KEY]": Label value exceeds the maximum string size of 1024 characters

    • 原因：指標或資源標籤值超過 1024 個字元。
    • 解決方法：將收集器或應用程式設定為將標籤值截斷至 1024 個半形字元以內。請避免在指標標籤中儲存大量文字，改為將這些詳細資料寫入 Cloud Logging。

  • Field metric.labels had an invalid value of "[KEY]": Label key contains invalid characters

    • 原因：標籤鍵包含允許模式以外的字元。 鍵可包含英數字元和底線，長度不得超過 100 個字元，且開頭須為英文字母。
    • 解決方法：重新命名標籤鍵，只使用有效字元。

  • The metric type must be a URL-formatted string with a domain and non-empty path

    • 原因：metric.type 格式錯誤或缺少網域前置字元。
    • 解決方法：將自訂指標類型格式設為 custom.googleapis.com/<category>/<name> 或 workload.googleapis.com/<name>。

  • Field metric.labels had an invalid value: The metric [METRIC_NAME] has more than [LIMIT] labels

    • 原因：自訂指標描述元的標籤數量超過 30 個，或是 Prometheus 指標的標籤數量超過 200 個。
    • 解決方法：移除不必要的標籤，確保描述元不超過限制。

  • unrecognized metric label "[LABEL_KEY]"

    • 原因：指標描述元已存在，但要求提供的標籤鍵未在描述元中定義。
    • 解決方法：確認標籤鍵與現有 MetricDescriptor 相符，或在需要修改結構定義時建立新的指標描述元。

專案和資源 ID 不符

以下列出與專案和資源 ID 不符相關的錯誤訊息：

  • Field resource.labels.project_id had an invalid value of "[VAL]": if present, must be the project number or ID in the request name ([PROJECT]) 或 Field resource.labels.project_id had an invalid value of "[VAL]": if present, must be the resource container ID in the request name [PROJECT]

    • 原因：resource.labels 中指定的 project_id 或 resource_container 標籤，與要求名稱中的專案 ID 或編號不符。
    • 解決方法：將資源 project_id 標籤設為與要求專案相符，或從 resource.labels 中省略 project_id 標籤，讓系統預設為要求專案。

  • unrecognized resource type "[RESOURCE_TYPE]"或missing resource type

    • 原因：Cloud Monitoring 無法辨識 resource.type，或非自訂指標省略了。
    • 解決方法：使用有效的受監控資源類型，例如 gce_instance、k8s_container、generic_task 或 global。

時間戳記和間隔

以下列出與時間戳記和間隔相關的錯誤訊息：

  • Points must be written in order. One or more of the points specified had an older end time than the most recent point

    • 原因：資料點的 end_time 早於或等於先前為該時間序列擷取的最新資料點時間戳記。
    • 解決方法：嚴格按照時間順序擷取點。

  • Field points[0].interval.start_time had an invalid value of "[START]": The start time must be equal to the end time ([END]) for the gauge metric '[METRIC]'

    • 原因：提交的 GAUGE 指標點中，start_time 不等於 end_time。
    • 解析度：針對 GAUGE 指標，請將 start_time 設為等於 end_time，或省略 start_time。

  • Field points[0].interval.start_time had an invalid value of "[START]": The start time must be before the end time ([END]) for the non-gauge metric '[METRIC]'

    • 原因：CUMULATIVE 或 DELTA 指標點的值大於或等於 end_time 值。start_time
    • 解決方法：請確認 start_time 值小於 end_time 值，且代表非零的時間間隔。

  • Field points[0].interval.end_time had an invalid value of "[TIME]": Data points cannot be written more than 5m into the future.

    • 原因：Point 的時間戳記比目前的伺服器時間快 5 分鐘以上。
    • 解決方法：將系統時鐘與 Google Public NTP (time.google.com) 同步。

  • Field points[0].interval.end_time had an invalid value of "[TIME]": Data points cannot be written more than approximately 24 hours in the past

    • 原因：資料點的時間戳記早於記憶體內保留期限 (24 小時)。
    • 解決方法：在產生資料後 24 小時內寫入即時資料。

值類型和分布情形

以下列出與值類型和分配相關的錯誤訊息：

  • value type for metric must be [EXPECTED], but is [ACTUAL]或metric kind for metric must be [EXPECTED], but is [ACTUAL]

    • 原因：傳入的值類型 (INT64、DOUBLE、STRING、BOOL、DISTRIBUTION) 或指標種類 (GAUGE、DELTA、CUMULATIVE) 與現有的 MetricDescriptor 衝突。
    • 解決方法：確認資料類型與現有描述符相符。值類型和指標種類建立後即無法修改。

  • Field points[0].value had an invalid value: The metric value exceeds the maximum string size of 1024 characters

    • 原因：STRING 值類型指標點超過 1024 個字元。
    • 解決方法：將字串指標值截斷為 1024 個半形字元以內，或改為將記錄傳送至 Cloud Logging。

  • Field points[0].value had an invalid value: Bucket options must be specified for Distribution metric

    • 原因：DISTRIBUTION 點未指定 bucket_options。
    • 解決方法：為分佈指標定義 linear_buckets、exponential_buckets 或 explicit_buckets。

  • Field points[0].value.distributionValue had an invalid value: Distribution value has |bucket_counts| fields that sum to X which does not equal the |count| field value of Y

    • 原因：bucket_counts 中的計數總和不等於 count 欄位。
    • 解決方法：請確認所有值區計數的總和等於樣本 count。

  • Field points[0].value had an invalid value: Distribution metric has too many buckets

    • 原因：直方圖值區數量超過 200 個。
    • 解析度：調整 bucket 參數，將 bucket 總數維持在 200 個以下。

400 FAILED_PRECONDITION

以下列出與這個錯誤代碼相關的錯誤訊息：

  • One or more points were written more frequently than the maximum sampling period configured for the metric

    • 原因：提交相同時間序列的資料點時，速度超過允許的上限 (每 5 秒一個資料點)。
    • 解決方法：限制擷取速率，確保特定時間序列的連續資料點間隔至少 5 秒。

  • ingestion of prometheus delta metrics is not supported in this API

    • 原因：要求嘗試透過 timeSeries.create 寫入 Prometheus DELTA 指標。
    • 解決方法：使用 Prometheus GAUGE 或 CUMULATIVE 指標，或透過 Google Cloud Managed Service for Prometheus OTLP 端點擷取指標。

  • One or more points arrived late outside of its aggregation window

    • 原因：點數在收集匯總指標的匯總時間範圍後才送達。
    • 解決方式：清除並串流緩衝延遲較低的點。

403 PERMISSION_DENIED 寫入指標資料時

寫入指標資料時，您可能會收到 403 PERMISSION_DENIED 回應，原因與專案存取權和帳單有關，也可能與下列原因有關：

  • Permission monitoring.timeSeries.create denied on resource (or it may not exist)

    • 原因：呼叫端沒有目標專案的 monitoring.timeSeries.create 權限。
    • 解決方法：將 Monitoring Metric Writer 角色 (roles/monitoring.metricWriter) 授予服務帳戶或主體。

  • Billing check failed for project [PROJECT_ID]或Billing account disabled

    • 原因：專案的 Cloud Billing 已停用或暫停。Google Cloud 如要擷取自訂指標，必須有運作中的帳單帳戶。
    • 解決方法：在 Google Cloud 控制台中，將有效的 Cloud Billing 帳戶連結至專案。

  • User does not have permission to write to metric [METRIC]

    • 原因：呼叫端嘗試將自訂指標直接寫入系統保留的網域，例如 compute.googleapis.com 或 storage.googleapis.com。
    • 解決方法：使用自訂指標網域，例如 custom.googleapis.com/ 或 workload.googleapis.com/。

429 RESOURCE_EXHAUSTED

以下列出與這個錯誤代碼相關的錯誤訊息：

  • Monitored resource ([RESOURCE_ID]) has too many time series (custom metrics)

    • 原因： 超過有效時間序列限制 (高基數)。 單一受監控資源的有效時間序列數量，在 24 小時內超過 20 萬個有效序列的上限。如果是 Prometheus 指標，有效序列的上限為 1,000,000 個。通常是因為流失資源的指標標籤中包含暫時性 ID，例如容器 ID、Pod UUID、要求 ID、使用者 ID 或時間戳記。
    • 解決方法：
      • 從指標中移除暫時性或高基數標籤。
      • 如要追蹤個別暫時性工作的指標，請使用 generic_task 受監控的資源類型，而非 dataflow_job 等資源專屬類型。將臨時 ID 對應至 generic_task 資源的 task_id 標籤。

  • Your Metric Ingestion quota has been exhausted

    • 原因：專案超過 API 擷取頻率配額。
    • 解決方法：批次寫入時間序列時，每個要求最多可寫入 200 個序列，或前往 Google Cloud 控制台的「配額」頁面申請提高配額。

  • Your Metric Descriptors quota has been exhausted

    • 原因：專案的自訂指標描述元數量已達上限 (每個專案 10,000 個)。如果是 Prometheus 指標，每個專案的上限為 25,000 個。
    • 解決方法：使用 projects.metricDescriptors.delete 刪除未使用的指標描述元，或減少動態指標命名。

  • Rate of metric descriptor creation exceeded

    • 原因：專案嘗試建立新指標描述元的速率，超過每項專案每分鐘 6,000 個。
    • 解決方法：請避免在資料擷取期間動態建立新的指標類型，並盡可能預先建立描述元。

重試 API 錯誤

有兩個 Cloud API 錯誤代碼表示可能需要重試要求：

  • 503 UNAVAILABLE：如果問題是短暫或暫時的狀況，重試會很有幫助。
  • 429 RESOURCE_EXHAUSTED：對於有時間配額的長時間背景工作 (例如每 t 秒 n 次呼叫)，延遲後重試很有用。如果問題是短暫或暫時性狀況，或是您已用盡以量為準的配額，重試就沒有用。如果是暫時性狀況，請考慮容許失敗。如要解決配額相關問題，請考慮減少配額用量或申請提高配額。

編寫可能會重試要求的程式碼時，請先確認要求是否可安全重試。

重試要求是否安全？

如果要求是等冪，可以放心重試。等冪動作是指狀態的任何變更都不取決於目前狀態。例如：

  • 讀取 x 是等冪運算，值不會變更。
  • 將 x 設為 10 是等冪運算，如果值不是 10，這可能會變更狀態，但目前的值為何並不重要。嘗試設定值的次數也不重要。
  • 遞增 x「並非等冪，新值取決於目前的值。

以指數輪詢方式重試

實作程式碼來重試要求時，請勿無限期快速發出新要求。如果系統負載過重，這種做法會加劇問題。

請改用部分指數輪詢方法。如果要求因暫時超載而失敗，而非真正無法使用，解決方法是降低負載。部分指數輪詢的一般模式如下：

  • 請決定重試時願意等待的時間長度，或願意嘗試的次數。超過這項限制時，請將服務視為無法使用，並為應用程式適當處理該情況。這就是導致退避截斷的原因，因為您會在某個時間點停止重試。

  • 請重試要求，並逐漸延長暫停時間，以減少重試頻率。請重試，直到要求成功或達到設定的限制為止。

    間隔通常會根據重試次數的冪次以某種函式增加，因此是「指數」輪詢。

實作指數輪詢的方法有很多種。以下範例會將輪詢延遲時間增加至至少 1000 毫秒。初始輪詢延遲時間為 2 毫秒，每次嘗試都會增加至 2retry_count 毫秒。

下表顯示使用初始值的重試間隔：

  • 最短延遲時間 = 1 秒 = 1000 毫秒
  • 初始輪詢時間 = 2 毫秒
重試次數 額外延遲 (毫秒) 重試時間 (毫秒)
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 次後停止，或是在時間超過應用程式的合理值時停止。

詳情請參閱維基百科的「指數輪詢」一文。