使用者定義指標簡介

使用者定義指標是指不是由 Google Cloud定義的所有指標。 包括您定義的指標，以及第三方應用程式定義的指標。使用者定義的指標可擷取特定應用程式資料或用戶端系統資料。Cloud Monitoring 收集的內建指標可提供後端延遲或磁碟使用情形等資訊，但無法告知您應用程式產生的背景常式數量。

您也可以根據記錄項目內容建立指標。記錄指標是使用者定義指標的一種，但您必須從 Cloud Logging 建立這類指標。如要進一步瞭解記錄指標，請參閱「記錄指標總覽」一文。

使用者定義指標有時稱為自訂指標或應用程式專屬指標。您或第三方應用程式可透過這些指標，定義及收集內建 Cloud Monitoring 指標無法取得的資訊。您可以使用程式庫提供的 API 來擷取這類指標以便設定程式碼，接著將指標傳送到 Cloud Monitoring 等後端應用程式。

您可以直接使用 Cloud Monitoring API 建立使用者定義的指標 (記錄指標除外)。不過，我們建議使用 OpenTelemetry。如要瞭解如何建立使用者定義的指標，請參閱下列文件：

  • 「收集 OTLP 指標和追蹤記錄」一文說明如何使用 Ops Agent 和代理程式的 OpenTelemetry Protocol (OTLP) 接收器，從使用 OpenTelemetry 檢測並在 Compute Engine 上執行的應用程式收集指標和追蹤記錄。

  • Google Cloud Managed Service for Prometheus 說明如何從 Google Kubernetes Engine 和 Kubernetes 上執行的應用程式收集 Prometheus 指標。

  • 收集 Prometheus 指標一文說明如何使用作業套件代理程式，從 Compute Engine 上執行的應用程式收集 Prometheus 指標。

  • 使用 API 建立使用者定義的指標一文說明如何使用 Cloud Monitoring API 建立指標，以及如何將指標資料新增至這些指標。本文將說明如何使用 Monitoring API，並提供 API Explorer、C#、Go、Java、Node.js、PHP、Python 和 Ruby 程式設計語言的範例。

  • 在 Cloud Run 上建立自訂指標一文說明如何在 Cloud Run 部署作業中，將 OpenTelemetry Collector 做為 Sidecar 代理程式使用。

就 Cloud Monitoring 而言，使用者定義的指標使用方式如同內建指標：您可以為這些指標建立圖表、設定快訊、讀取指標，或加以監控。如要瞭解如何讀取指標資料，請參閱下列文件：

  • 列出指標和資源類型一文說明如何列出及檢查使用者定義和內建的指標類型。舉例來說，您可以使用該文件中的資訊，列出專案中所有使用者定義的指標描述元。
  • 擷取時間序列資料一文說明如何使用 Monitoring API 從指標擷取時間序列資料。舉例來說，本文說明如何使用 API 取得 Google Cloud 專案中虛擬機器 (VM) 執行個體的 CPU 使用率。

Google Cloud 控制台提供專屬頁面，方便您查看使用者定義指標的使用情況。如要瞭解這個頁面的內容，請參閱「查看及管理指標用量」。

使用者定義指標的指標描述元

每種指標類型都必須有指標描述元，用於定義指標資料的整理方式。指標描述元也會定義指標的標籤和指標名稱。舉例來說，指標清單會顯示所有內建指標類型的指標描述元。

Cloud Monitoring 可以使用您寫入的指標資料，為您建立指標描述元，您也可以明確建立指標描述元，然後寫入指標資料。無論是哪種情況，您都必須決定要如何整理指標資料。

設計範例

假設您有一個在單一機器上執行的程式，且該程式會呼叫輔助程式 A 和 B。您想計算程式 A 和 B 的呼叫頻率。您也想知道程式 A 每分鐘呼叫次數超過 10 次，以及程式 B 每分鐘呼叫次數超過 5 次時。最後，假設您有一個 Google Cloud 專案，並打算針對受監控的global資源寫入資料。

這個範例說明幾種可供使用者定義指標使用的設計：

  • 您會使用兩項指標：Metric-type-A 會計算對程式的呼叫次數，A 則會計算對程式 Metric-type-B 的呼叫次數。B在本例中，Metric-type-A 包含 1 個時間序列，而 Metric-type-B 包含 1 個時間序列。

    您可以建立一項含有兩個條件的快訊政策，也可以建立兩項快訊政策，每項政策各含一個條件，並使用這個資料模式。警告政策可支援多項條件，但通知管道只有單一設定。

    如果您對所監控活動之間的資料相似性不感興趣，這個模型可能就適合您。在本例中，活動是指對程式 A 和 B 的呼叫率。

  • 您可以使用單一指標，並使用標籤儲存計畫 ID。 舉例來說，標籤可能會儲存 A 或 B 值。監控功能會為每個不重複的標籤組合建立時間序列。因此，有一個時間序列的標籤值為 A，另一個時間序列的標籤值為 B。

    與先前的模型相同，您可以建立一或兩項快訊政策。不過，快訊政策的條件較為複雜，如果程式 A 的通話率超過門檻，就會產生事件。這類條件必須使用篩選器，只納入標籤值為 A 的資料點。

    這個模型的優點之一是計算比率很簡單。舉例來說，您可以判斷通往 A 的通話佔總通話量的比例。

  • 您使用單一指標計算通話次數，但不會使用標籤記錄撥打電話的程式。在這個模型中，有一個時間序列會合併兩個計畫的資料。不過，由於無法區分兩個計畫的資料，因此您無法建立符合目標的快訊政策。

