REST Resource: services.serviceLevelObjectives

Resource: ServiceLevelObjective

A Service-Level Objective (SLO) describes a level of desired good service. It consists of a service-level indicator (SLI), a performance goal, and a period over which the objective is to be evaluated against that goal. The SLO can use SLIs defined in a number of different manners. Typical SLOs might include "99% of requests in each rolling week have latency below 200 milliseconds" or "99.5% of requests in each calendar month return successfully."

JSON representation 
{
  "name": string,
  "displayName": string,
  "serviceLevelIndicator": {
    object (ServiceLevelIndicator)
  },
  "goal": number,
  "userLabels": {
    string: string,
    ...
  },

  // 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.
}
Fields
name

string

Identifier. Resource name for this ServiceLevelObjective. The format is:

projects/[PROJECT_ID_OR_NUMBER]/services/[SERVICE_ID]/serviceLevelObjectives/[SLO_NAME]
displayName

string

Name used for UI elements listing this SLO.
serviceLevelIndicator

object (ServiceLevelIndicator)

The definition of good service, used to measure and calculate the quality of the Service's performance with respect to a single aspect of service quality.
goal

number

The fraction of service that must be good in order for this objective to be met. 0 < goal <= 0.9999.
userLabels

map (key: string, value: string)

Labels which have been used to annotate the service-level objective. Label keys must start with a letter. Label keys and values may contain lowercase letters, numbers, underscores, and dashes. Label keys and values have a maximum length of 63 characters, and must be less than 128 bytes in size. Up to 64 label entries may be stored. For labels which do not have a semantic value, the empty string may be supplied for the label value.
Union field period. The time period over which the objective will be evaluated. period can be only one of the following:
rollingPeriod

string (Duration format)

A rolling time period, semantically "in the past <rollingPeriod>". Must be an integer multiple of 1 day no larger than 30 days.
calendarPeriod

enum (CalendarPeriod)

A calendar period, semantically "since the start of the current <calendarPeriod>". At this time, only DAY, WEEK, FORTNIGHT, and MONTH are supported.

ServiceLevelIndicator

A Service-Level Indicator (SLI) describes the "performance" of a service. For some services, the SLI is well-defined. In such cases, the SLI can be described easily by referencing the well-known SLI and providing the needed parameters. Alternatively, a "custom" SLI can be defined with a query to the underlying metric store. An SLI is defined to be good_service / total_service over any queried time interval. The value of performance always falls into the range 0 <= performance <= 1. A custom SLI describes how to compute this ratio, whether this is by dividing values from a pair of time series, cutting a Distribution into good and bad counts, or counting time windows in which the service complies with a criterion. For separation of concerns, a single Service-Level Indicator measures performance for only one aspect of service quality, such as fraction of successful queries or fast-enough queries.

JSON representation 
{

  // Union field type can be only one of the following:
  "basicSli": {
    object (BasicSli)
  },
  "requestBased": {
    object (RequestBasedSli)
  },
  "windowsBased": {
    object (WindowsBasedSli)
  }
  // End of list of possible types for union field type.
}
Fields
Union field type. Service level indicators can be grouped by whether the "unit" of service being measured is based on counts of good requests or on counts of good time windows type can be only one of the following:
basicSli

object (BasicSli)

Basic SLI on a well-known service type.
requestBased

object (RequestBasedSli)

Request-based SLIs
windowsBased

object (WindowsBasedSli)

Windows-based SLIs

BasicSli

An SLI measuring performance on a well-known service type. Performance will be computed on the basis of pre-defined metrics. The type of the service_resource determines the metrics to use and the service_resource.labels and metricLabels are used to construct a monitoring filter to filter that metric down to just the data relevant to this service.

JSON representation 
{
  "method": [
    string
  ],
  "location": [
    string
  ],
  "version": [
    string
  ],

  // Union field sli_criteria can be only one of the following:
  "availability": {
    object (AvailabilityCriteria)
  },
  "latency": {
    object (LatencyCriteria)
  }
  // End of list of possible types for union field sli_criteria.
}
Fields
method[]

