排解 Monitoring API 問題

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

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

一般 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 重新整理驗證權杖。此外，請確認服務帳戶金鑰是否有效。

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

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

    • 解決方法：確認 endTime 欄位的格式。有效格式包括：

      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 方法的失敗情形可能不會顯示。不過，您可以採取下列行動：

  • 使用 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 次後停止，或是在時間超過應用程式的合理值時停止。

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