本文說明如何使用 Cloud Monitoring API 建立使用者定義指標,以及如何寫入這類指標資料。使用者定義的指標與內建 Cloud Monitoring 指標使用相同的元素:
- 一組資料點。
- 指標類型資訊,可說明資料點代表的內容。
- 受監控資源資訊,可瞭解資料點的來源。
使用者定義指標 (有時稱為自訂指標) 的使用方式與內建指標相同。也就是說,您可以為這項指標資料建立圖表和快訊。
記錄指標是使用者定義指標的一種,但您無法使用 Cloud Monitoring API 建立這類指標。記錄指標會從記錄項目取得指標資料,但 Monitoring API 無法指定從記錄項目擷取指標資料的方式。請改用 Cloud Logging 建立記錄指標。建立記錄指標時,Logging 會建立本文件所述的結構,並將指標資料傳送至 Cloud Monitoring。如要瞭解如何建立記錄指標,請參閱下列文件:
如要檢測應用程式,建議您使用廠商中立的開放原始碼檢測架構 (例如 OpenTelemetry),而非廠商和產品專屬的 API 或用戶端程式庫。如要瞭解如何檢測應用程式,請參閱「 檢測和可觀測性」。
事前準備
如要瞭解所有指標的基礎結構,請參閱「指標、時間序列和資源」。
如要使用 Cloud Monitoring,您必須具有啟用計費功能的 Google Cloud 專案,如有需要,請按照下列步驟操作:
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Make sure that billing is enabled for your Google Cloud project.
- 確認已啟用 Monitoring API。詳情請參閱「啟用 Monitoring API」。
- 如果應用程式在 Google Cloud以外的環境執行, Google Cloud 專案必須使用本機應用程式預設憑證 (ADC) 驗證應用程式。詳情請參閱「為內部部署環境或其他雲端服務供應商設定 ADC」。
建立使用者定義的指標類型
如要建立使用者定義指標,請定義 MetricDescriptor
物件,指定指標的各種資訊,或是寫入指標資料。寫入指標資料時,Monitoring 會根據您提供的資料結構建立指標描述元。如要瞭解如何設計指標描述元,請參閱使用者定義指標的指標描述元。
自動建立指標描述元
如果您在使用者定義指標的指標描述元尚不存在時寫入指標資料,系統會自動建立指標描述元。但是,這個新的指標描述元可能與您想要的不完全相同;自動建立指標描述元的時候,會需要使用一些假設和預設值。
當呼叫 timeSeries.create
時,如果 TimeSeries
物件參照的 Metric
物件指定了不存在的指標類型名稱,Cloud Monitoring 就會建立新的 MetricDescriptor
。Cloud Monitoring 會根據下列規則填入 MetricDescriptor
:
type
:系統會從Metric
物件的type
欄位複製類型。name
:系統會從方法呼叫中的專案 ID 與Metric
物件中的type
值來建立名稱。labels
:顯示在Metric
物件中的標籤。新指標描述元中的每個標籤描述元都有下列欄位:key
:Metric
物件中的標籤鍵。valueType
:STRING
description
:未設定
metricKind
:除非您指定TimeSeries
物件的metricKind
參數,否則指標種類會設為GAUGE
。指定metricKind
時,新指標會含有這個種類。您只能指定GAUGE
和CUMULATIVE
種類。valueType
:值類型會從要寫入Point
的輸入值取得。值類型必須為BOOL
、INT64
、DOUBLE
或DISTRIBUTION
。在TimeSeries
的valueType
欄位中指定值類型時,該類型必須與Point
的類型相符。unit
:未設定description
:"Auto created custom metric."
。displayName
:未設定
在單一 timeSeries.create
呼叫中,您可以納入多個參照同一種不存在的指標類型的 TimeSeries
物件。在這種情況下,新指標描述元中的標籤會由 create
呼叫的所有時間序列中Metric
物件內的所有標籤聯集所組成。
後續步驟:請參閱「寫入使用者定義指標」。
手動建立指標描述元
如要建立指標描述元,請執行下列操作:
決定指標描述元的結構。如要進一步瞭解如何選擇,請瀏覽內建指標,並查看指標時間序列資料:
決定要寫入指標資料的受監控資源。請從下列清單中選擇:
aws_ec2_instance
: Amazon EC2 執行個體。dataflow_job
: Dataflow 工作。gae_instance
: App Engine 執行個體。gce_instance
: Compute Engine 執行個體。generic_node
: 使用者指定的運算節點。generic_task
: 使用者定義的工作。gke_container
: GKE 容器執行個體。global
:如果其他資源類型都不適用,則選用這個資源。在多數情況下,generic_node
或generic_task
是比global
更好的選擇。k8s_cluster
: Kubernetes 叢集。k8s_container
: Kubernetes 容器。k8s_node
: Kubernetes 節點。k8s_pod
: Kubernetes Pod。
建立
MetricDescriptor
物件,然後將其做為引數傳遞至metricDescriptors.create
方法的呼叫。
一般而言,使用與現有指標描述元相同的類型名稱來呼叫 metricDescriptors.create
是錯誤的做法。但是,如果新 MetricDescriptor
物件的所有欄位都與現有描述元的欄位完全相符,則這類呼叫並非錯誤,但卻會無效。
在下列範例中,您會建立一個取樣指標。
通訊協定
如要建立指標描述元,請使用 metricDescriptors.create
方法。您可以使用方法參考資料頁面上的 APIs Explorer 小工具來執行這個方法。詳情請參閱 APIs Explorer。
以下是 metricDescriptors.create
的範例參數:
- 名稱 (網址):
projects/[PROJECT_ID]
要求主體:提供如下所示的
MetricDescriptor
物件:{ "name": "", "description": "Daily sales records from all branch stores.", "displayName": "Sales", "type": "custom.googleapis.com/stores/sales", "metricKind": "GAUGE", "valueType": "DOUBLE", "unit": "{USD}", "labels": [ { "key": "store_id", "valueType": "STRING", "description": "The ID of the store." }, ], }
使用您的專案 ID 取代 [PROJECT_ID
],將這些值提供給小工具中的欄位:
按一下 [Execute] (執行) 按鈕來執行這個方法。
建立新指標時,MetricDescriptor
中的 name
欄位會遭到忽略,且可以省略。create
方法會傳回已填入 name
欄位的新指標描述元,在這個範例中為:
"name": "projects/[PROJECT_ID]/metricDescriptors/custom.googleapis.com/stores/daily_sales"
例如,如果您想要取得指標的描述元,可以使用這個名稱。
C#
如要驗證 Monitoring,請設定應用程式預設憑證。 詳情請參閱「為本機開發環境設定驗證」。
Go
如要驗證 Monitoring,請設定應用程式預設憑證。 詳情請參閱「為本機開發環境設定驗證」。
Java
如要驗證 Monitoring,請設定應用程式預設憑證。 詳情請參閱「為本機開發環境設定驗證」。
Node.js
如要驗證 Monitoring,請設定應用程式預設憑證。 詳情請參閱「為本機開發環境設定驗證」。
PHP
如要驗證 Monitoring,請設定應用程式預設憑證。 詳情請參閱「為本機開發環境設定驗證」。
Python
如要驗證 Monitoring,請設定應用程式預設憑證。 詳情請參閱「為本機開發環境設定驗證」。
Ruby
如要驗證 Monitoring,請設定應用程式預設憑證。 詳情請參閱「為本機開發環境設定驗證」。
如果遇到問題,請參閱「排解 API 呼叫問題」。
後續步驟:請參閱「寫入使用者定義指標」。
撰寫使用者定義的指標
您只能將資料寫入使用者定義指標的指標類型。如要寫入資料,請使用 timeSeries.create
方法。如果時間序列存在,這個方法會將新的資料點附加至現有時間序列。如果時間序列不存在,這個方法會建立時間序列並附加資料。
您可以將 TimeSeries
物件的清單傳送到 timeSeries.create
,藉以寫入資料點。清單大小最多 200 筆,且清單中每個物件都必須指定不同的時間序列。
metric
和resource
欄位的值會識別特定TimeSeries
物件。這些欄位代表資料的指標類型,以及收集資料的受監控資源。- 省略
metricKind
和valueType
欄位;寫入資料點時,會忽略這兩個欄位。 每個
TimeSeries
物件都只能包含單一Point
物件:- 資料點的值與時間間隔必須與指標類型的定義保持一致。如要瞭解不同指標種類的時間間隔,請參閱
TimeInterval
。 - 資料點的時間間隔必須晚於已在時間序列中的任何資料點。
- 間隔的結束時間在過去不得超過 25 小時,在未來不得超過五分鐘。
- 資料點的值與時間間隔必須與指標類型的定義保持一致。如要瞭解不同指標種類的時間間隔,請參閱
如要將多個資料點寫入相同的時間序列,請針對每個資料點單獨呼叫
timeSeries.create
方法。請勿以高於每 5 秒一個資料點的速度,將資料寫入單一時間序列。如果您要將資料點新增至不同的時間序列,則沒有頻率限制。
通訊協定
如要寫入指標資料,請使用 timeSeries.create
方法。您可以使用方法參考資料頁面上的 APIs Explorer 小工具來執行這個方法。詳情請參閱 API Explorer。
如要將資料點寫入在手動建立指標描述元一節中建立的 stores/daily_sales
指標,請按照下列步驟操作:
- 前往
timeSeries.create
的參考資料頁面。 - 將下列參數提供給 APIs Explorer 小工具。
- 按一下 [Execute] (執行) 按鈕。
使用下列範例參數:
- name:
projects/[PROJECT_ID]
要求主體:包含
TimeSeries
物件的清單。下列範例清單中只包含一個時間序列。{ "timeSeries": [ { "metric": { "type": "custom.googleapis.com/my_metric", "labels": { "my_label": "my_value" } }, "resource": { "type": "gce_instance", "labels": { "project_id": "[PROJECT_ID]", "instance_id": "1234567890123456789", "zone": "us-central1-f" } }, "points": [ { "interval": { "endTime": "2018-06-01T10:00:00-04:00" }, "value": { "doubleValue": 123.45 } } ] } ] }
C#
如要驗證 Monitoring,請設定應用程式預設憑證。 詳情請參閱「為本機開發環境設定驗證」。
Go
如要驗證 Monitoring,請設定應用程式預設憑證。 詳情請參閱「為本機開發環境設定驗證」。
Java
如要驗證 Monitoring,請設定應用程式預設憑證。 詳情請參閱「為本機開發環境設定驗證」。
Node.js
如要驗證 Monitoring,請設定應用程式預設憑證。 詳情請參閱「為本機開發環境設定驗證」。
PHP
如要驗證 Monitoring,請設定應用程式預設憑證。 詳情請參閱「為本機開發環境設定驗證」。
Python
如要驗證 Monitoring,請設定應用程式預設憑證。 詳情請參閱「為本機開發環境設定驗證」。
Ruby
如要驗證 Monitoring,請設定應用程式預設憑證。 詳情請參閱「為本機開發環境設定驗證」。
如果遇到問題,請參閱「排解 API 呼叫問題」。
刪除使用者定義指標
如要刪除使用者定義的指標,請刪除指標描述元。 您無法刪除儲存在 Google Cloud 專案中的時間序列資料,但刪除指標描述元會導致無法存取資料。資料會根據資料保留政策過期並刪除。
您無法刪除內建指標的指標描述元。
如要刪除指標描述元,請呼叫 metricDescriptors.delete
方法。
通訊協定
如要刪除指標描述元,請使用 metricDescriptors.delete
方法。您可以使用方法參考資料頁面上的 APIs Explorer 小工具來執行這個方法。詳情請參閱 API Explorer。
如要刪除在手動建立指標描述元一節中建立的 stores/daily_sales
指標,請按照以下步驟操作:
- 前往
metricDescriptors.delete
的參考資料頁面: 將指標描述元的名稱提供給 API Explorer 小工具:
name:
projects/[PROJECT_ID]/metricDescriptors/custom.googleapis.com/stores/daily_sales
按一下 [Execute] (執行) 按鈕。
C#
如要驗證 Monitoring,請設定應用程式預設憑證。 詳情請參閱「為本機開發環境設定驗證」。
Go
如要驗證 Monitoring,請設定應用程式預設憑證。 詳情請參閱「為本機開發環境設定驗證」。
Java
如要驗證 Monitoring,請設定應用程式預設憑證。 詳情請參閱「為本機開發環境設定驗證」。
Node.js
如要驗證 Monitoring,請設定應用程式預設憑證。 詳情請參閱「為本機開發環境設定驗證」。
PHP
如要驗證 Monitoring,請設定應用程式預設憑證。 詳情請參閱「為本機開發環境設定驗證」。
Python
如要驗證 Monitoring,請設定應用程式預設憑證。 詳情請參閱「為本機開發環境設定驗證」。
Ruby
如要驗證 Monitoring,請設定應用程式預設憑證。 詳情請參閱「為本機開發環境設定驗證」。
如果遇到問題,請參閱「排解 API 呼叫問題」。
修改使用者定義指標
如要修改使用者定義的指標,請更新定義指標的 MetricDescriptor
物件。目前僅支援新增標籤。
如要為現有使用者定義指標新增標籤,請使用 timeSeries.create
方法,並在時間序列資料中加入新標籤。如果您嘗試寫入的標籤有效,且標籤總數少於 30 個,系統就會將標籤新增至指標描述元。
接著,就像一開始就有標籤一樣,系統會寫入時間序列資料。
如要執行新增標籤之外的其他操作,則必須刪除並重新建立指標描述元。在這種情況下,您會遺失之前針對舊指標描述元收集的所有時間序列資料。詳情請參閱「刪除使用者定義的指標」。
您無法重新命名指標。