Retrieving SLO data

SLO data is stored in time series, but these time series can't be retrieved by specifying a metric type and monitored resource to a console component like Metrics Explorer or the timeSeries.list method in the Cloud Monitoring API.

Instead, you retrieve SLO time series by specifying a time-series selector in the filter parameter to the timeSeries.list method.

Using a time-series selector in a filter

The usual approach to retrieving time-series data is that you specify a filter consisting of a pair of metric and monitored-resource types that identify a set of time series. SLO data isn't stored with standard metric types and can't be retrieved with this kind of filter. To retrieve time-series data for SLOs, your filter must specify a time-series selector instead.

Names and arguments

Time-series selectors have one of the following forms:

SELECTOR_NAME(SLO_NAME)
SELECTOR_NAME(SLO_NAME, LOOKBACK_PERIOD)

The selectors have names that start with select_slo_ and take one or two arguments:

  • The first argument to the selector is the resource name for an SLO, which looks like this:

    projects/[PROJECT_ID]/services/[SERVICE_ID]/serviceLevelObjectives/[SLO_ID]
    

  • The second argument, if supported, is a lookback period. See Types of error-budget alerts for information on lookback periods. Valid time units are "ns", "us" "ms", "s", "m", "h".

For example, the select_slo_budget selector takes only the SLO-name argument, so a filter using this selector looks like the following:

select_slo_budget("projects/[PROJECT_ID]/services/[SERVICE_ID]/serviceLevelObjectives/[SLO_ID]")

In contrast, the select_slo_burn_rate selector also takes a lookback period, so a filter using this selector looks like the following:

select_slo_burn_rate("projects/[PROJECT_ID]/services/[SERVICE_ID]/serviceLevelObjectives/[SLO_ID]", "3600s")

For a list and description of all the selectors, see Time-series selectors.

Retrieving data with a selector

A straight-forward way to query time-series data is by using the API Explorer tool on the timeSeries.list method's reference page. For information on the API Explorer tool, see API Explorer.

The following screenshot shows the use, in API Explorer, of the select_slo_budget time-series selector as a filter for timeSeries.list:

Specifying a time-series selector to the timeSeries.list method.

The following shows a fragment of the returned time-series data:

An excerpt from the retrieved time series

Time-series selectors

This section lists the available time-series selectors for SLOs and describes what they represent. All the selectors can be used in filters for timeSeries.list to retrieve time-series data. Not all of them are supported in alerting policies.

select_slo_burn_rate

Syntax: select_slo_burn_rate(SLO_NAME, LOOKBACK_PERIOD)

The “burn-rate” time-series selector returns the ratio of the current failure rate (the rate of bad requests in the lookback interval) to the sustainable failure rate for the SLO. The sustainable failure rate is the rate at which the SLO is exactly met: a value of 1 means that the service exhibits the ideal failure rate: not too risky, not too conservative.

The values in this time series can range from 0 to infinity. A value greater than 1 means the failure rate exceeds the sustainable rate. The higher the value, the sooner the SLO falls out of compliance.

Use two alerting policies to monitor burn rate: a fast-burn policy to alert you to spikes in the burn rate, and a slow-burn policy to alert you to gradual increases. For more information, see Creating the alerting policy.

select_slo_health

Syntax: select_slo_health(SLO_NAME)

The “SLO health” time series answers the question, “During a given output period, what was the ratio of good requests to total requests?” What counts as a good request is defined by the SLI for the service.

This time series measures service performance: if every request to the service is good, then the data points in this time series have the value 1. As the number of bad requests rise, the values of the data points drop.

You can create alerting policies that use this time-series selector by using the API, and you can only edit these policies by using the API.

select_slo_compliance

Syntax: select_slo_compliance(SLO_NAME)

The “SLO compliance” time series answers the question, “Measuring the behavior of the service since the beginning of the compliance period, measured in calendar time or as a rolling window, what is the ratio of good units to total units at this point?” The unit can be a request or a window of time. See Compliance in request- and windows-based SLOs for more information.

This time series gives you a general picture of how well the service is meeting the SLO. It doesn't produce an operationally urgent signal.

Do not use this time-series selector in alerting policies.

select_slo_budget

Syntax: select_slo_budget(SLO_NAME)

The “SLO budget” time series answers the question, “How much of the error budget remained at the time of the measurement?” The error budget might be measured in requests or minutes, and the amount remaining is computed based on whether the compliance period is measured in calendar time or as a rolling window. See Error budgets for more information.

This time series measures the risk in a service's reliability. If the error budget goes below 0, even if the service performs perfectly going forward, it might not be possible to meet the SLO for the current period. A failure to meet the SLO might have real consequences for an organization's production environment, depending on how the organization governs reliability.

Do not use this time-series selector in alerting policies.

select_slo_budget_fraction

Syntax: select_slo_budget_fraction(SLO_NAME)

The “SLO budget fraction” time series answers the question, “How much of the error budget, as a fraction from 0 to 1, remains at this time?”

Do not use this time-series selector in alerting policies.

select_slo_budget_total

Syntax: select_slo_budget_total(SLO_NAME)

The “SLO total budget” time series answers the question, “What is the total error budget (in requests or minutes) that is projected to be available at this time, based on the behavior of the service since the start of the compliance period, either calendar-time or rolling-window?”

Do not use this time-series selector in alerting policies.

select_slo_counts

Syntax: select_slo_counts(SLO_NAME)

The “SLO counts” time series answers the question, “During a given output period, what is the number of good and bad requests?” This selector provides a time series that records general health and is suitable for ingestion into long-term storage systems.

Do not use this time-series selector in alerting policies.