前兩種設計可滿足資料分析需求，但最後一種設計則無法。

詳情請參閱「建立使用者定義的指標」。

使用者定義指標的名稱

建立使用者定義的指標時，請定義代表指標類型的字串 ID。這個字串在Google Cloud 專案中定義的使用者定義指標中不得重複，且必須使用前置字元將指標標示為使用者定義指標。監控功能允許的前置字元為 custom.googleapis.com/、workload.googleapis.com/、external.googleapis.com/user 和 external.googleapis.com/prometheus。前置字元後方會加上名稱，說明您收集的內容。如要瞭解建議的指標命名方式，請參閱指標命名慣例。 以下是指標類型兩種 ID 的範例：

    custom.googleapis.com/cpu_utilization
    custom.googleapis.com/instance/cpu/utilization

在上述範例中，前置字元 custom.googleapis.com 表示這兩個指標都是使用者定義的指標。這兩個範例都是用來評估 CPU 使用率的指標，但使用的組織模型不同。如果您預期會有大量使用者定義指標，建議您使用第二個範例中的階層式命名結構。

所有指標類型都有稱為「資源名稱」的全球專屬 ID。 指標類型的資源名稱結構如下：

projects/PROJECT_ID/metricDescriptors/METRIC_TYPE

其中 METRIC_TYPE 是指標類型的字串 ID。 如果先前的指標範例是在專案 my-project-id 中建立，則這些指標的資源名稱如下：

    projects/my-project-id/metricDescriptors/custom.googleapis.com/cpu_utilization
    projects/my-project-id/metricDescriptors/custom.googleapis.com/instance/cpu/utilization

名稱或類型？在指標描述元中，name 欄位會儲存指標類型的資源名稱，而 type 欄位會儲存 METRIC_TYPE 字串。

使用者定義指標的受監控資源類型

將資料寫入時間序列時，您必須指出資料來源。如要指定資料來源，請選擇代表資料來源的受監控資源類型，然後使用該類型說明特定來源。受監控資源不屬於指標類型。 而是您寫入資料的時間序列包含指標類型和受監控資源的參照。指標類型會說明資料，而受監控資源則會說明資料的來源。

建立指標描述元前，請先考慮受監控的資源。 您使用的受控資源類型會影響指標描述元中需要加入的標籤。舉例來說，Compute Engine VM 資源包含專案 ID、執行個體 ID 和執行個體區域的標籤。因此，如果您打算針對 Compute Engine VM 資源寫入指標，資源標籤會包含執行個體 ID，因此您不需要在指標描述元中加入執行個體 ID 的標籤。

每個指標資料點都必須與受監控的資源物件建立關聯。來自不同受控資源物件的資料點保存在不同的時間序列中。

您必須搭配使用者定義指標使用下列其中一種受監控資源類型：

一般做法是使用受監控的資源物件，代表應用程式碼執行的實體資源。這種做法有幾個優點：

  • 相較於使用單一資源類型，您會獲得更好的效能。
  • 您可以避免因將多個程序寫入相同時間序列而導致資料變得雜亂無章。
  • 您可以將使用者定義指標資料與相同資源中的其他指標資料分組在一起。

global 和一般資源

在沒有更適當的具體資源類型可用的情況下，generic_task 和 generic_node 就會變得相當實用。generic_task 類型可用於定義類似工作的資源，例如應用程式。generic_node 型別可用於定義類似節點的資源，例如虛擬機器。這兩種generic_*類型都有幾個通用標籤，可用於定義專屬資源物件，方便您在指標篩選器中用於匯總和縮減。

相較之下，global 資源類型只有 project_id 標籤。 如果專案中有許多指標來源，使用相同的 global 資源物件可能會導致指標資料發生衝突和覆寫。

支援使用者定義指標的 API 方法

下表顯示 Monitoring API 中支援使用者定義指標的方法，以及支援內建指標的方法：

Monitoring API 方法 搭配
使用者定義指標使用		 搭配
內建指標使用
monitoredResourceDescriptors.get 是的 是的
monitoredResourceDescriptors.list 是的 是的
metricDescriptors.get 是的 是的
metricDescriptors.list 是的 是的
timeSeries.list 是的 是的
timeSeries.create 是的
metricDescriptors.create 是的
metricDescriptors.delete 是的

限制與延遲時間

如要瞭解使用者定義指標和資料保留期限的相關限制，請參閱「配額與限制」。

如要在保留期限以外繼續保留指標資料，您必須將資料手動複製到其他位置，例如 Cloud Storage 或 BigQuery。

如要瞭解與寫入資料至使用者定義指標相關聯的延遲時間，請參閱指標資料的延遲時間一節。

後續步驟