本文說明如何使用 Cloud Monitoring API 管理服務和服務等級目標 (SLO)。
服務監控會在 Monitoring API 中新增下列資源:
本文將這些新增項目統稱為 SLO API,並說明主要用途。如要大致瞭解 SLO API 中的結構,請參閱「API 中的建構元件」。完整參考資料會顯示在「Cloud Monitoring API v3」下方。
您可以使用 SLO API 執行下列操作:
建立及管理服務。
根據自訂或預先定義的服務水準指標 (SLI),為任何服務建立服務等級目標 (SLO)。
有效 ID
SLO API 中的多種方法會使用不同元素的 ID,尤其是專案和服務的 ID。這些 ID 遵循下列規則:
- 長度:1 至 63 個字元
- 字元:只能使用小寫英文字母、數字和連字號
- 開頭字元:小寫字母
- 結尾字元:小寫英文字母或數字,但不得為連字號
這些規則的規則運算式如下:
[a-z](?:[-a-z0-9]{0,61}[a-z0-9])?
使用「curl
」的範例
本節說明使用 curl
工具呼叫 SLO API 時所用的慣例和設定。如果您是透過用戶端程式庫使用這項 API,可以略過本節。
本頁的範例會使用 curl
工具,將 HTTP 要求傳送至 REST 端點,藉此存取 SLO API。請使用下列驗證和叫用 curl
的相關資訊,設定叫用時使用的變數。
驗證
建立環境變數,用來保存指標範圍的範圍界定專案 ID。以下範例使用
PROJECT_ID
:PROJECT_ID=my-test-service
驗證 Google Cloud CLI:
gcloud auth login
為避免必須在每個指令中指定專案 ID,請使用 gcloud CLI 將專案 ID 設為預設值:
gcloud config set project ${PROJECT_ID}
建立授權權杖,並擷取至環境變數中。 這些範例會呼叫變數
ACCESS_TOKEN
:ACCESS_TOKEN=`gcloud auth print-access-token`
您必須定期更新存取權杖。如果原本可用的指令突然回報您未通過驗證,請重新發出這個指令。
如要確認您已取得存取權杖,請回應
ACCESS_TOKEN
變數:echo ${ACCESS_TOKEN} ya29.GluiBj8o....
叫用「curl
」
每次 curl
呼叫都會包含一組引數,後接 SLO API 資源的網址。常見引數包括 PROJECT_ID
和 ACCESS_TOKEN
環境變數指定的值。您可能也必須指定其他引數,例如指定 HTTP 要求的類型 (例如 -X DELETE
)。預設要求為 GET
,因此範例不會指定這項引數。
每次叫用 curl
時,一般結構如下:
curl --http1.1 --header "Authorization: Bearer ${ACCESS_TOKEN}" <other_args> https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/<request>
舉例來說,如要列出專案中的所有服務,請發出下列 GET
要求:
curl --http1.1 --header "Authorization: Bearer ${ACCESS_TOKEN}" https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/services
這項要求會傳回服務說明陣列,其中包含下列項目,也就是服務 ID 為「my-test-service」的 GKE 工作負載服務:
{ "services": [ { "name": "projects/PROJECT_NUMBER/services/my-test-service", "displayName": "My Test GKE Workload Service", "basicService": { "serviceType": "GKE_WORKLOAD", "serviceLabels": { "cluster_name": "workload-test", "location": "us-central1-c", "namespace_name": "kube-system", "project_id": "lesser-weevil", "top_level_controller_name": "gke-metrics-controller", "top_level_controller_type": "DaemonSet" } }, "gkeWorkload": { "projectId": "lesser-weevil", "location": "us-central1-c", "clusterName": "workload-test", "namespaceName": "kube-system", "topLevelControllerType": "DaemonSet", "topLevelControllerName": "gke-metrics-controller" }, "source": "USER", "telemetry": { "resourceName": "//container.googleapis.com/projects/PROJECT_ID/zones/us-central1-c/clusters/workload-test/k8s/namespaces/kube-system/apps/daemonsets/gke-metrics-controller" } }, ... ] }
如要查看用於建立這項服務的設定,請參閱「建立服務」。請注意,這個清單中的 gkeWorkload
結構是衍生自用於建立服務的 basicService
結構。如要進一步瞭解服務結構,請參閱 Service
。
管理服務
Service
資源是組織服務的根元素。特定服務的各個層面 (例如服務等級目標) 會依服務名稱整理。支援的服務類型如下:
- App Engine 服務:
APP_ENGINE
- Cloud Endpoints 服務:
CLOUD_ENDPOINTS
- 標準 Istio 服務:
ISTIO_CANONICAL_SERVICE
- 叢集 Istio 服務:
CLUSTER_ISTIO
- Cloud Run 服務:
CLOUD_RUN
- 一組以 Google Kubernetes Engine 為基礎的服務:
- GKE 服務:
GKE_SERVICE
- GKE 命名空間:
GKE_NAMESPACE
- GKE 工作負載:
GKE_WORKLOAD
- GKE 服務:
- 自訂服務:
CUSTOM
詳情請參閱「基本服務類型」或「基本 GKE 服務類型」。
您可以使用 API,在專案中的任何服務中加入服務等級目標。管理服務等級目標一文介紹了操作服務等級目標的指令。
服務 ID
每項服務都有完整識別碼,稱為「資源名稱」。這個 ID 會儲存在服務說明的 name
欄位中,例如:
"name": "projects/PROJECT_NUMBER/services/PROJECT_ID-zone-us-central1-a-cloudrun-istio-system-cluster-local-gateway",
資源名稱中內嵌了服務的較短 ID,也就是資源名稱中 projects/PROJECT_NUMBER/services/
子字串後方的部分。
如果您建立的服務資源名稱為 projects/PROJECT_NUMBER/services/my-test-service
,則服務 ID 為 my-test-service
。
為求簡潔和準確,許多 curl
範例會假設服務 ID 保存在環境變數 SERVICE_ID
中,方便您重複參照。
列出服務
如要擷取專案中所有服務的相關資訊,請叫用 services.list
方法。如要依服務 ID 擷取特定服務的資訊,請使用 services.get
方法:
通訊協定
如要使用curl
列出服務相關資訊,請將 GET
要求傳送至下列網址,以叫用 services.list
或 services.get
方法:
https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services
列出所有服務https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services/SERVICE_ID
取得特定服務
舉例來說,下列要求會擷取環境變數 SERVICE_ID
中儲存值所識別的服務相關資訊:
curl --http1.1 --header "Authorization: Bearer ${ACCESS_TOKEN}" https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/services/${SERVICE_ID}
建立 Service
如要建立服務,請指定服務類型的表示法,然後傳送至 services.create
方法。您可以參閱「基本服務類型」和「基本 GKE 服務類型」一文,瞭解服務類型結構。
結構各不相同,但呼叫 API 的程序相同。
你必須指定服務的顯示名稱,以及包含服務代表的 basicService
欄位。
您可以視需要指定服務 ID。以下範例說明如何建立 {[gke_name_short}} 工作負載服務:
通訊協定
如要使用 curl
建立服務,請將 POST
訊息傳送至 https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services
端點:
如要提供服務的 ID,請為服務 ID 建立變數:
SERVICE_ID=my-test-service
這個值會以網址查詢參數
service_id
提供。建立變數,以保留說明服務的要求主體:
CREATE_SERVICE_POST_BODY=$(cat <<EOF { "displayName": "My Test GKE Workload Service", "basicService": { "serviceType": "GKE_WORKLOAD", "serviceLabels": { "cluster_name": "workload-test", "location": "us-central1-c", "namespace_name": "kube-system", "project_id": "PROJECT_ID", "top_level_controller_name": "gke-metrics-controller", "top_level_controller_type": "DaemonSet" } } } EOF )
將要求主體發布至端點,並將服務 ID 指定為
service_id
查詢參數的值:curl --http1.1 --header "Authorization: Bearer ${ACCESS_TOKEN}" --header "Content-Type: application/json" -X POST -d "${CREATE_SERVICE_POST_BODY}" https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/services?service_id=${SERVICE_ID}
如需與其他服務相關聯的結構範例,請參閱「基本服務類型」或「基本 GKE 服務類型」。
刪除服務
如要刪除您建立的服務,請叫用 services.delete
方法並指定服務 ID。
通訊協定
如要使用curl
刪除服務,請向 https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services/SERVICE_ID
端點傳送 DELETE
要求:
curl --http1.1 --header "Authorization: Bearer ${ACCESS_TOKEN}" -X DELETE https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/services/${SERVICE_ID}
管理服務等級目標
您可以使用 SLO API 建立、刪除及擷取 SLO。每項服務最多可有 500 個 SLO。
如要管理服務的 SLO,您必須擁有服務 ID。系統會根據服務為服務等級目標命名。 如要瞭解如何找出服務 ID,請參閱「服務 ID」。
列出服務等級目標
如要擷取與服務相關聯的所有服務等級目標資訊,請叫用 services.serviceLevelObjectives.list
方法。如要依名稱擷取特定服務水準目標的相關資訊,請使用 services.serviceLevelObjectives.get
方法:
通訊協定
如要使用curl
列出服務相關資訊,請將 GET
要求傳送至下列網址,以叫用 services.serviceLevelObjectives.list
或 services.serviceLevelObjectives.get
方法:
https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services/[SERVICE_ID]/serviceLevelObjectives
列出所有服務等級目標https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services/[SERVICE_ID]/serviceLevelObjectives/SLO_ID
取得特定服務等級目標
舉例來說,下列要求會列出與環境變數 SERVICE_ID
中儲存的服務 ID 相關聯的所有 SLO:
curl --http1.1 --header "Authorization: Bearer ${ACCESS_TOKEN}" https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/services/${SERVICE_ID}/serviceLevelObjectives
以下是從「currencyservice」服務擷取的可用性 SLO:
{ "name": "projects/PROJECT_NUMBER/services/PROJECT_ID-zone-us-central1-c-csm-main-default-currencyservice/serviceLevelObjectives/3kavNVTtTMuzL7KcXAxqCQ", "displayName": "98% Availability in Calendar Week" "serviceLevelIndicator": { "basicSli": { "availability": {}, "location": [ "us-central1-c" ] } }, "goal": 0.98, "calendarPeriod": "WEEK", },
這個服務水準目標是以可用性服務水準指標為基礎,設定 98% 的目標效能,並以一週為單位評估達成度。如要進一步瞭解可用性 SLI,請參閱「服務水準指標」。
如要進一步瞭解 SLO 的結構,請參閱 ServiceLevelObjective
。
擷取特定服務等級目標
每個服務等級目標在服務中都有專屬 ID,由服務等級目標 name
欄位中 serviceLevelObjectives
後方的字串組成。在下列範例中:
"name": "projects/PROJECT_NUMBER/services/PROJECT_ID-zone-us-central1-c-csm-main-default-currencyservice/serviceLevelObjectives/3kavNVTtTMuzL7KcXAxqCQ",
SLO ID 是字串 3kavNVTtTMuzL7KcXAxqCQ
。
如要擷取特定服務等級目標的資訊,請依 ID 要求服務等級目標。
通訊協定
如要使用curl
取得特定 SLO,請向 https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services/SERVICE_ID/serviceLevelObjectives/SLO_ID
發出 GET
要求,叫用 services.serviceLevelObjectives.get
方法:
SLO_ID=dhefHDM4TwSRZEKIV4ZYEg curl --http1.1 --header "Authorization: Bearer ${ACCESS_TOKEN}" https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/services/${SERVICE_ID}/serviceLevelObjectives/${SLO_ID}
建立服務等級目標
如要使用 SLO API 建立 SLO,請建立 ServiceLevelObjective
物件,並將其傳遞至 serviceLevelObjectives.create
方法。
SLO 的結構包含許多內嵌結構,包括 serviceLevelIndicator
欄位值的結構。
對於 Cloud Service Mesh、Google Kubernetes Engine 上的 Istio 和 App Engine 服務,系統會預先定義 SLI。 您可以使用 Cloud Service Mesh 控制台建立服務等級目標,只要指定效能目標和合規期間即可。
如為其他服務,您必須使用 SLO API 定義服務等級目標。如要指定服務等級目標,您也必須為
serviceLevelIndicator
欄位建立值。如需一些技巧,請參閱「建立服務水準指標」一文;如需根據各種來源建立 SLI 的範例,請參閱「運用指標建立 SLI」一文。
您也可以使用 Google Cloud 控制台建立 SLI。詳情請參閱「建立 SLO」。
服務等級目標的架構
建立服務等級目標的基本架構如下:
{ "displayName": string, "serviceLevelIndicator": { object (ServiceLevelIndicator) }, "goal": number, // Union field period can be only one of the following: "rollingPeriod": string, "calendarPeriod": enum (CalendarPeriod) // End of list of possible types for union field period. }
您必須指定下列項目:
- 顯示名稱:服務水準目標的說明
- 服務水準指標,屬於下列三種類型之一:
- 成效目標 (百分比)
- 達成度評估時間範圍,分為下列兩種:
- 一段時間的滾動週期 (以秒為單位)
- 一段日曆時間
如要進一步瞭解 SLI、效能目標和法規遵循週期,請參閱「服務監控概念」。
對於 Cloud Service Mesh、Google Kubernetes Engine 上的 Istio 和 App Engine 服務,SLI 類型為基本 SLI。
如果是其他服務,則必須建立以要求為基礎的 SLI 或以時間範圍為基礎的 SLI。如需一些技巧,請參閱「建立服務水準指標」。
範例
有了 SLI 後,您就可以建立 SLO。以下範例定義了使用基本 SLI 的服務 SLO。您可能在單一 SLI 上有多個 SLO,例如一個是 95% 可用性,另一個是 99% 可用性。以下範例是日曆週內 95% 正常運作時間的 SLO:
{ "serviceLevelIndicator": { "basicSli": { "availability": {}, "location": [ "us-central1-c" ] } }, "goal": 0.95, "calendarPeriod": "WEEK", "displayName": "95% Availability in Calendar Week" }
這個範例指定了在 3 天的滾動期間內,可用性為 75% 的 SLO:
{ "serviceLevelIndicator": { "basicSli": { "availability": {}, "location": [ "us-central1-c" ] } }, "goal": 0.75, "rollingPeriod": "259200s", "displayName": "75% Availability in Rolling 3 Days" }
通訊協定
如要使用curl
建立 SLO,請將 POST
訊息傳送至 https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services/SERVICE_ID/serviceLevelObjectives
端點:
建立服務 ID 的變數:
SERVICE_ID=custom:my-test-service
建立變數來保存要求主體,也就是
ServiceLevelObjective
物件的例項。這個範例使用先前所述的其中一個 SLO:CREATE_SLO_POST_BODY=$(cat <<EOF { "serviceLevelIndicator": { "basicSli": { "availability": {}, "location": [ "us-central1-c" ] } }, "goal": 0.75, "rollingPeriod": "259200s", "displayName": "75% Availability in Rolling 3 Days" } EOF )
將要求主體發布至端點:
curl --http1.1 --header "Authorization: Bearer ${ACCESS_TOKEN}" --header "Content-Type: application/json" -X POST -d "${CREATE_SLO_POST_BODY}" https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/services/${SERVICE_ID}/serviceLevelObjectives
您也可以選擇將 SLO 的所需 ID 指定為
service_level_objective_id
查詢參數的值:SLO_ID=test-slo-id curl --http1.1 --header "Authorization: Bearer ${ACCESS_TOKEN}" --header "Content-Type: application/json" -X POST -d "${CREATE_SLO_POST_BODY}" https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/services/${SERVICE_ID}/serviceLevelObjectives?service_level_objective_id=${SLO_ID}
刪除服務等級目標
如要刪除 SLO,請叫用 services.serviceLevelObjectives.delete
方法,並指定專案中的 SLO ID:
通訊協定
如要使用curl
刪除 SLO,請向 https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services/SERVICE_ID/serviceLevelObjectives/SLO_ID
端點傳送 DELETE
要求:
curl --http1.1 --header "Authorization: Bearer ${ACCESS_TOKEN}" -X DELETE https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/services/${SERVICE_ID}/serviceLevelObjectives/${SLO_ID}
存取服務等級目標時間序列
SLO 資料會儲存在時間序列中,因此您可以使用 timeSeries.list
方法擷取資料。不過,這項資料不會儲存在標準指標類型中,因此您無法使用指定指標類型篩選器的標準機制,將資料傳送至 timeSeries.list
方法。
不過,您可以透過 filter
參數的 timeSeries.list
方法指定其他類型的篩選器 (即時間序列選取器),擷取 SLO 時間序列。如要瞭解如何使用這些選取器,請參閱「擷取服務等級目標資料」。
您也可以使用時間序列選取器,以程式輔助方式設定快訊政策。詳情請參閱「資金消耗率的快訊」。