This document introduces the structures used to represent services and SLOs inthe SLO API and maps them to the concepts described in generally inConcepts in service monitoring.

The SLO API is used to set up service-level objectives (SLOs) that can beused to monitor the health of your services.

Service Monitoring adds the following resources to the Monitoring API:

• services
• services.serviceLevelObjectives

For information on invoking the API, seeWorking with the API.

Services

A service is represented by aService object.This object includes the following fields:

• A name: A fully qualified resource name for this service
• A display name: A label for use in console components
• A structure for one of theBasicService types.
• A system-provided telemetry-configuration object

To define a basic service, you specify the type of service and providea set of service-specific labels that describe the service:

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

The following sections provide examples for each type of service.

Basic service types

This section provides examples of services definitions built on theBasicService type, where the value of theserviceType field is one of the following:

• APP_ENGINE
• CLOUD_ENDPOINTS
• CLUSTER_ISTIO
• ISTIO_CANONICAL_SERVICE
• CLOUD_RUN

Each of these service types uses theBasicSliservice-level indicator.

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

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

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

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

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

Basic GKE service types

This section contains examples of GKE service definitionsbuilt on theBasicService type, where the valueof theserviceType field is one of the following:

• GKE_NAMESPACE
• GKE_WORKLOAD
• GKE_SERVICE

You must define SLIs for these service types. They can't useBasicSli service-level indicators.For more information, seeService-level indicators.

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

    {      "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",          }      },    }

    {      "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"          }      },    }

Custom services

You can create custom services if none of the basic service types is suitable.A custom service looks like the following:

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

You must define SLIs for these service types. They can't useBasicSli service-level indicators.For more information, seeService-level indicators.

Service-level indicators

A service-level indicator (SLI) provides a measure of the performance of a service.An SLI is based on metric captured by the service. Exactly how the SLI isdefined depends on the type of metric used as the indicator metric, butit is generally some comparison between acceptable results and total results.

A SLI is represented by theServiceLevelIndicator object. This object isa collective way to refer the three supported types ofSLIs:

• A basic SLI, which is created automatically for instances of thetheBasicService service type.This type of SLI is described inService-level-objectives;it is represented by aBasicSli object and measuresavailability or latency.

• A request-based SLI, which you can use to count events that representacceptable service.Use of this type of SLI is described inRequest-based SLOs;it is represented by aRequestBasedSli object.

• A window-based SLI, which you can use to count periods of time thatmeet some goodness criterion.Use of this type of SLI is described inWindows-based SLOs;it is represented by aWindowsBasedSli object.

For example, the following shows a basic availability SLI:

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

Structures for request-based SLIs

A request-based SLI is based on a metric that counts units of serviceas a ratio between a particular outcome and the total. For example,if you use a metric that counts requests, you can build the ratio betweenthe number of requests that return success and the total number of requests.

There are two ways to build a request-based SLI:

• As aTimeSeriesRatio, when the ratioof good service to total service is computed from two time serieswhose values have a metric kind ofDELTA orCUMULATIVE.
• As aDistributionCut, when thetime series has value typeDISTRIBUTION andwhose values have a metric kind ofDELTA orCUMULATIVE.The good-service value is the count of items that fall into thehistogram buckets in a specified range, and the total is the count of allvalues in the distribution.

The following shows the JSON representation of an SLI that uses atime-series ratio:

{  "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",    }  }}

The time series in this ratio are identified by the pair of monitored-resourcetype and metric type:

• Resource:https_lb_rule
• Metric type:loadbalancing.googleapis.com/https/request_count

The value for thetotalServiceFilter is represented by the pair ofmetric and resource type. The value for thegoodServiceFilter is representedby the same pair but where some label has a particular value; in this case,when the value of theresponse_code_class label is200.

The ratio between the filters measures the number of requests that return a2xx HTTP status over the total number of requests.

The following shows the JSON representation of an SLI that uses a distributioncut:

{  "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      }    }  }}

The time series is identified by the monitored-resource type, metric type, andvalue for a metric label:

• Resource:https_lb_rule
• Metric type:loadbalancing.googleapis.com/https/backend_latencies
• Label-value pair:response_code_class =200

The range of latencies considered good is designated by therange field.This SLI computes the ratio of latencies of 2xx-class responses below 500to the latencies of all 200-class responses.

Structures for windows-based SLIs

A windows-based SLI counts time windows in which the provided service isconsidered good. The criterion for determining how good service is partof the SLI definition.

All windows-based SLIs include a window period, 60–86,400 seconds (1 day).

There are two ways to specify the good-service criterion for a windows-basedSLI:

• Create a filter string, described inMonitoring filters thatreturns a time series with boolean values. A window is good if the valuefor that window istrue. This filter is called thegoodBadMetricFilter.

• Create aPerformanceThreshold object thatrepresents a threshold for acceptable performance. This object isspecified as the value of thegoodTotalRatioThreshold.

  APerformanceThreshold object specifies a threshold value anda performance SLI. If the value of the performance SLI meets orexceeds the threshold value, then the time window counts as good.

  There are two ways to specify the performance SLI:

  • As aBasicSli object in thebasicPerformanceSlifield.
  • As aRequestBasedSli object in theperformancefield. If you use a request-based SLI, then the metric kind of yourSLI must beDELTA orCUMULATIVE. You can't useGAUGE metricsin request-based SLIs.

The following shows the JSON representation a windows-based SLI built on aperformance threshold for a basic availability SLI:

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

This SLI specifies good performance as a 5-minute window in which availabilityreaches 90% or better. The structure of a basic SLI is shown inService-levelindicators.

You can also embed a request-based SLI in the windows-based SLI. For moreinformation on the embedded structures, seeStructures for request-basedSLIs.

Service-level objectives

A service-level objective (SLO) is represented by aServiceLevelObjective object. This object includes the followingfields:

• A name
• A display name
• The target SLI; an embeddedServiceLevelIndicator object
• The performance goal for the SLI
• The compliance period for the SLI

The following shows the JSON representation of an SLO that uses a basicavailability SLI as the value of theserviceLevelIndicator field:

{   "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"}

This SLO sets the performance goal at 98 percent availability over aperiod of a week.