string

OPTIONAL: The set of RPCs to which this SLI is relevant. Telemetry from other methods will not be used to calculate performance for this SLI. If omitted, this SLI applies to all the Service's methods. For service types that don't support breaking down by method, setting this field will result in an error.
location[]

string

OPTIONAL: The set of locations to which this SLI is relevant. Telemetry from other locations will not be used to calculate performance for this SLI. If omitted, this SLI applies to all locations in which the Service has activity. For service types that don't support breaking down by location, setting this field will result in an error.
version[]

string

OPTIONAL: The set of API versions to which this SLI is relevant. Telemetry from other API versions will not be used to calculate performance for this SLI. If omitted, this SLI applies to all API versions. For service types that don't support breaking down by version, setting this field will result in an error.
Union field sli_criteria. This SLI can be evaluated on the basis of availability or latency. sli_criteria can be only one of the following:
availability

object (AvailabilityCriteria)

Good service is defined to be the count of requests made to this service that return successfully.
latency

object (LatencyCriteria)

Good service is defined to be the count of requests made to this service that are fast enough with respect to latency.threshold.

AvailabilityCriteria

This type has no fields.

Future parameters for the availability SLI.

LatencyCriteria

Parameters for a latency threshold SLI.

JSON representation 
{
  "threshold": string
}
Fields
threshold

string (Duration format)

Good service is defined to be the count of requests made to this service that return in no more than threshold.

RequestBasedSli

Service Level Indicators for which atomic units of service are counted directly.

JSON representation 
{

  // Union field method can be only one of the following:
  "goodTotalRatio": {
    object (TimeSeriesRatio)
  },
  "distributionCut": {
    object (DistributionCut)
  }
  // End of list of possible types for union field method.
}
Fields
Union field method. The means to compute a ratio of good_service to total_service. method can be only one of the following:
goodTotalRatio

object (TimeSeriesRatio)

goodTotalRatio is used when the ratio of good_service to total_service is computed from two TimeSeries.
distributionCut

object (DistributionCut)

distributionCut is used when good_service is a count of values aggregated in a Distribution that fall into a good range. The total_service is the total count of all values aggregated in the Distribution.

TimeSeriesRatio

A TimeSeriesRatio specifies two TimeSeries to use for computing the good_service / total_service ratio. The specified TimeSeries must have ValueType = DOUBLE or ValueType = INT64 and must have MetricKind = DELTA or MetricKind = CUMULATIVE. The TimeSeriesRatio must specify exactly two of good, bad, and total, and the relationship good_service + bad_service = total_service will be assumed.

JSON representation 
{
  "goodServiceFilter": string,
  "badServiceFilter": string,
  "totalServiceFilter": string
}
Fields
goodServiceFilter

string

A monitoring filter specifying a TimeSeries quantifying good service provided. Must have ValueType = DOUBLE or ValueType = INT64 and must have MetricKind = DELTA or MetricKind = CUMULATIVE.
badServiceFilter

string

A monitoring filter specifying a TimeSeries quantifying bad service, either demanded service that was not provided or demanded service that was of inadequate quality. Must have ValueType = DOUBLE or ValueType = INT64 and must have MetricKind = DELTA or MetricKind = CUMULATIVE.
totalServiceFilter

string

A monitoring filter specifying a TimeSeries quantifying total demanded service. Must have ValueType = DOUBLE or ValueType = INT64 and must have MetricKind = DELTA or MetricKind = CUMULATIVE.

DistributionCut

A DistributionCut defines a TimeSeries and thresholds used for measuring good service and total service. The TimeSeries must have ValueType = DISTRIBUTION and MetricKind = DELTA or MetricKind = CUMULATIVE. The computed good_service will be the estimated count of values in the Distribution that fall within the specified min and max.

JSON representation 
{
  "distributionFilter": string,
  "range": {
    object (Range)
  }
}
Fields
distributionFilter

