Package: slo-generator
SLO Generatorslo-generatoris a tool to compute and exportService Level Objectives(SLOs),Error BudgetsandBurn Rates, using configurations written in YAML (or JSON) format.IMPORTANT NOTE: the following content is theslo-generatorv2 documentation. The v1 documentation is availablehere, and instructions to migrate to v2 are availablehere.Table of contentsDescriptionLocal usageRequirementsInstallationCLI usageAPI usageConfigurationSLO configurationShared configurationMore documentationBuild an SLO achievements report with BigQuery and DataStudioDeploy the SLO Generator in Cloud RunDeploy the SLO Generator in Kubernetes (Alpha)Deploy the SLO Generator in a CloudBuild pipelineDEPRECATED: Deploy the SLO Generator on Google Cloud Functions (Terraform)Contribute to the SLO GeneratorDescriptionTheslo-generatorruns backend queries computingService Level Indicators, compares them with theService Level Objectivesdefined and generates a report by computing important metrics:Service Level Indicator(SLI) defined asSLI = Ngood_events/ Nvalid_eventsError Budget(EB) defined asEB = 1 - SLIError Budget Burn Rate(EBBR) defined asEBBR = EB / EBtarget... and more, see theexample SLO report.TheError Budget Burn Rateis often used foralerting on SLOs, as it demonstrates in practice to be morereliableandstablethan alerting directly on metrics or onSLI > SLOthresholds.Local usageRequirementspython3.7and abovepip3Installationslo-generatoris a Python library published onPyPI. To install it, run:pip3installslo-generatorNotes:To installproviders, usepip3 install slo-generator[<PROVIDER_1>, <PROVIDER_2>, ... <PROVIDER_n]. For instance:pip3 install slo-generator[cloud_monitoring]installs the Cloud Monitoring backend / exporter.pip3 install slo-generator[prometheus, datadog, dynatrace]install the Prometheus, Datadog and Dynatrace, backends / exporters.To install theslo-generator API, runpip3 install slo-generator[api].To enabledebug logs, set the environment variableDEBUGto1.To enablecolorized output(local usage), set the environment variableCOLORED_OUTPUTto1.CLI usageTo compute an SLO report using the CLI, run:slo-generatorcompute-f<SLO_CONFIG_PATH>-c<SHARED_CONFIG_PATH>--exportwhere:<SLO_CONFIG_PATH>is theSLO configurationfile or folder path.<SHARED_CONFIG_PATH>is theShared configurationfile path.--export|-eenables exporting data using theexportersspecified in the SLO
configuration file.Useslo-generator compute --helpto list all available arguments.API usageOn top of the CLI, theslo-generatorcan also be run as an API using the Cloud Functions Framework SDK (Flask) using theapisubcommand:slo-generatorapi--config<SHARED_CONFIG_PATH>where:<SHARED_CONFIG_PATH>is theShared configurationfile path or GCS URL.Once the API is up-and-running, you can make HTTP POST requests with your SLO configurations (YAML or JSON) in the request body:curl-XPOST-H"Content-Type: text/x-yaml"--data-binary@slo.yamllocalhost:8080# yaml SLO configcurl-XPOST-H"Content-Type: application/json"-d@slo.jsonlocalhost:8080# json SLO configTo read more about the API and advanced usage, seedocs/shared/api.md.ConfigurationTheslo-generatorrequires two configuration files to run, anSLO configurationfile, describing your SLO, and theShared configurationfile (common configuration for all SLOs).SLO configurationTheSLO configuration(JSON or YAML) is following the Kubernetes format and is composed of the following fields:api:sre.google.com/v2kind:ServiceLevelObjectivemetadata:name: [required]string- Full SLO name (MUSTbe unique).labels: [optional]map- Metadata labels,for example:slo_name: SLO name (e.gavailability,latency128ms, ...).service_name: Monitored service (to group SLOs by service).feature_name: Monitored feature (to group SLOs by feature).spec:description: [required]string- Description of this SLO.goal: [required]string- SLO goal (or target) (MUSTbe between 0 and 1).backend: [required]string- Backend name (MUSTexist in SLO Generator Configuration).method: [required]string- Backend method to use (MUSTexist in backend class definition).service_level_indicator: [required]map- SLI configuration. The content of this section is
specific to each provider, seedocs/providers.error_budget_policy: [optional]string- Error budget policy name
(MUSTexist in SLO Generator Configuration). If not specified, defaults todefault.exporters: [optional]string- List of exporter names (MUSTexist in SLO Generator Configuration).Note:you can use environment variables in your SLO configs by using${MY_ENV_VAR}syntax to avoid having sensitive data in version control. Environment variables will be replaced automatically at run time.→ Seeexample SLO configuration.Shared configurationThe shared configuration (JSON or YAML) configures theslo-generatorand acts as a shared config for all SLO configs. It is composed of the following fields:backends: [required]map- Data backends configurations. Each backend alias is defined as a key<backend_name>/<suffix>, and a configuration map.backends:cloud_monitoring/dev:project_id:proj-cm-dev-a4b7datadog/test:app_key:${APP_SECRET_KEY}api_key:${API_SECRET_KEY}See specific providers documentation for detailed configuration:cloud_monitoringcloud_service_monitoringprometheuselasticsearchdatadogdynatrace<custom>exporters: A map of exporters to export results to. Each exporter is defined as a key formatted as<exporter_name>/<optional_suffix>, and a map value detailing the exporter configuration.exporters:bigquery/dev:project_id:proj-bq-dev-a4b7dataset_id:my-test-datasettable_id:my-test-tableprometheus:url:${PROMETHEUS_URL}See specific providers documentation for detailed configuration:bigqueryto export SLO reports to BigQuery for historical analysis and DataStudio reporting.cloudeventto stream SLO reports to Cloudevent receivers.pubsubto stream SLO reports to Pubsub.cloud_monitoringto export metrics to Cloud Monitoring.prometheusto export metrics to Prometheus.datadogto export metrics to Datadog.dynatraceto export metrics to Dynatrace.<custom>to export SLO data or metrics to a custom destination.error_budget_policies: [required] A map of various error budget policies.<ebp_name>: Name of the error budget policy.steps: List of error budget policy steps, each containing the following fields:window: Rolling time window for this error budget.alerting_burn_rate_threshold: Target burnrate threshold over which alerting is needed.urgent_notification: boolean whether violating this error budget should trigger a page.overburned_consequence_message: message to show when the error budget is above the target.achieved_consequence_message: message to show when the error budget is within the target.error_budget_policies:default:steps:-name:1 hourburn_rate_threshold:9alert:truemessage_alert:Page to defend the SLOmessage_ok:Last hour on trackwindow:3600-name:12 hoursburn_rate_threshold:3alert:truemessage_alert:Page to defend the SLOmessage_ok:Last 12 hours on trackwindow:43200→ Seeexample Shared configuration.More documentationTo go further with the SLO Generator, you can read:Build an SLO achievements report with BigQuery and DataStudioDeploy the SLO Generator in Cloud RunDeploy the SLO Generator in Kubernetes (Alpha)Deploy the SLO Generator in a CloudBuild pipelineDEPRECATED: Deploy the SLO Generator on Google Cloud Functions (Terraform)Contribute to the SLO Generator