<commit_before># SLO Generator

![test](https://github.com/google/slo-generator/workflows/test/badge.svg)
![build](https://github.com/google/slo-generator/workflows/build/badge.svg)
![deploy](https://github.com/google/slo-generator/workflows/deploy/badge.svg)

[![PyPI version](https://badge.fury.io/py/slo-generator.svg)](https://badge.fury.io/py/slo-generator)

`slo-generator` is a tool to compute and export **Service Level Objectives** ([SLOs](https://landing.google.com/sre/sre-book/chapters/service-level-objectives/)),
**Error Budgets** and **Burn Rates**, using configurations written in YAML (or JSON) format.

***IMPORTANT NOTE: the following content is the `slo-generator` v2 documentation. The v1 documentation is available [here](https://github.com/google/slo-generator/tree/v1.5.1), and instructions to migrate to v2 are available [here](https://github.com/google/slo-generator/blob/master/docs/shared/migration.md).***

## Table of contents
- [Description](#description)
- [Local usage](#local-usage)
  - [Requirements](#requirements)
  - [Installation](#installation)
  - [CLI usage](#cli-usage)
  - [API usage](#api-usage)
- [Configuration](#configuration)
  - [SLO configuration](#slo-configuration)
  - [Shared configuration](#shared-configuration)
- [More documentation](#more-documentation)
  - [Build an SLO achievements report with BigQuery and DataStudio](#build-an-slo-achievements-report-with-bigquery-and-datastudio)
  - [Deploy the SLO Generator in Cloud Run](#deploy-the-slo-generator-in-cloud-run)
  - [Deploy the SLO Generator in Kubernetes (Alpha)](#deploy-the-slo-generator-in-kubernetes-alpha)
  - [Deploy the SLO Generator in a CloudBuild pipeline](#deploy-the-slo-generator-in-a-cloudbuild-pipeline)
  - [DEPRECATED: Deploy the SLO Generator on Google Cloud Functions (Terraform)](#deprecated-deploy-the-slo-generator-on-google-cloud-functions-terraform)
  - [Contribute to the SLO Generator](#contribute-to-the-slo-generator)

## Description
The `slo-generator` runs backend queries computing **Service Level Indicators**, 
compares them with the **Service Level Objectives** defined and generates a report 
by computing important metrics:

* **Service Level Indicator** (SLI) defined as **SLI = N<sub>good_events</sub> &#47; N<sub>valid_events</sub>**
* **Error Budget** (EB) defined as **EB = 1 - SLI**
* **Error Budget Burn Rate** (EBBR) defined as **EBBR = EB / EB<sub>target</sub>**
* **... and more**, see the [example SLO report](./test/unit/../../tests/unit/fixtures/slo_report_v2.json).

The **Error Budget Burn Rate** is often used for [**alerting on SLOs**](https://sre.google/workbook/alerting-on-slos/), as it demonstrates in practice to be more **reliable** and **stable** than 
alerting directly on metrics or on **SLI > SLO** thresholds.

## Local usage

### Requirements

* `python3.7` and above
* `pip3`

### Installation

`slo-generator` is a Python library published on [PyPI](https://pypi.org). To install it, run:

```sh
pip3 install slo-generator
```

***Notes:***
* To install **[providers](./docs/providers)**, use `pip3 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 the **slo-generator API**, run `pip3 install slo-generator[api]`.
* To enable **debug logs**, set the environment variable `DEBUG` to `1`.
* To enable **colorized output** (local usage), set the environment variable `COLORED_OUTPUT` to `1`.

### CLI usage

To compute an SLO report using the CLI, run:
```
slo-generator compute -f <SLO_CONFIG_PATH> -c <SHARED_CONFIG_PATH> --export
```
where:
  * `<SLO_CONFIG_PATH>` is the [SLO configuration](#slo-configuration) file or folder path.

  * `<SHARED_CONFIG_PATH>` is the [Shared configuration](#shared-configuration) file path.

  * `--export` | `-e` enables exporting data using the `exporters` specified in the SLO
  configuration file.

Use `slo-generator compute --help` to list all available arguments.

### API usage

On top of the CLI, the `slo-generator` can also be run as an API using the Cloud 
Functions Framework SDK (Flask):
```
slo-generator api -c <SHARED_CONFIG_PATH>
```
where:
  * `<SHARED_CONFIG_PATH>` is the [Shared configuration](#shared-configuration) file path or GCS URL.

Once the API is up-and-running, you can `HTTP POST` SLO configurations (YAML or JSON) to it:

```
curl -X POST -H "Content-Type: text/x-yaml" --data-binary @slo.yaml ${SERVICE_URL} # yaml SLO config
curl -X POST -H "Content-Type: application/json" -d @slo.json ${SERVICE_URL} # json SLO config<commit_msg>docs: update readme<commit_after># SLO Generator

![test](https://github.com/google/slo-generator/workflows/test/badge.svg)
![build](https://github.com/google/slo-generator/workflows/build/badge.svg)
![deploy](https://github.com/google/slo-generator/workflows/deploy/badge.svg)

[![PyPI version](https://badge.fury.io/py/slo-generator.svg)](https://badge.fury.io/py/slo-generator)

`slo-generator` is a tool to compute and export **Service Level Objectives** ([SLOs](https://landing.google.com/sre/sre-book/chapters/service-level-objectives/)),
**Error Budgets** and **Burn Rates**, using configurations written in YAML (or JSON) format.

***IMPORTANT NOTE: the following content is the `slo-generator` v2 documentation. The v1 documentation is available [here](https://github.com/google/slo-generator/tree/v1.5.1), and instructions to migrate to v2 are available [here](https://github.com/google/slo-generator/blob/master/docs/shared/migration.md).***

## Table of contents
- [Description](#description)
- [Local usage](#local-usage)
  - [Requirements](#requirements)
  - [Installation](#installation)
  - [CLI usage](#cli-usage)
  - [API usage](#api-usage)
- [Configuration](#configuration)
  - [SLO configuration](#slo-configuration)
  - [Shared configuration](#shared-configuration)
- [More documentation](#more-documentation)
  - [Build an SLO achievements report with BigQuery and DataStudio](#build-an-slo-achievements-report-with-bigquery-and-datastudio)
  - [Deploy the SLO Generator in Cloud Run](#deploy-the-slo-generator-in-cloud-run)
  - [Deploy the SLO Generator in Kubernetes (Alpha)](#deploy-the-slo-generator-in-kubernetes-alpha)
  - [Deploy the SLO Generator in a CloudBuild pipeline](#deploy-the-slo-generator-in-a-cloudbuild-pipeline)
  - [DEPRECATED: Deploy the SLO Generator on Google Cloud Functions (Terraform)](#deprecated-deploy-the-slo-generator-on-google-cloud-functions-terraform)
  - [Contribute to the SLO Generator](#contribute-to-the-slo-generator)

## Description
The `slo-generator` runs backend queries computing **Service Level Indicators**, 
compares them with the **Service Level Objectives** defined and generates a report 
by computing important metrics:

* **Service Level Indicator** (SLI) defined as **SLI = N<sub>good_events</sub> &#47; N<sub>valid_events</sub>**
* **Error Budget** (EB) defined as **EB = 1 - SLI**
* **Error Budget Burn Rate** (EBBR) defined as **EBBR = EB / EB<sub>target</sub>**
* **... and more**, see the [example SLO report](./test/unit/../../tests/unit/fixtures/slo_report_v2.json).

The **Error Budget Burn Rate** is often used for [**alerting on SLOs**](https://sre.google/workbook/alerting-on-slos/), as it demonstrates in practice to be more **reliable** and **stable** than 
alerting directly on metrics or on **SLI > SLO** thresholds.

## Local usage

### Requirements

* `python3.7` and above
* `pip3`

### Installation

`slo-generator` is a Python library published on [PyPI](https://pypi.org). To install it, run:

```sh
pip3 install slo-generator
```

***Notes:***
* To install **[providers](./docs/providers)**, use `pip3 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 the **slo-generator API**, run `pip3 install slo-generator[api]`.
* To enable **debug logs**, set the environment variable `DEBUG` to `1`.
* To enable **colorized output** (local usage), set the environment variable `COLORED_OUTPUT` to `1`.

### CLI usage

To compute an SLO report using the CLI, run:
```
slo-generator compute -f <SLO_CONFIG_PATH> -c <SHARED_CONFIG_PATH> --export
```
where:
  * `<SLO_CONFIG_PATH>` is the [SLO configuration](#slo-configuration) file or folder path.

  * `<SHARED_CONFIG_PATH>` is the [Shared configuration](#shared-configuration) file path.

  * `--export` | `-e` enables exporting data using the `exporters` specified in the SLO
  configuration file.

Use `slo-generator compute --help` to list all available arguments.

### API usage

On top of the CLI, the `slo-generator` can also be run as an API using the Cloud 
Functions Framework SDK (Flask):
```
slo-generator api -c <SHARED_CONFIG_PATH>
```
where:
  * `<SHARED_CONFIG_PATH>` is the [Shared configuration](#shared-configuration) file path or GCS URL.

Once the API is up-and-running, you can `HTTP POST` SLO configurations (YAML or JSON) to it:

```
curl -X POST -H "Content-Type: text/x-yaml" --data-binary @slo.yaml localhost:8080 # yaml SLO config
curl -X POST -H "Content-Type: application/json" -d @slo.json localhost:8080 # json SLO config
{'fraction_non_alphanumeric': 0.1492771841609051, 'fraction_numerical': 0.005447307772889169, 'mean_word_length': 4.860650705954574, 'pattern_counts': {'":': 0, '<': 33, '<?xml version=': 0, '>': 33, 'https://': 20, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '844834', 'n_tokens_mistral': 3221, 'n_tokens_neox': 2982, 'n_words': 889}