Retrieving SLO data

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

Instead, SLO time series are retrieved 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 wtih 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:


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:


  • 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:


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 of the selectors can be used in filters for timeSeries.list to retrieve time-series data. Not all of them are supported in alerting policies.


Syntax: select_slo_burn_rate(SLO_NAME, LOOKBACK_PERIOD)

The “burn-rate” time-series selector returns the ratio of the 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 above 1 means the failure rate is above the sustainable rate. The higher the value, the sooner the SLO falls out of compliance.

When you create an alerting policy as described in Creating SLO-based alerting policies with the UI, this selector is used to retrieve the SLO data.

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.

This time-series selector is used in SLO-based alerting policies created with the Stackdriver Monitoring console. You can create and edit alerting policies based on this time-series selector by using the API or the Monitoring console.


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.


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.


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. This might have real consequences for the user's production environment, depending on how an organization governs reliability.

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


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 between 0 and 1, remains at this time?”

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


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.