使用 gRPC 用戶端指標

本頁說明如何使用 gRPC 與 Cloud Storage 互動時，透過下列支援的介面發出 gRPC 用戶端指標至 Cloud Monitoring：

您可以使用用戶端指標，監控透過 gRPC 與 Cloud Storage 互動的用戶端應用程式效能。用戶端指標與伺服器端指標不同，後者可從伺服器端角度深入瞭解 Cloud Storage 效能。

運作方式

使用 gRPC 透過其中一個支援的介面與 Cloud Storage 互動時，您可以選擇將用戶端指標傳送至 Cloud Monitoring。

定價

Cloud Storage 用戶端指標不會產生費用，也就是說，您可以發出、儲存及存取 Cloud Storage 用戶端指標，而不會產生 Cloud Monitoring 費用。如要進一步瞭解定價，請參閱 Google Cloud Observability 定價。

事前準備

如要使用用戶端指標，請先完成下列步驟：

  1. 確認您要使用的 Cloud Storage 用戶端程式庫或連接器支援 gRPC。下列 Cloud Storage 用戶端程式庫和連接器支援 gRPC：

  2. 設定驗證。

  3. 啟用 Cloud Monitoring API。

  4. 啟用 Cloud Storage API。

    前往 Cloud Storage API

  5. 設定發出用戶端指標所需的角色和權限。

必要的角色

如要設定權限，將 gRPC 用戶端指標傳送至 Cloud Monitoring，請在 gRPC 用戶端使用的服務帳戶中，授予「監控指標寫入者」(roles/monitoring.metricWriter) IAM 角色。

這個預先定義的角色具備將 gRPC 用戶端指標發布至 Cloud Monitoring 所需的權限。如要查看確切的必要權限，請參閱「必要權限」一節：

所需權限

  • monitoring.timeSeries.create

下列 Cloud Storage 預先定義的角色具備這項 IAM 權限：

您或許還可透過其他自訂角色或預先定義的角色取得這些權限。如要進一步瞭解 Monitoring Metric Writer 角色，請參閱有關 roles/monitoring.metricWriter 的 IAM 說明文件。

指標說明

以下各節將說明 Cloud Storage 用戶端指標，可用於監控 gRPC 用戶端的效能。

用戶端每次嘗試指標

下列指標會收集用戶端與伺服器通訊時，個別嘗試的效能資料。您可以透過每次嘗試的用戶端指標，評估重試行為、瓶頸，以及最佳化用戶端與伺服器之間的通訊。

完整指標 說明 付款方式類型 單位 屬性
storage.googleapis.com/client/grpc/client/attempt/started Preview。啟動的 RPC 嘗試總數，包括尚未完成的嘗試。 計數器 {attempt}
  • grpc.method：完整的 gRPC 方法名稱，包括套件、服務和方法。
  • grpc.target：建立 gRPC 管道時使用的標準化目標 URI。
storage.googleapis.com/client/grpc/client/attempt/duration Preview。完成遠端程序呼叫 (RPC) 嘗試的端對端時間，包括挑選子通道所需的時間。 直方圖 s
  • grpc.method：完整的 gRPC 方法名稱，包括套件、服務和方法。
  • grpc.target：建立 gRPC 管道時使用的標準化目標 URI。
  • grpc.status：收到的 gRPC 伺服器狀態碼，例如 OK、CANCELLED 或 DEADLINE_EXCEEDED。
  • grpc.lb.locality：流量傳送至的地區。這會設為從 weighted_target 政策傳遞下來的解析器屬性，如果解析器屬性未設定，則會設為空字串。
storage.googleapis.com/client/grpc/client/attempt/sent_total_compressed_message_size Preview。所有要求訊息 (中繼資料除外) 在每次 RPC 嘗試中傳送的總位元組數 (已壓縮但未加密)。這不包括 gRPC 或傳輸框架位元組。 直方圖 By
  • grpc.method：完整的 gRPC 方法名稱，包括套件、服務和方法。
  • grpc.target：建立 gRPC 管道時使用的標準化目標 URI。
  • grpc.status：收到的 gRPC 伺服器狀態碼，例如 OK、CANCELLED 或 DEADLINE_EXCEEDED。
  • grpc.lb.locality：流量傳送至的地區。這會設為從 weighted_target 政策向下傳遞的解析器屬性，如果解析器屬性未設定，則會設為空字串。
