Add build information to the metrics/queries (#34)

* Add build information to the metrics/queries

This allows use cases where we can see and query the changes in metrics
after a version change in the code base.

Ref: autometrics-dev/autometrics-rs#69
Ref: https://github.com/orgs/autometrics-dev/discussions/10

* Add --help and --version flags to the binary

Closes: #36

* !Breaking: Use go-arg to parse generator arguments

Breaking change: the long flags in autometrics now take the long form
arguments starting with --

Also removes the unused `am-alertsgen` binary. Even though for the time
being we are using sloth to generate the alerts, at some point we might
want to change, and adding extra code/friction to do the change seems
unwarranted for now.

.github/workflows/release.yml

@@ -30,14 +30,17 @@ jobs:
             ext: ''
     steps:
       - uses: actions/checkout@v3
+        with:
+          # We need all tags
+          fetch-depth: 0
       - name: Set up Go
         uses: actions/setup-go@v4
         with:
           go-version: "1.20"
           check-latest: true
       - name: Build
         run: |
-          GOOS=${{ matrix.goos }} GOARCH=${{ matrix.goarch }} go build cmd/autometrics/main.go
+          GOOS=${{ matrix.goos }} GOARCH=${{ matrix.goarch }} ./scripts/build_generator
           mv main${{ matrix.ext }} autometrics${{ matrix.ext }}
 
       - name: Pack (Zip)

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "autometrics-shared"]
+	path = configs/shared
+	url = https://github.com/autometrics-dev/autometrics-shared.git

README.md

@@ -13,7 +13,16 @@ trigger alerts directly from production usage:
 ![a Slack bot is posting an alert directly in the channel](./assets/slack-alert-example.png)
 
 A fully working use-case and example of library usage is available in the
-[examples/web](./examples/web) subdirectory
+[examples/web](./examples/web) subdirectory. You can build and run load on the
+example server using:
+
+```console
+git submodule update --init
+docker compose -f docker-compose.prometheus-example.yaml up
+```
+
+And then explore the generated links by opening the [main
+file](./examples/web/cmd/main.go) in your editor.
 
 ## How to use
 
@@ -43,14 +52,25 @@ In the main entrypoint of your program, you need to both add package
 
 ``` go
 import (
-	amImpl "github.com/autometrics-dev/autometrics-go/pkg/autometrics/prometheus"
+	autometrics "github.com/autometrics-dev/autometrics-go/pkg/autometrics/prometheus"
 )
 ```
 
 And then in your main function initialize the metrics
 
 ``` go
-amImpl.Init(nil, am.DefBuckets)
+	// Everything in BuildInfo is optional.
+	// You can also use any string variable whose value is
+	// injected at build time by ldflags.
+	autometrics.Init(
+		nil,
+		autometrics.DefBuckets,
+		autometrics.BuildInfo{
+			Version: "0.4.0",
+			Commit: "anySHA",
+			Branch: "",
+		},
+	)
 ```
 
 > **Warning**
@@ -59,11 +79,11 @@ 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 your use case, you can change the buckets in
-the init call, and add a `-custom-latency` argument to the `//go:generate` invocation.
+the init call, and add a `--custom-latency` argument to the `//go:generate` invocation.
 
 ```patch
 -//go:generate autometrics
-+//go:generate autometrics -custom-latency
++//go:generate autometrics --custom-latency
 ```
 
 ### Add cookies in your code
@@ -128,13 +148,21 @@ For Prometheus the shortest way is to add the handler code in your main entrypoi
 
 ``` go
 import (
-	amImpl "github.com/autometrics-dev/autometrics-go/pkg/autometrics/prometheus"
+	autometrics "github.com/autometrics-dev/autometrics-go/pkg/autometrics/prometheus"
 	"github.com/prometheus/client_golang/prometheus/promhttp"
 )
 
 
 func main() {
-	amImpl.Init(nil, am.DefBuckets)
+	autometrics.Init(
+		nil,
+		autometrics.DefBuckets,
+		autometrics.BuildInfo{
+			Version: "0.4.0",
+			Commit: "anySHA",
+			Branch: "",
+		},
+	)
 	http.Handle("/metrics", promhttp.Handler())
 }
 ```
