本頁面由 Cloud Translation API 翻譯而成。

API 中的建構元件

本文件將介紹在 SLO API 中用來代表服務和 SLO 的結構，並將這些結構對應至「服務監控中的概念」一文中一般所述的概念。

SLO API 可用來設定服務等級目標 (SLO)，用於監控服務的健康狀態。

服務監控會將下列資源新增至 Monitoring API：

如要瞭解如何叫用 API，請參閱「使用 API」。

服務

服務由 Service 物件表示。這個物件包含下列欄位：

名稱：這個服務的完整資源名稱
顯示名稱：用於控制台元件的標籤
其中一個 BasicService 類型的結構。
系統提供的遙測設定物件

如要定義基本服務，請指定服務類型，並提供一組用於說明服務的服務專屬標籤：

{
   "serviceType": string,
   "serviceLabels": {
      string: string,
      ...
   }
}

以下各節將提供各類型服務的範例。

基本服務類型

本節提供以 BasicService 類型建構的服務定義範例，其中 serviceType 欄位的值為下列其中一種：

APP_ENGINE
CLOUD_ENDPOINTS
CLUSTER_ISTIO
ISTIO_CANONICAL_SERVICE
CLOUD_RUN

每種服務類型都會使用 BasicSli 服務水準指標。

App Engine

    {
      "displayName": "DISPLAY_NAME",
      "basicService": {
          "serviceType": "APP_ENGINE",
          "serviceLabels": {
            "module_id": "MODULE_ID"
          },
      },
    }

Cloud Endpoints

    {
      "displayName": "DISPLAY_NAME",
      "basicService": {
          "serviceType": "CLOUD_ENDPOINTS",
          "serviceLabels": {
            "service": "SERVICE"
          },
      },
    }

叢集 Istio

    {
      "displayName": "DISPLAY_NAME",
      "basicService": {
          "serviceType": "CLUSTER_ISTIO",
          "serviceLabels": {
            "location": "LOCATION",
            "cluster_name": "CLUSTER_NAME",
            "service_namespace": "SERVICE_NAMESPACE",
            "service_name": "SERVICE_NAME"
          },
      },
    }

Istio 標準服務

    {
      "displayName": "DISPLAY_NAME",
      "basicService": {
          "serviceType": "ISTIO_CANONICAL_SERVICE",
          "serviceLabels": {
            "mesh_uid": "MESH_UID",
            "canonical_service_namespace": "CANONICAL_SERVICE_NAMESPACE",
            "canonical_service": "CANONICAL_SERVICE"
          },
      },
    }

Cloud Run

    {
      "displayName": "DISPLAY_NAME",
      "basicService": {
          "serviceType": "CLOUD_RUN",
          "serviceLabels": {
            "service_name": "SERVICE_NAME",
            "location": "LOCATION"
          },
      },
    }

基本 GKE 服務類型

本節提供以 BasicService 類型建構的 GKE 服務定義範例，其中 serviceType 欄位的值為下列其中一個：

GKE_NAMESPACE
GKE_WORKLOAD
GKE_SERVICE

您必須為這些服務類型定義服務水準指標。他們無法使用 BasicSli 服務水準指標。詳情請參閱「服務水準指標」。

GKE 命名空間

    {
      "displayName": "DISPLAY_NAME",
      "basicService": {
          "serviceType": "GKE_NAMESPACE",
          "serviceLabels": {
            "project_id": "PROJECT_ID",
            "location": "LOCATION",
            "cluster_name": "CLUSTER_NAME",
            "namespace_name": "NAMESPACE_NAME"
          }
      },
    }

GKE 工作負載

    {
      "displayName": "DISPLAY_NAME",
      "basicService": {
          "serviceType": "GKE_WORKLOAD",
          "serviceLabels": {
            "project_id": "PROJECT_ID",
            "location": "LOCATION",
            "cluster_name": "CLUSTER_NAME",
            "namespace_name": "NAMESPACE_NAME",
            "top_level_controller_type": "TOPLEVEL_CONTROLLER_TYPE",
            "top_level_controller_name": "TOPLEVEL_CONTROLLER_NAME",
          }
      },
    }