string

A monitoring filter specifying a TimeSeries aggregating values. Must have ValueType = DISTRIBUTION and MetricKind = DELTA or MetricKind = CUMULATIVE.
range

object (Range)

Range of values considered "good." For a one-sided range, set one bound to an infinite value.

Range

Range of numerical values within min and max.

JSON representation 
{
  "min": number,
  "max": number
}
Fields
min

number

Range minimum.
max

number

Range maximum.

WindowsBasedSli

A WindowsBasedSli defines good_service as the count of time windows for which the provided service was of good quality. Criteria for determining if service was good are embedded in the window_criterion.

JSON representation 
{
  "windowPeriod": string,

  // Union field window_criterion can be only one of the following:
  "goodBadMetricFilter": string,
  "goodTotalRatioThreshold": {
    object (PerformanceThreshold)
  },
  "metricMeanInRange": {
    object (MetricRange)
  },
  "metricSumInRange": {
    object (MetricRange)
  }
  // End of list of possible types for union field window_criterion.
}
Fields
windowPeriod

string (Duration format)

Duration over which window quality is evaluated. Must be an integer fraction of a day and at least 60s.
Union field window_criterion. The criterion to use for evaluating window goodness. window_criterion can be only one of the following:
goodBadMetricFilter

string

A monitoring filter specifying a TimeSeries with ValueType = BOOL. The window is good if any true values appear in the window.
goodTotalRatioThreshold

object (PerformanceThreshold)

A window is good if its performance is high enough.
metricMeanInRange

object (MetricRange)

A window is good if the metric's value is in a good range, averaged across returned streams.
metricSumInRange

object (MetricRange)

A window is good if the metric's value is in a good range, summed across returned streams.

PerformanceThreshold

A PerformanceThreshold is used when each window is good when that window has a sufficiently high performance.

JSON representation 
{
  "threshold": number,

  // Union field type can be only one of the following:
  "performance": {
    object (RequestBasedSli)
  },
  "basicSliPerformance": {
    object (BasicSli)
  }
  // End of list of possible types for union field type.
}
Fields
threshold

number

If window performance >= threshold, the window is counted as good.
Union field type. The means, either a request-based SLI or a basic SLI, by which to compute performance over a window. type can be only one of the following:
performance

object (RequestBasedSli)

RequestBasedSli to evaluate to judge window quality.
basicSliPerformance

object (BasicSli)

BasicSli to evaluate to judge window quality.

MetricRange

A MetricRange is used when each window is good when the value x of a single TimeSeries satisfies range.min <= x <= range.max. The provided TimeSeries must have ValueType = INT64 or ValueType = DOUBLE and MetricKind = GAUGE.

JSON representation 
{
  "timeSeries": string,
  "range": {
    object (Range)
  }
}
Fields
timeSeries

string

A monitoring filter specifying the TimeSeries to use for evaluating window quality.
range

object (Range)

Range of values considered "good." For a one-sided range, set one bound to an infinite value.

CalendarPeriod

A CalendarPeriod represents the abstract concept of a time period that has a canonical start. Grammatically, "the start of the current CalendarPeriod." All calendar times begin at midnight UTC.

Enums
CALENDAR_PERIOD_UNSPECIFIED Undefined period, raises an error.
DAY A day.
WEEK A week. Weeks begin on Monday, following ISO 8601.
FORTNIGHT A fortnight. The first calendar fortnight of the year begins at the start of week 1 according to ISO 8601.
MONTH A month.
QUARTER A quarter. Quarters start on dates 1-Jan, 1-Apr, 1-Jul, and 1-Oct of each year.
HALF A half-year. Half-years start on dates 1-Jan and 1-Jul.
YEAR A year.

Methods

create

 Create a ServiceLevelObjective for the given Service.

delete

 Delete the given ServiceLevelObjective.

get

 Get a ServiceLevelObjective by name.

list

 List the ServiceLevelObjectives for the given Service.

patch

 Update the given ServiceLevelObjective.