Generate SLO document

It's recommended to document your defined SLO to ensure that other teams and stakeholders can review and understand it. slom supports generating an SLO document from the spec file using a template.

Add annotations and labels to the spec

First, update the previous SLO spec to add labels and annotations.

example.yaml

name: example

labels: # (1)!
  environment: production

annotations: # (2)!
  author: john.doe

slos:
  - name: availability
    annotations: # (3)!
      description: 99% of requests were served successfully.
      clarification_and_caveats: |-
        - Request metrics are measured at the load balancer.
        - We only count HTTP 5XX status messages as error codes; everything else is counted as success.
    objective:
      ratio: 0.99
      windowRef: window-4w
    indicator:
      prometheus:
        errorRatio: >-
          sum by (job) (rate(http_requests_total{job="example", code!~"2.."}[$window])) /
          sum by (job) (rate(http_requests_total{job="example"}[$window]))
        level:
          - job
    alerts:
      - burnRate:
          consumedBudgetRatio: 0.02
          multiWindows:
            shortWindowRef: window-5m
            longWindowRef: window-1h
        alerter:
          prometheus:
            name: SLOHighBurnRate
            labels:
              severity: page
            annotations:
              description: 2% of the error budget has been consumed within 1 hour
      - burnRate:
          consumedBudgetRatio: 0.1
          multiWindows:
            shortWindowRef: window-6h
            longWindowRef: window-3d
        alerter:
          prometheus:
            name: SLOHighBurnRate
            labels:
              severity: ticket
            annotations:
              description: 10% of the error budget has been consumed within 3 days
      - errorBudget:
          consumedBudgetRatio: 0.9
        alerter:
          prometheus:
            name: SLOTooMuchErrorBudgetConsumed
            labels:
              severity: page
            annotations:
              description: 90% of the error budget has been consumed in the current SLO window
    windows:
      - name: window-5m
        rolling:
          duration: 5m
      - name: window-1h
        rolling:
          duration: 1h
      - name: window-6h
        rolling:
          duration: 6h
      - name: window-3d
        rolling:
          duration: 3d
      - name: window-4w
        rolling:
          duration: 4w

1. Added labels to indicate the groups to which this SLO specification belongs.
2. Added annotations to include arbitrary metadata for this SLO spec.
3. Added annotations to include arbitrary metadata for this availability SLO.

Prepare an SLO document template

To render an SLO document, you can use a template file that follows Go's template syntax. Below is an exmaple of an SLO document template, similar to the SLO Documentation Template provided by Google Cloud.

example.tmpl

# SLO Document

This document describes the SLOs for {{ .Name }} service.

| | |
| --- | --- |
| **Author** | {{ .Annotations.author }} |

{{ range .SLOs -}}
## SLO: {{ .Name }}

| | |
| --- | --- |
| **Compliance Period** | {{ .Objective.Window.Duration }} |

### SLI Implementation

| | |
| --- | --- |
| **Source** | {{ .Indicator.Source }} |

```
{{ toYaml .Indicator.Query -}}
```

### SLO Target

{{ .Annotations.description }}

### Clarification and Caveats

{{ .Annotations.clarification_and_caveats }}

{{- end }}

Info

See the Document reference for the available fields.

Generate an SLO document

After preparing an SLO document template file, run slom generate document command to generate a Prometheus rule file based on the SLO spec.

slom generate document -o go-template-file=document.tmpl example.yaml

See the appendix for the result.

Info

slom can also generate an SLO document in formats such as JSON, enabling other tools to render the document as needed. For details, refer to the slom generate document command reference.