使用 API

本文說明如何使用 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 的相關資訊,設定叫用時使用的變數。

驗證

  1. 建立環境變數,用來保存指標範圍的範圍界定專案 ID。以下範例使用 PROJECT_ID

    PROJECT_ID=my-test-service
    
  2. 驗證 Google Cloud CLI:

    gcloud auth login
    
  3. 為避免必須在每個指令中指定專案 ID,請使用 gcloud CLI 將專案 ID 設為預設值:

    gcloud config set project ${PROJECT_ID}
    
  4. 建立授權權杖,並擷取至環境變數中。 這些範例會呼叫變數 ACCESS_TOKEN

    ACCESS_TOKEN=`gcloud auth print-access-token`
    

    您必須定期更新存取權杖。如果原本可用的指令突然回報您未通過驗證,請重新發出這個指令。

  5. 如要確認您已取得存取權杖,請回應 ACCESS_TOKEN 變數:

    echo ${ACCESS_TOKEN}
    ya29.GluiBj8o....
    

叫用「curl

每次 curl 呼叫都會包含一組引數,後接 SLO API 資源的網址。常見引數包括 PROJECT_IDACCESS_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
  • 自訂服務: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.listservices.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 端點:

  1. 如要提供服務的 ID,請為服務 ID 建立變數:

    SERVICE_ID=my-test-service
    

    這個值會以網址查詢參數 service_id 提供。

  2. 建立變數,以保留說明服務的要求主體:

    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
    )
    
  3. 將要求主體發布至端點,並將服務 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.listservices.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 端點:

  1. 建立服務 ID 的變數:

    SERVICE_ID=custom:my-test-service
    
  2. 建立變數來保存要求主體,也就是 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
    )
    
  3. 將要求主體發布至端點:

    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 時間序列。如要瞭解如何使用這些選取器,請參閱「擷取服務等級目標資料」。

您也可以使用時間序列選取器,以程式輔助方式設定快訊政策。詳情請參閱「資金消耗率的快訊」。