Getting started guide

[MunnaTelik]

Hi Laurent, As discussed over the email can you please help us with started with SLO gen? Can you please provide a guide for external customers to get started? We have our metrics in Prometheus and we want to run SLO/SLI on those.
BTW: Due to some restrictions I am not able to use my enterprise account to post. So using personal account for now.
Thanks

[lvaylet]

Thanks a lot for reposting your question here. It is such a good one that I think the whole community can benefit from it.

I agree the documentation could be better, especially for newcomers who are not familiar with the tool already. Let's fix this, so visitors understand what the SLO Generator is, how it works and what kind of problems it solves. Let me create an Issue to work on that and enhance the documentation.

In the meantime, to answer your question as quickly as possible, I recommend you follow the instructions available at https://github.com/google/slo-generator#local-usage.

1. If your backend is Prometheus, install the SLO Generator and the Prometheus provider with pip3 install slo-generator[prometheus].
2. Draw inspiration from https://github.com/google/slo-generator/blob/master/samples/config.yaml to come up with your global, shared config used by the SLO Generator. You can safely remove most of the backends and keep only the prometheus one.
3. Configure the Prometheus backend with environment variables in a .env file next to config.yaml, so your sensitive data (like credentials and secrets) are not exposed directly. Again, draw inspiration from https://github.com/google/slo-generator/blob/master/samples/.env.sample and come up with your own.
4. Draw inspiration from the sample SLO definitions in https://github.com/google/slo-generator/tree/master/samples/prometheus to write your own SLO definitions.
5. Test your configuration locally with slo-generator compute -f <SLO_CONFIG_PATH> -c <SHARED_CONFIG_PATH>, as detailed in https://github.com/google/slo-generator/blob/master/README.md#cli-usage.
6. Add the --export flag (and configure the exporters in config.yaml, like you configured the backends previously) if you need to export the computed values and alerting flags.
7. When you are happy with your local configuration, you can make the SLO Generator available as an API in a container and send POST requests to it, with your SLO definitions defined in the body of the request. Again, some examples are available at https://github.com/google/slo-generator/blob/master/README.md#api-usage. You can even test the API locally before deploying it.

Regarding deployment options, https://github.com/google/slo-generator/blob/master/docs/deploy/cloudrun.md has detailed instructions on how to deploy the SLO Generator API to Google Cloud Run, store the SLO definitions in a Google Cloud Storage bucket and trigger the computations every minute with Google Cloud Scheduler jobs. If you work on another cloud provider, the Docker images are also available from GitHub's own registry, for example with docker pull ghcr.io/google/slo-generator:2.6.0 for the latest version. The Docker images are listed at https://github.com/google/slo-generator/pkgs/container/slo-generator.

Finally, there are multiple README.md files spread across the repository. For example in https://github.com/google/slo-generator/tree/master/samples. Prometheus also has a dedicated documentation in https://github.com/google/slo-generator/blob/master/docs/providers/prometheus.md. Feel free to explore the repository while I work on improving the documentation.

[lvaylet]

After a quick look at the open Issues, I already had #375 and #476. Let's leverage these issues to work on a better documentation.