GKE 服務

    {
      "displayName": "DISPLAY_NAME",
      "basicService": {
          "serviceType": "GKE_SERVICE",
          "serviceLabels": {
            "project_id": "PROJECT_ID",
            "location": "LOCATION",
            "cluster_name": "CLUSTER_NAME",
            "namespace_name": "NAMESPACE_NAME",
            "service_name": "SERVICE_NAME"
          }
      },
    }

自訂服務

如果沒有任何基本服務類型適合，您可以建立自訂服務。自訂服務如下所示：

    {
      "displayName": "DISPLAY_NAME",
      "custom": {}
    }

您必須為這些服務類型定義服務水準指標。他們無法使用 BasicSli 服務水準指標。詳情請參閱「服務水準指標」。

服務水準指標

服務水準指標 (SLI) 可用來評估服務的效能。服務水準指標是根據服務擷取的指標而定。具體的 SLI 定義方式取決於用來做為指標指標的指標類型，但通常是將可接受的結果與總結果進行比較。

SLI 由 ServiceLevelIndicator 物件表示。這個物件是用來參照三種支援的 SLI 類型：

基本 SLI，系統會自動為 BasicService 服務類型的執行個體建立這項 SLI。這類 SLI 的說明請參閱「服務等級目標」一文；它由 BasicSli 物件表示，用於評估可用性或延遲時間。
以要求為基礎的服務水準指標，可用於計算代表可接受服務的事件。以要求為準的服務等級目標一文說明瞭這類 SLI 的用法；這類 SLI 由 RequestBasedSli 物件代表。
以時間範圍為依據的 SLI，可用來計算符合某些良好條件的時間範圍。以 Windows 為基礎的服務等級目標一文說明瞭這類 SLI 的用法；這類 SLI 由 WindowsBasedSli 物件代表。

舉例來說，下方顯示的是基本可用性 SLI：

{
  "basicSli": {
    "availability": {},
    "location": [
      "us-central1-c"
    ]
  }
}

以要求為基礎的 SLI 結構

以要求為基礎的 SLI 是以指標為依據，將服務單位計為特定結果與總數的比率。舉例來說，如果您使用可計算要求數的指標，就可以建立成功傳回要求數與要求總數之間的比率。

建立以要求為準的 SLI 有兩種方法：

做為 TimeSeriesRatio，當良好服務與總服務的比率是根據兩個時間序列計算，且這些時間序列的值屬於 DELTA 或 CUMULATIVE 指標類型。
做為 DistributionCut，當時間序列的值類型為 DISTRIBUTION，且其值的指標種類為 DELTA 或 CUMULATIVE。良好服務值是指在指定範圍內屬於直方圖值區的項目計數，而總計則是指分布中所有值的計數。

以下是使用時序比率的 SLI 的 JSON 表示法：

{
  "requestBased": {
    "goodTotalRatio": {
      "totalServiceFilter": "resource.type=https_lb_rule metric.type="loadbalancing.googleapis.com/https/request_count"",
      "goodServiceFilter": "resource.type=https_lb_rule metric.type="loadbalancing.googleapis.com/https/request_count" metric.label.response_code_class=200",
    }
  }
}

這個比率中的時間序列會由一組受控資源類型和指標類型識別：

資源：https_lb_rule
指標類型：loadbalancing.googleapis.com/https/request_count

totalServiceFilter 的值由指標和資源類型組合表示。goodServiceFilter 的值由相同的組合表示，但其中某些標籤具有特定值；在本例中，當 response_code_class 標籤的值為 200 時即是如此。

篩選器之間的比率是指傳回 2xx HTTP 狀態的請求數量與請求總數的比率。