storage.googleapis.com/client/grpc/client/attempt/rcvd_total_compressed_message_size Preview。所有回應訊息 (不含每個 RPC 嘗試的中繼資料) 收到的總位元組數 (已壓縮但未加密)。這不包括 gRPC 或傳輸框架位元組。 直方圖 By
  • grpc.method：完整的 gRPC 方法名稱，包括套件、服務和方法。
  • grpc.target：建立 gRPC 管道時使用的標準化目標 URI。
  • grpc.status：收到的 gRPC 伺服器狀態碼，例如 OK、CANCELLED 或 DEADLINE_EXCEEDED。
  • grpc.lb.locality：流量傳送目的地所在的位置。這項屬性會設為從 weighted_target 政策傳遞下來的解析器屬性，如果解析器屬性未設定，則會設為空字串。

如要進一步瞭解用戶端每次嘗試的工具，請參閱 GitHub 中的 OpenTelemetry 指標說明文件。

用戶端通話指標

下列指標提供用戶端呼叫伺服器整個生命週期的匯總檢視畫面。用戶端通話指標提供用戶端通話的高階資料、追蹤指標 (有助於瞭解通話模式)，以及協助您找出錯誤的頻率。

完整指標 說明 付款方式類型 單位 屬性
storage.googleapis.com/client/grpc/client/call/duration Preview. 從應用程式的角度來看，測量 gRPC 程式庫完成 RPC 的端對端時間。 直方圖 s
  • grpc.method：完整的 gRPC 方法名稱，包括套件、服務和方法。
  • grpc.target：建立 gRPC 管道時使用的標準化目標 URI。
  • grpc.status：收到的 gRPC 伺服器狀態碼，例如 OK、CANCELLED 或 DEADLINE_EXCEEDED。

如要進一步瞭解用戶端每次呼叫的工具，請參閱 GitHub 上的 OpenTelemetry 指標說明文件。

要求負載感應指標

下列指標可深入瞭解用戶端應用程式使用要求負載感應功能的成效。要求負載感應指標可協助您平衡伺服器負載、提高資源使用率，以及縮短用戶端回應時間。只有直接連線才能使用下列指標。

完整指標 說明 付款方式類型 單位 屬性
storage.googleapis.com/client/grpc/lb/rls/cache_entries Preview。要求負載感應快取中的項目數。 度量圖 {entry}
  • grpc.target：指出 WRR 所用 gRPC 管道的目標。
  • grpc.lb.rls.server_target：要求負載感應伺服器通訊的目標 URI。
  • grpc.lb.rls.instance_uuid：個別要求負載感應用戶端執行個體的通用專屬 ID (UUID)。這個值本身沒有意義，但可用於區分要求負載感應用戶端執行個體，適用於同一 gRPC 通道中有多個執行個體，或有多個通道指向相同目標的情況。
storage.googleapis.com/client/grpc/lb/rls/cache_size Preview。要求負載感應快取的目前大小。 度量圖 By
  • grpc.target：WRR 使用的 gRPC 管道目標。
  • grpc.lb.rls.server_target：要求負載感應伺服器通訊的目標 URI。
  • grpc.lb.rls.instance_uuid：個別要求負載感應用戶端執行個體的 UUID。這個值本身沒有意義，但可用於區分要求負載感應用戶端執行個體，適用於同一 gRPC 通道中有多個執行個體，或有多個通道指向相同目標的情況。
storage.googleapis.com/client/grpc/lb/rls/default_target_picks Preview。傳送至預設目標的負載平衡器 (LB) 選取次數。 計數器 {pick}
  • grpc.target：指出使用要求負載感應的 gRPC 管道目標。
  • grpc.lb.rls.server_target：要求負載感應伺服器要通訊的目標 URI。
  • grpc.lb.rls.data_plane_target：要求負載感應功能使用的目標字串，用於轉送資料平面流量。這個值是由要求負載感應伺服器針對特定鍵傳回，或是設定為要求負載感應設定中的預設目標。
  • grpc.lb.pick_result：LB 挑選結果，例如 "complete"、"fail" 或 "drop"。
storage.googleapis.com/client/grpc/lb/rls/target_picks Preview：傳送至每個要求負載感應目標的 LB 選擇數。如果要求負載感應伺服器也傳回預設目標，從快取傳送至該目標的 RPC 會計入這項指標，而非 grpc.rls.default_target_picks。 計數器 {pick}
  • grpc.target：gRPC 管道的目標，要求負載感應功能會在此管道中使用。
  • grpc.lb.rls.server_target：要求負載感應伺服器要通訊的目標 URI。
  • grpc.lb.rls.data_plane_target：要求負載感應功能使用的目標字串，用於轉送資料平面流量。這個值是由特定鍵的要求負載感應伺服器傳回，或是設定為要求負載感應設定中的預設目標。
  • grpc.lb.pick_result：LB 挑選結果，例如 "complete"、"fail" 或 "drop"。
