OpenTelemetry support (#27)

* Refactor autometrics to separate prometheus

The initializer, and instrumentation functions of Prometheus have been
separated into an additional package so that support for open telemetry
can be added more transparently.

Also added support for detecting and reusing the local names of
autometrics package.

Also also make the generator error if it uses non-default objective
targets or latency targets, to avoid letting users have wrong targets in
their files

* Force Go 1.20 for tests

It seems that the tests are dependent on a breaking change in gofmt

* Refactor context to be global per am invocation

This allows to add a flag to allow, or not, custom latencies in the SLOs

* Document git-hook and -custom-latency flag

* Tweak comment generation

Doc comments do not accept Level-2 headings

Add a less alarming sub text to documentation fences

* Refactor: ask for single import in client code

This is done through adding a lot of interfaces and copy pasting to
allow the "descendant" packages (prom and otel implementations) to build
and return "parent" structures (autometrics.Context)

---------

Co-authored-by: Mari <[email protected]>

Author: gagbo

.github/workflows/build.yml

@@ -12,7 +12,7 @@ jobs:
       - name: Set up Go
         uses: actions/setup-go@v3
         with:
-          go-version: "1.18"
+          go-version: "1.20"
           check-latest: true
           cache: true
 

README.md

@@ -20,6 +20,52 @@ A fully working use-case and example of library usage is available in the
 There is a one-time setup phase to prime the code for autometrics. Once this
 phase is accomplished, only calling `go generate` is necessary.
 
+### Install the go generator.
+
+The generator is the binary in cmd/autometrics, so the easiest way to get it is
+to install it through go:
+
+```console
+go install github.com/autometrics-dev/autometrics-go/cmd/autometrics@latest
+```
+
+In order to have `autometrics` visible then, make sure that the directory
+`$GOBIN` (or the default `$GOPATH/bin`) is in your `$PATH`:
+
+``` console
+$ echo "$PATH" | grep -q "${GOBIN:-$GOPATH/bin}" && echo "GOBIN in PATH" || echo "GOBIN not in PATH, please add it"
+GOBIN in PATH
+```
+
+### Import the libraries and initialize the metrics
+
+In the main entrypoint of your program, you need to both add package
+
+``` go
+import (
+	am "github.com/autometrics-dev/autometrics-go/pkg/autometrics/prometheus"
+)
+```
+
+And then in your main function initialize the metrics
+
+``` go
+am.Init(nil, am.DefBuckets)
+```
+
+> **Warning**
+> If you want to enable alerting from Autometrics, you **MUST**
+have the `--latency-ms` values to match the values given in your buckets. The
+values in the buckets are given in _seconds_. By default, the generator will
+error and tell you the valid default values if they don't match.
+If the default values do not match you use case, you can change the buckets in
+the init call, and add a `-custom-latency` argument to the `//go:generate` invocation.
+
+```patch
+-//go:generate autometrics
++//go:generate autometrics -custom-latency
+```
+
 ### Add cookies in your code
 
 Given a starting function like:
@@ -34,7 +80,6 @@ func RouteHandler(args interface{}) error {
 The manual changes you need to do are:
 
 ```go
-// Somewhere in your file, probably at the bottom
 //go:generate autometrics
 
 //autometrics:doc
@@ -50,6 +95,12 @@ value you return for function you want to instrument.
 
 ### Generate the documentation and instrumentation code
 
+Install the go generator using `go install` as usual:
+
+``` console
+go install https://github.com/autometrics-dev/autometrics-go/cmd/autometrics
+```
+
 Once you've done this, the `autometrics` generator takes care of the rest, and you can
 simply call `go generate` with an optional environment variable:
 
@@ -77,13 +128,13 @@ For Prometheus the shortest way is to add the handler code in your main entrypoi
 
 ``` go
 import (
-	"github.com/autometrics-dev/autometrics-go/pkg/autometrics"
+	am "github.com/autometrics-dev/autometrics-go/pkg/autometrics/prometheus"
 	"github.com/prometheus/client_golang/prometheus/promhttp"
 )
 
 
 func main() {
-	autometrics.Init(nil, autometrics.DefBuckets)
+	am.Init(nil, am.DefBuckets)
 	http.Handle("/metrics", promhttp.Handler())
 }
 ```
@@ -114,6 +165,52 @@ The valid arguments for alert generation are:
 - `--latency-target` : latency target for the threshold, between 0 and 100 (so X%
   of calls must last less than `latency-ms` milliseconds). You must specify both
   latency options, or none.
+  
+> **Warning**
+> The generator will error out if you use targets that are not
+supported by the bundled [Alerting rules file](./configs/autometrics.rules.yml).
+Support for custom target is planned but not present at the moment
+  
+## (OPTIONAL) OpenTelemetry Support
+
+Autometrics supports using OpenTelemetry with a prometheus exporter instead of using
+Prometheus to publish the metrics. The changes you need to make are:
+
+- change where the `amImpl` import points to
+```patch
+import (
+-	am "github.com/autometrics-dev/autometrics-go/pkg/autometrics/prometheus"
++	am "github.com/autometrics-dev/autometrics-go/pkg/autometrics/otel"
+)
+```
+- change the call to `amImpl.Init` to the new signature: instead of a registry,
+the `Init` function takes a meter name for the `otel_scope` label of the exported
+metric. You can use the name of the application or its version for example
+
+``` patch
+-	am.Init(nil, am.DefBuckets)
++	am.Init("myApp/v2/prod", am.DefBuckets)
+```
+
+- add the `-otel` flag to the `//go:generate` directive
+
+```patch
+-//go:generate autometrics
++//go:generate autometrics -otel
+```
+
+## (OPTIONAL) Git hook
+
+As autometrics is a Go generator that modifies the source code when run, it
+might be interesting to set up `go generate ./...` to run in a git pre-commit
+hook so that you never forget to run it if you change the source code.
+
+If you use a tool like [pre-commit](https://pre-commit.com/), see their
+documentation about how to add a hook that will run `go generate ./...`.
+
+Otherwise, a simple example has been added in the [configs folder](./configs/pre-commit)
+as an example. You can copy this file in your copy of your project's repository, within
+`.git/hooks` and make sure that the file is executable.
 
 ## Status
 
@@ -125,8 +222,10 @@ the current status
 The first version of the library has _not_ been written by Go experts. Any comment or
 code suggestion as Pull Request is more than welcome!
 
-### Metrics system
+### Support for custom alerting rules generation
 
-For the time being only Prometheus metrics are supported, but the code has been
-written with the possibility to have other systems, like OpenTelemetry,
-integrated in the same way.
+The alerting system for SLOs that Autometrics uses is based on
+[Sloth](https://github.com/slok/sloth), and it has native Go types for
+marshalling/unmarshalling rules, so it should be possible to provide an extra
+binary in this repository, that only takes care of generating a new [rules
+file](./configs/autometrics.rules.yml) with custom objectives.

cmd/autometrics/doc.go

@@ -0,0 +1,22 @@
+// Autometrics runs as Go generator and updates a source file to add usage queries and metric collection to annotated functions.
+//
+// As a Go generator, it relies on the environment variables `GOFILE` and
+// `GOPACKAGE` to find the target file to edit.
+//
+// By default, `autometrics` generates metric collection code for usage with the
+// [Prometheus client library]. If you want to use [OpenTelemetry metrics]
+// instead (with a prometheus exporter for the metrics), pass the `-otel` flag
+// to the invocation.
+//
+// By default, when activating Service Level Objectives (SLOs) `autometrics`
+// does not allow to use latency targets that are outside the default latencies
+// defined in [autometrics.DefBuckets]. If you want to use custom latencies for
+// your latency SLOs, pass the `-custom-latency` flag to the invocation.
+//
+// By default, the generated links in the documentation point to a Prometheus
+// instance at http://localhost:9090. You can use the environment variable
+// `AM_PROMETHEUS_URL` to change the base URL in the documentation links.
+//
+// [Prometheus client library]: https://github.com/prometheus/client_golang
+// [OpenTelemetry metrics]: https://opentelemetry.io/docs/instrumentation/go/
+package main

cmd/autometrics/main.go

@@ -4,24 +4,48 @@ import (
 	"log"
 	"os"
 
-	"github.com/autometrics-dev/autometrics-go/internal/doc"
+	internal "github.com/autometrics-dev/autometrics-go/internal/autometrics"
 	"github.com/autometrics-dev/autometrics-go/internal/generate"
+	"github.com/autometrics-dev/autometrics-go/pkg/autometrics"
 )
 
-const prometheusAddressEnvironmentVariable = "AM_PROMETHEUS_URL"
+const (
+	prometheusAddressEnvironmentVariable = "AM_PROMETHEUS_URL"
+	useOtelFlag                          = "-otel"
+	allowCustomLatencies                 = "-custom-latency"
+	DefaultPrometheusInstanceUrl         = "http://localhost:9090/"
+)
 
 func main() {
 	fileName := os.Getenv("GOFILE")
 	moduleName := os.Getenv("GOPACKAGE")
+	args := os.Args
 
 	prometheusUrl, envVarExists := os.LookupEnv(prometheusAddressEnvironmentVariable)
 	if !envVarExists {
-		prometheusUrl = doc.DefaultPrometheusInstanceUrl
+		prometheusUrl = DefaultPrometheusInstanceUrl
+	}
+
+	implementation := autometrics.PROMETHEUS
+	if contains(args, useOtelFlag) {
+		implementation = autometrics.OTEL
 	}
 
-	promGenerator := doc.NewPrometheusDoc(prometheusUrl)
+	ctx, err := internal.NewGeneratorContext(implementation, prometheusUrl, contains(args, allowCustomLatencies))
+	if err != nil {
+		log.Fatalf("error initialising autometrics context: %s", err)
+	}
 
-	if err := generate.TransformFile(fileName, moduleName, promGenerator); err != nil {
+	if err := generate.TransformFile(ctx, fileName, moduleName); err != nil {
 		log.Fatalf("error transforming %s: %s", fileName, err)
 	}
 }
+
+func contains[T comparable](s []T, e T) bool {
+	for _, v := range s {
+		if v == e {
+			return true
+		}
+	}
+	return false
+}

configs/pre-commit

@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+
+# This pre-commit hook runs "go generate over all .go files that are staged"
+
+STAGED_GO_FILES=$(git diff --cached --name-only -- '*.go')
+
+if [[ $STAGED_GO_FILES == "" ]]; then
+    echo "No Go Files to check"
+else
+    for file in $STAGED_GO_FILES; do
+        go generate $file
+        git add $file
+    done
+fi

examples/otel/.gitignore

@@ -0,0 +1,8 @@
+# Local build of autometrics-dev/autometrics-go/cmd/autometrics
+/autometrics
+
+# Local build of the example server
+/web-server
+
+# Local file that holds Slack secret webhook URL for alerts
+slack_url.txt

examples/otel/Dockerfile

@@ -0,0 +1,17 @@
+FROM golang:1.20-alpine
+MAINTAINER Fiberplane <[email protected]>
+
+# Cannot really build the demo image from
+# the examples subfolder because of
+# relative imports shenanigans that go out of build context (i.e. upwards)
+#
+# Use
+# GOOS=linux GOARCH=amd64 go build -o web-server ./cmd/main.go
+#
+# To build the web-server app
+
+COPY web-server /
+
+EXPOSE 62086
+
+CMD [ "/web-server" ]

examples/otel/README.md

@@ -0,0 +1,13 @@
+# OpenTelemetry example
+
+This is simply an OpenTelemetry version of the [web](../web) example so most of
+the README there also applies here.
+
+The only difference is that the metrics implementation used is OpenTelemetry
+with a Prometheus exporter instead of using a Prometheus only client crate.
+
+You can notice the 3 differences that are mentionned in the top-level README:
+- The amImpl import has been changed to `otel`
+- The autometrics call in the Go generator has the `-otel` flag
+- The `amImpl.Init` call uses a different first argument, with the name of the
+  OpenTelemetry scope to use

examples/otel/alertmanager.yml

@@ -0,0 +1,17 @@
+global:
+  # Also possible to use the URL directly
+  # Ex: `slack_api_url: 'https://slack.com/...'`
+  slack_api_url_file: '/etc/alertmanager/slack_url'
+
+route:
+  receiver: 'slack-notifications'
+  group_by: [sloth_service, sloth_slo, objective_name]
+
+receivers:
+- name: 'slack-notifications'
+  slack_configs:
+  # Channel is ignored when using a webhook. The webhook URL encodes the
+  # channel the alerts will be posted to.
+  - channel: '#alerts'
+    title: "{{ range .Alerts }}{{ .Annotations.summary }}\n{{ end }}"
+    text: "{{ range .Alerts }}{{ .Annotations.description }}\n{{ end }}"