API 中的构造

本文档介绍了用于在 SLO API 中表示服务和 SLO 的结构，并将它们映射到服务监控的概念中概要介绍的概念。

SLO API 用于设置可用于监控服务运行状况的服务等级目标 (SLO)。

Service Monitoring 可将以下资源添加到 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

您必须为这些服务类型定义 SLI。它们不能使用 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": {}
    }

您必须为这些服务类型定义 SLI。它们不能使用 BasicSli 服务等级指标。如需了解详情，请参阅服务等级指标。

服务等级指标

服务等级指标 (SLI) 可以衡量服务的性能。 SLI 基于服务捕获的指标。SLI 的具体定义方式取决于用作指标指示符的指标类型，但通常是可接受结果与总结果之间的一些比较。

SLI 由 ServiceLevelIndicator 对象表示。此对象是一个统一称呼，它包括三种受支持的 SLI 类型：

基本 SLI（针对 BasicService 服务类型的实例自动创建）。服务等级目标中介绍了这一类型的 SLI；它由 BasicSli 对象表示，测量可用性或延迟时间。
基于请求的 SLI 可用于计算代表可接受服务的事件。基于请求的 SLO 中介绍了此类 SLI 的用法；它由 RequestBasedSli 对象表示。
基于窗口的 SLI 可用于计算满足某个良好标准的时间段。基于窗口的 SLO 中介绍了此类 SLI 的用法；它由 WindowsBasedSli 对象表示。

例如，以下显示了基本可用性 SLI：

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

基于请求的 SLI 的结构

基于请求的 SLI 使用的指标以服务单元为单位，计算特定结果与总结果之间的比率。例如，如果您使用一个计算请求数量的指标，则可以构建返回成功的请求数与请求总数之间的比率。

您可以通过以下两种方法构建基于请求的 SLI：

当良好服务与总服务的比率是根据两个时间序列计算，并且这些时间序列的值具有指标类型 DELTA 或 CUMULATIVE 时，构建为 TimeSeriesRatio。
当时间序列的值类型为 DISTRIBUTION 且其值具有指标类型 DELTA 或 CUMULATIVE 时，构建为 DistributionCut。良好服务值是指在指定范围内落入直方图分区的项的数量，而总数是分布中所有值的数量。

以下显示了使用时间序列比率的 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 计算延迟时间低于 500 的 2xx 类响应占所有 200 类响应的延迟时间的比率。

基于窗口的 SLI 的结构

基于窗口的 SLI 计算所提供服务被视为良好服务的时间窗口。良好服务的标准是 SLI 定义的一部分。

所有基于窗口的 SLI 都包含一个窗口期，即 60-86400 秒（1 天）。

您可以通过以下两种方式为基于窗口的 SLI 指定良好服务的标准：

根据 Monitoring 过滤条件中的说明创建过滤条件字符串，该过滤条件将返回具有布尔值的时间序列。如果窗口的值是 true，则该窗口是良好的。此过滤条件称为 goodBadMetricFilter。
创建一个表示可接受性能阈值的 PerformanceThreshold 对象。此对象被指定为 goodTotalRatioThreshold 的值。

PerformanceThreshold 对象指定阈值和性能 SLI。如果性能 SLI 的值达到或超过阈值，则该时间窗口将被计为良好。

您可以通过以下两种方式指定性能 SLI：
- 指定为 basicPerformanceSli 字段中的 BasicSli 对象。
- 指定为 performance 字段中的 RequestBasedSli 对象。如果您使用基于请求的 SLI，则 SLI 的指标种类必须是 DELTA 或 CUMULATIVE。您不能在基于请求的 SLI 中使用 GAUGE 指标。

以下显示了一个基于窗口的 SLI 的 JSON 表示法，该 SLI 基于基本可用性 SLI 的性能阈值构建：

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

该 SLI 指定的良好性能标准为：在 5 分钟的时间窗口内可用性达到 90% 或更高。服务等级指标中介绍了基本 SLI 的结构。

您还可以在基于窗口的 SLI 中嵌入基于请求的 SLI。如需详细了解嵌入式结构，请参阅基于请求的 SLI 的结构。

服务等级目标

服务等级目标 (SLO) 由 ServiceLevelObjective 对象表示。此对象包含以下字段：

名称
显示名称
目标 SLI，这是一个嵌入的 ServiceLevelIndicator 对象
SLI 的性能目标
SLI 的合规期

以下显示了一个 SLO 的 JSON 表示法，该 SLO 使用基本可用性 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% 的可用性。