以下是使用分布式切割的 SLI 的 JSON 表示法：

{
  "requestBased": {
    "distribution_cut": {
      "distribution_filter": "resource.type=https_lb_rule  metric.type="loadbalancing.googleapis.com/https/backend_latencies" metric.label.response_code_class=200",
      "range": {
        "min": "-Infinity",
        "max": 500.0
      }
    }
  }
}

時間序列的識別依據為受控資源類型、指標類型和指標標籤的值：

資源：https_lb_rule
指標類型：loadbalancing.googleapis.com/https/backend_latencies
標籤-值組合：response_code_class = 200

range 欄位會指定視為良好的延遲範圍。這個 SLI 會計算 2xx 類回應的延遲時間 (低於 500 毫秒) 與所有 200 類回應的延遲時間的比率。

以時間範圍為準的 SLI 結構

以時間範圍為依據的 SLI 會計算系統在哪些時間範圍內提供的服務被視為良好。用於判斷服務品質的條件，是服務水準指標定義的一部分。

所有以視窗為基礎的服務水準指標都包含視窗期，時間範圍為 60 到 86,400 秒 (1 天)。

您可以透過兩種方式指定以時間範圍為依據的 SLI 的良好服務條件：

建立篩選字串 (如「監控篩選器」一節所述)，以便傳回含有布林值的時間序列。如果視窗的值為 true，表示視窗運作良好。這個篩選器稱為 goodBadMetricFilter。
建立 PerformanceThreshold 物件，代表可接受的效能門檻。這個物件會指定為 goodTotalRatioThreshold 的值。

PerformanceThreshold 物件會指定閾值和效能 SLI。如果效能 SLI 的值達到或超過閾值，則時間範圍就會計為良好。

您可以透過兩種方式指定成效 SLI：
- 做為 basicPerformanceSli 欄位中的 BasicSli 物件。
- 在 performance 欄位中，以 RequestBasedSli 物件形式顯示。如果您使用以要求為基礎的 SLI，則 SLI 的指標類型必須為 DELTA 或 CUMULATIVE。您無法在依要求產生的 SLI 中使用 GAUGE 指標。

以下是 JSON 表示法，說明以 Windows 為基礎的 SLI 是如何根據基本可用性 SLI 的效能門檻建構：

{
  "windowsBased": {
     "goodTotalRatioThreshold": {
       "threshold": 0.9,
       "basicSliPerformance": {
         "availability": {},
         "location": [
           "us-central1-c"
         ]
       }
     },
     "windowPeriod": "300s"
   }
}

這個 SLI 將良好效能定義為可用性達到 90% 以上，且持續 5 分鐘的時間範圍。基本 SLI 的結構如「服務水準指標」所示。

您也可以在以時間為準的 SLI 中嵌入以要求為準的 SLI。如要進一步瞭解內嵌結構，請參閱「以要求為基礎的 SLI 專用結構」。

服務等級目標

服務等級目標 (SLO) 由 ServiceLevelObjective 物件表示。這個物件包含下列欄位：

名稱
顯示名稱
目標 SLI；嵌入的 ServiceLevelIndicator 物件
SLI 的成效目標
SLI 的評估時間範圍

以下是 SLO 的 JSON 表示法，其中使用基本可用性 SLI 做為 serviceLevelIndicator 欄位的值：

{
   "name": "projects/PROJECT_NUMBER/services/PROJECT_ID-zone-us-central1-c-csm-main-default-currencyservice/serviceLevelObjectives/3kavNVTtTMuzL7KcXAxqCQ",
   "serviceLevelIndicator": {
     "basicSli": {
       "availability": {},
       "location": [
         "us-central1-c"
       ]
     }
   },
   "goal": 0.98,
   "calendarPeriod": "WEEK",
   "displayName": "98% Availability in Calendar Week"
}

這個 SLO 將效能目標設為在一段時間內達到 98% 的可用性。