Add build information to the metrics/queries

.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).
 
 ## How to use
 
@@ -50,7 +59,18 @@ import (
 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.
+	amImpl.Init(
+		nil,
+		amImpl.DefBuckets,
+		amImpl.BuildInfo{
+			Version: "0.4.0",
+			Commit: "anySHA",
+			BuildTime: "",
+		},
+	)
 ```
 
 > **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
@@ -134,7 +154,15 @@ import (
 
 
 func main() {
-	amImpl.Init(nil, am.DefBuckets)
+	amImpl.Init(
+		nil,
+		amImpl.DefBuckets,
+		amImpl.BuildInfo{
+			Version: "0.4.0",
+			Commit: "anySHA",
+			BuildTime: "",
+		},
+	)
 	http.Handle("/metrics", promhttp.Handler())
 }
 ```
@@ -188,15 +216,23 @@ the `Init` function takes a meter name for the `otel_scope` label of the exporte
 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)
+	amImpl.Init(
+-		nil,
++		"myApp/v2/prod",
+		amImpl.DefBuckets,
+		amImpl.BuildInfo{
+			Version: "2.1.37",
+			Commit: "anySHA",
+			BuildTime: "",
+		},
+	)
 ```
 
-- 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

cmd/autometrics/main.go

@@ -1,51 +1,77 @@
 package main
 
 import (
+	"fmt"
 	"log"
-	"os"
+	"strings"
 
 	internal "github.com/autometrics-dev/autometrics-go/internal/autometrics"
+	"github.com/autometrics-dev/autometrics-go/internal/build"
 	"github.com/autometrics-dev/autometrics-go/internal/generate"
 	"github.com/autometrics-dev/autometrics-go/pkg/autometrics"
+
+	arg "github.com/alexflint/go-arg"
 )
 
 const (
-	prometheusAddressEnvironmentVariable = "AM_PROMETHEUS_URL"
-	useOtelFlag                          = "-otel"
-	allowCustomLatencies                 = "-custom-latency"
-	DefaultPrometheusInstanceUrl         = "http://localhost:9090/"
+	DefaultPrometheusInstanceUrl = "http://localhost:9090/"
 )
 
-func main() {
-	fileName := os.Getenv("GOFILE")
-	moduleName := os.Getenv("GOPACKAGE")
-	args := os.Args
+type args struct {
+	FileName             string `arg:"-f,--,required,env:GOFILE" placeholder:"FILE_NAME" help:"File to transform."`
+	ModuleName           string `arg:"-m,--,required,env:GOPACKAGE" placeholder:"MODULE_NAME" help:"Module containing the file to transform."`
+	PrometheusUrl        string `arg:"--prom_url,env:AM_PROMETHEUS_URL" placeholder:"PROMETHEUS_URL" default:"http://localhost:9090" help:"Base URL of the Prometheus instance to generate links to."`
+	UseOtel              bool   `arg:"--otel" default:"false" help:"Use OpenTelemetry client library to instrument code instead of default Prometheus."`
+	AllowCustomLatencies bool   `arg:"--custom-latency" default:"false" help:"Allow non-default latencies to be used in latency-based SLOs."`
+}
 
-	prometheusUrl, envVarExists := os.LookupEnv(prometheusAddressEnvironmentVariable)
-	if !envVarExists {
-		prometheusUrl = DefaultPrometheusInstanceUrl
+func (args) Version() string {
+	var buf strings.Builder
+
+	fmt.Fprintf(&buf, "Autometrics %s", build.Version)
+	if build.Time != "" {
+		fmt.Fprintf(&buf, " (Built on %s)", build.Time)
 	}
 
+	return buf.String()
+}
+
+func (args) Description() string {
+	var buf strings.Builder
+
+	fmt.Fprintf(&buf,
+		"Autometrics instruments annotated functions, and adds links in their doc comments to graphs of their live usage.\n\n")
+
+	fmt.Fprintf(&buf,
+		"It is meant to be used in a Go generator context. As such, it takes mandatory arguments in the form of environment variables.\n"+
+			"You can also control the base URL of the prometheus instance in doc comments with an environment variable.\n")
+	fmt.Fprintf(&buf,
+		"\tNote: If you do not use the custom latencies in the SLO, the allowed latencies (in seconds) are %v\n\n",
+		autometrics.DefBuckets)
+
+	fmt.Fprintln(&buf,
+		"Check https://github.com/autometrics-dev/autometrics-go for more help (including examples) and information.")
+	fmt.Fprintf(&buf,
+		"Autometrics is built by Fiberplane -- https://autometrics.dev\n")
+
+	return buf.String()
+}
+
+func main() {
+	var args args
+	arg.MustParse(&args)
+
 	implementation := autometrics.PROMETHEUS
-	if contains(args, useOtelFlag) {
+	if args.UseOtel {
 		implementation = autometrics.OTEL
 	}
 
-	ctx, err := internal.NewGeneratorContext(implementation, prometheusUrl, contains(args, allowCustomLatencies))
+	ctx, err := internal.NewGeneratorContext(implementation, args.PrometheusUrl, args.AllowCustomLatencies)
 	if err != nil {
 		log.Fatalf("error initialising autometrics context: %s", err)
 	}
 
-	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
-		}
+	if err := generate.TransformFile(ctx, args.FileName, args.ModuleName); err != nil {
+		log.Fatalf("error transforming %s: %s", args.FileName, err)
 	}
-	return false
 }