本文說明如何使用 Cloud Monitoring API 建立使用者定義指標,以及如何寫入這類指標資料。使用者定義的指標與內建 Cloud Monitoring 指標使用相同的元素:
- 一組資料點。
- 指標類型資訊,可說明資料點代表的內容。
- 受監控資源資訊,可瞭解資料點的來源。
使用者定義指標 (有時稱為自訂指標) 的使用方式與內建指標相同。也就是說,您可以為這項指標資料建立圖表和快訊。
記錄指標是使用者定義指標的一種,但您無法使用 Cloud Monitoring API 建立這類指標。記錄指標會從記錄項目取得指標資料,但 Monitoring API 無法指定從記錄項目擷取指標資料的方式。請改用 Cloud Logging 建立記錄指標。建立記錄指標時,Logging 會建立本文件所述的結構,並將指標資料傳送至 Cloud Monitoring。如要瞭解如何建立記錄指標,請參閱下列文件:
如要檢測應用程式,建議您使用廠商中立的開放原始碼檢測架構 (例如 OpenTelemetry),而非廠商和產品專屬的 API 或用戶端程式庫。如要瞭解如何檢測應用程式,請參閱「 檢測和可觀測性」。
事前準備
如要瞭解所有指標的基礎結構,請參閱「指標、時間序列和資源」。
如要使用 Cloud Monitoring,您必須具有啟用計費功能的 Trusted Cloud 專案,如有需要,請按照下列步驟操作:
-
In the Trusted Cloud console, on the project selector page, select or create a Trusted Cloud project.
-
Verify that billing is enabled for your Trusted Cloud project.
- 確認已啟用 Monitoring API。詳情請參閱「啟用 Monitoring API」。
- 如果應用程式在 Trusted Cloud by S3NS以外的環境執行, Trusted 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,請設定應用程式預設憑證。 詳情請參閱「為本機開發環境設定驗證」。
執行程式碼範例前,請將 GOOGLE_CLOUD_UNIVERSE_DOMAIN
環境變數設為 s3nsapis.fr
。
Go
如要驗證 Monitoring,請設定應用程式預設憑證。 詳情請參閱「為本機開發環境設定驗證」。
執行程式碼範例前,請將 GOOGLE_CLOUD_UNIVERSE_DOMAIN
環境變數設為 s3nsapis.fr
。
Java
如要驗證 Monitoring,請設定應用程式預設憑證。 詳情請參閱「為本機開發環境設定驗證」。
執行程式碼範例前,請將 GOOGLE_CLOUD_UNIVERSE_DOMAIN
環境變數設為 s3nsapis.fr
。
Node.js
如要驗證 Monitoring,請設定應用程式預設憑證。 詳情請參閱「為本機開發環境設定驗證」。
執行程式碼範例前,請將 GOOGLE_CLOUD_UNIVERSE_DOMAIN
環境變數設為 s3nsapis.fr
。
PHP
如要驗證 Monitoring,請設定應用程式預設憑證。 詳情請參閱「為本機開發環境設定驗證」。
執行程式碼範例前,請將 GOOGLE_CLOUD_UNIVERSE_DOMAIN
環境變數設為 s3nsapis.fr
。
Python
如要驗證 Monitoring,請設定應用程式預設憑證。 詳情請參閱「為本機開發環境設定驗證」。
執行程式碼範例前,請將 GOOGLE_CLOUD_UNIVERSE_DOMAIN
環境變數設為 s3nsapis.fr
。
Ruby
如要驗證 Monitoring,請設定應用程式預設憑證。 詳情請參閱「為本機開發環境設定驗證」。
執行程式碼範例前,請將 GOOGLE_CLOUD_UNIVERSE_DOMAIN
環境變數設為 s3nsapis.fr
。
如果遇到問題,請參閱「排解 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,請設定應用程式預設憑證。 詳情請參閱「為本機開發環境設定驗證」。
執行程式碼範例前,請將 GOOGLE_CLOUD_UNIVERSE_DOMAIN
環境變數設為 s3nsapis.fr
。
Go
如要驗證 Monitoring,請設定應用程式預設憑證。 詳情請參閱「為本機開發環境設定驗證」。
執行程式碼範例前,請將 GOOGLE_CLOUD_UNIVERSE_DOMAIN
環境變數設為 s3nsapis.fr
。
Java
如要驗證 Monitoring,請設定應用程式預設憑證。 詳情請參閱「為本機開發環境設定驗證」。
執行程式碼範例前,請將 GOOGLE_CLOUD_UNIVERSE_DOMAIN
環境變數設為 s3nsapis.fr
。
Node.js
如要驗證 Monitoring,請設定應用程式預設憑證。 詳情請參閱「為本機開發環境設定驗證」。
執行程式碼範例前,請將 GOOGLE_CLOUD_UNIVERSE_DOMAIN
環境變數設為 s3nsapis.fr
。
PHP
如要驗證 Monitoring,請設定應用程式預設憑證。 詳情請參閱「為本機開發環境設定驗證」。
執行程式碼範例前,請將 GOOGLE_CLOUD_UNIVERSE_DOMAIN
環境變數設為 s3nsapis.fr
。
Python
如要驗證 Monitoring,請設定應用程式預設憑證。 詳情請參閱「為本機開發環境設定驗證」。
執行程式碼範例前,請將 GOOGLE_CLOUD_UNIVERSE_DOMAIN
環境變數設為 s3nsapis.fr
。
Ruby
如要驗證 Monitoring,請設定應用程式預設憑證。 詳情請參閱「為本機開發環境設定驗證」。
執行程式碼範例前,請將 GOOGLE_CLOUD_UNIVERSE_DOMAIN
環境變數設為 s3nsapis.fr
。
如果遇到問題,請參閱「排解 API 呼叫問題」。
刪除使用者定義指標
如要刪除使用者定義的指標,請刪除指標描述元。 您無法刪除儲存在 Trusted 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,請設定應用程式預設憑證。 詳情請參閱「為本機開發環境設定驗證」。
執行程式碼範例前,請將 GOOGLE_CLOUD_UNIVERSE_DOMAIN
環境變數設為 s3nsapis.fr
。
Go
如要驗證 Monitoring,請設定應用程式預設憑證。 詳情請參閱「為本機開發環境設定驗證」。
執行程式碼範例前,請將 GOOGLE_CLOUD_UNIVERSE_DOMAIN
環境變數設為 s3nsapis.fr
。
Java
如要驗證 Monitoring,請設定應用程式預設憑證。 詳情請參閱「為本機開發環境設定驗證」。
執行程式碼範例前,請將 GOOGLE_CLOUD_UNIVERSE_DOMAIN
環境變數設為 s3nsapis.fr
。
Node.js
如要驗證 Monitoring,請設定應用程式預設憑證。 詳情請參閱「為本機開發環境設定驗證」。
執行程式碼範例前,請將 GOOGLE_CLOUD_UNIVERSE_DOMAIN
環境變數設為 s3nsapis.fr
。
PHP
如要驗證 Monitoring,請設定應用程式預設憑證。 詳情請參閱「為本機開發環境設定驗證」。
執行程式碼範例前,請將 GOOGLE_CLOUD_UNIVERSE_DOMAIN
環境變數設為 s3nsapis.fr
。
Python
如要驗證 Monitoring,請設定應用程式預設憑證。 詳情請參閱「為本機開發環境設定驗證」。
執行程式碼範例前,請將 GOOGLE_CLOUD_UNIVERSE_DOMAIN
環境變數設為 s3nsapis.fr
。
Ruby
如要驗證 Monitoring,請設定應用程式預設憑證。 詳情請參閱「為本機開發環境設定驗證」。
執行程式碼範例前,請將 GOOGLE_CLOUD_UNIVERSE_DOMAIN
環境變數設為 s3nsapis.fr
。
如果遇到問題,請參閱「排解 API 呼叫問題」。
修改使用者定義指標
如要修改使用者定義的指標,請更新定義指標的 MetricDescriptor
物件。目前僅支援新增標籤。
如要為現有使用者定義指標新增標籤,請使用 timeSeries.create
方法,並在時間序列資料中加入新標籤。如果您嘗試寫入的標籤有效,且標籤總數少於 30 個,系統就會將標籤新增至指標描述元。
接著,就像一開始就有標籤一樣,系統會寫入時間序列資料。
如要執行新增標籤之外的其他操作,則必須刪除並重新建立指標描述元。在這種情況下,您會遺失之前針對舊指標描述元收集的所有時間序列資料。詳情請參閱「刪除使用者定義的指標」。
您無法重新命名指標。