storage.googleapis.com/client/grpc/lb/rls/failed_picks Preview。由於要求負載感應要求失敗，或要求負載感應管道受到節流，導致 LB 選擇失敗的次數。 計數器 {pick}
  • grpc.target：gRPC 管道的目標，要求負載感應功能會在此管道中使用。
  • grpc.lb.rls.server_target：要求負載感應伺服器要通訊的目標 URI。

xDiscovery Service 用戶端指標

下列指標可提供深入分析資料，瞭解用戶端應用程式如何與 xDiscovery Service (xDS) 控制平面互動，以探索及設定與後端服務的連線。xDS 指標可協助您追蹤服務要求延遲時間、監控設定更新，以及提升整體 xDS 效能。

只有直接連線才能使用下列指標。

完整指標 說明 付款方式類型 單位 屬性
storage.googleapis.com/client/grpc/xds_client/connected Preview. 評估 xDS 用戶端是否具有可運作的 ADS 串流至 xDS 伺服器。對於特定伺服器，這個指標會在最初建立串流時設為 1。如果連線失敗，或 ADS 串流失敗但未顯示 A57 中的回應訊息，指標會設為 0。設為 0 後，當 ADS 串流收到第一個回應時，指標會重設為 1。這項指標僅適用於 C++ 的 Cloud 用戶端程式庫。 度量圖 {bool}
  • grpc.target：對於用戶端，表示 XdsClient 所用 gRPC 管道的目標。如果是伺服器，則為字串 "#server"。
  • grpc.xds.server：xDS 伺服器的目標 URI，XdsClient 會與該伺服器通訊。
storage.googleapis.com/client/grpc/xds_client/resource_updates_invalid Preview。系統判定為無效的資源數量。這項指標僅適用於 C++ 的 Cloud 用戶端程式庫。 計數器 {resource}
  • grpc.target：適用於用戶端，表示使用 XdsClient 的 gRPC 管道目標。如果是伺服器，則為字串 "#server"。
  • grpc.xds.server：XdsClient 通訊的 xDS 伺服器目標 URI。
  • grpc.xds.resource_type：表示 xDS 資源類型，例如 "envoy.config.listener.v3.Listener"。
storage.googleapis.com/client/grpc/xds_client/resource_updates_valid Preview。系統認為有效的資源數量，即使未變更也算在內。這項指標僅適用於 C++ 的 Cloud 用戶端程式庫。 計數器 {resource}
  • grpc.target：適用於用戶端，表示使用 XdsClient 的 gRPC 管道目標。如果是伺服器，則為字串 "#server"。
  • grpc.xds.server：XdsClient 與之通訊的 xDS 伺服器目標 URI。
  • grpc.xds.resource_type：表示 xDS 資源類型，例如 "envoy.config.listener.v3.Listener"。
storage.googleapis.com/client/grpc/xds_client/resources Preview。xDS 資源數量。這項指標僅適用於 C++ 的 Cloud 用戶端程式庫。 度量圖 {resource}
  • grpc.target：適用於用戶端，表示使用 XdsClient 的 gRPC 管道目標。如果是伺服器，則為字串 "#server"。
  • grpc.xds.authority：xDS 授權單位。在導入 xdstp:// URI 表示法之前，系統會為 xDS API 中識別的非 xdstp 資源名稱提供 "#old" 值。
  • grpc.xds.cache_state：表示 xDS 資源的快取狀態。
  • grpc.xds.resource_type 表示 xDS 資源類型，例如 "envoy.config.listener.v3.Listener"。
storage.googleapis.com/client/grpc/xds_client/server_failure Preview。不再正常運作的 xDS 伺服器數量，這些伺服器可能已無法使用、過載，或提供錯誤或無效的設定資料。這項指標僅適用於 C++ 的 Cloud 用戶端程式庫。 計數器 {failure}
  • grpc.target：xDS 伺服器的目標 URI，XdsClient 會與該伺服器通訊。
  • grpc.xds.server：對用戶端而言，這表示使用 XdsClient 的 gRPC 管道目標。如果是伺服器，則為字串 "#server"。

如要進一步瞭解 xDS 用戶端指標，請參閱 GitHub 的 xDS 架構全球負載平衡說明文件。

停用用戶端指標

您可以視需要停用用戶端指標。

Java

public GrpcStorageOptions.Builder setEnableGrpcClientMetrics(false enableGrpcClientMetrics)

詳情請參閱 Java 適用的 Cloud 用戶端程式庫類別 GrpcStorageOptions.Builder 方法，瞭解 gRPC 用戶端指標。

C++

如要使用 C++ 適用的 Cloud 用戶端程式庫，選擇不採用 gRPC API 的用戶端指標，請參閱結構體 EnableGrpcMetricsOption。

如果您使用 Bazel 建構應用程式，並想停用用戶端指標，請在應用程式的建構檔案中，將 enable_grpc_metrics 選項設為 false。