@@ -154,11 +182,11 @@ func RouteHandler(args interface{}) (err error) {
 }
 ```
 
-Then **you need to add** the [bundled](./configs/autometrics.rules.yml)
+Then **you need to add** the [bundled](./configs/shared/autometrics.rules.yml)
 recording rules to your prometheus configuration.
 
 The valid arguments for alert generation are:
-- `--slo` (*MANDATORY*): name of the service for which the objective is relevant
+- `--slo` (*MANDATORY* for alert generation): name of the service for which the objective is relevant
 - `--success-rate` : target success rate of the function, between 0 and 100 (you
   must name the `error` return value of the function for detection to work.)
 - `--latency-ms` : maximum latency allowed for the function, in milliseconds.
@@ -168,35 +196,43 @@ The valid arguments for alert generation are:
 
 > **Warning**
 > The generator will error out if you use targets that are not
-supported by the bundled [Alerting rules file](./configs/autometrics.rules.yml).
+supported by the bundled [Alerting rules file](./configs/shared/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
+- change where the `autometrics` import points to
 ```patch
 import (
--	amImpl "github.com/autometrics-dev/autometrics-go/pkg/autometrics/prometheus"
-+	amImpl "github.com/autometrics-dev/autometrics-go/pkg/autometrics/otel"
+-	autometrics "github.com/autometrics-dev/autometrics-go/pkg/autometrics/prometheus"
++	autometrics "github.com/autometrics-dev/autometrics-go/pkg/autometrics/otel"
 )
 ```
-- change the call to `amImpl.Init` to the new signature: instead of a registry,
+- change the call to `autometrics.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
--	amImpl.Init(nil, am.DefBuckets)
-+	amImpl.Init("myApp/v2/prod", am.DefBuckets)
+	autometrics.Init(
+-		nil,
++		"myApp/v2/prod",
+		autometrics.DefBuckets,
+		autometrics.BuildInfo{
+			Version: "2.1.37",
+			Commit: "anySHA",
+			Branch: "",
+		},
+	)
 ```
 
-- add the `-otel` flag to the `//go:generate` directive
+- add the `--otel` flag to the `//go:generate` directive
 
 ```patch
 -//go:generate autometrics
-+//go:generate autometrics -otel
++//go:generate autometrics --otel
 ```
 
 ## (OPTIONAL) Git hook
@@ -228,4 +264,4 @@ 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.
+file](./configs/shared/autometrics.rules.yml) with custom objectives.

cmd/autometrics/doc.go

@@ -1,22 +1,36 @@
-// 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.
+// Autometrics instruments annotated functions, and adds links in their doc comments to graphs of their live usage.
 //
 // 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
+// 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.
+// your latency SLOs, pass the `--custom-latency` flag to the invocation.
+//
+// It is meant to be used in a Go generator context. As such, it takes mandatory arguments in the form of environment variables.
+// You can also control the base URL of the prometheus instance in doc comments with an environment variable.
+//         Note: If you do not use the custom latencies in the SLO, the allowed latencies (in seconds) are in [autometrics.DefBuckets].
+//
+// Check https://github.com/autometrics-dev/autometrics-go for more help (including examples) and information.
+// Autometrics is built by Fiberplane -- https://autometrics.dev
+//
+// Usage: autometrics -f FILE_NAME -m MODULE_NAME [--prom_url PROMETHEUS_URL] [--otel] [--custom-latency]
 //
-// 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.
+// Options:
+//   -f FILE_NAME           File to transform. [env: GOFILE]
+//   -m MODULE_NAME         Module containing the file to transform. [env: GOPACKAGE]
+//   --prom_url PROMETHEUS_URL
+//                          Base URL of the Prometheus instance to generate links to. [default: http://localhost:9090, env: AM_PROMETHEUS_URL]
+//   --otel                 Use [OpenTelemetry client library] to instrument code instead of default [Prometheus client library]. [default: false]
+//   --custom-latency       Allow non-default latencies to be used in latency-based SLOs. [default: false]
+//   --help, -h             display this help and exit
+//   --version              display version and exit
 //
 // [Prometheus client library]: https://github.com/prometheus/client_golang
+// [OpenTelemetry client library]: https://github.com/open-telemetry/opentelemetry-go
 // [OpenTelemetry metrics]: https://opentelemetry.io/docs/instrumentation/go/
+// [autometrics.DefBuckets]: https://godoc.org/github.com/autometrics-dev/autometrics-go/pkg/autometrics#DefBuckets
 package main