Run Prometheus locally and validate your metrics with the Autometrics CLI and Explorer 📈
Go
Quickstart

Getting started in Go

Here's how to get started with Go in a new project.

Pre-requisites

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 generator

The generator is the binary in cmd/autometrics, so the easiest way to get it is to install it through Go:

Shell
go install github.com/autometrics-dev/autometrics-go/cmd/autometrics@latest

Add the generator to your PATH

In order to have autometrics visible then, make sure that the directory $GOBIN (or the default $GOPATH/bin) is in your $PATH:

Shell
echo "$PATH" | grep -q "${GOBIN:-$GOPATH/bin}" && echo "GOBIN in PATH" || echo "GOBIN not in PATH, please add it"
GOBIN in PATH

Instructions

Import the library in your code

In the main entrypoint of your program, add the package:

main.go
import (
	autometrics "github.com/autometrics-dev/autometrics-go/prometheus/autometrics"
)

And then in your main function initialize the metrics:

main.go
	autometrics.Init()

Add go:generate autometrics to your code

Automatically

You can use the am binary and its instrument subcommand to automatically instrument your whole codebase. You can also use a grep invocation:

Shell
# On Linux, use sed, not gsed
find . \
  -type d -name vendor -prune -or \
  -type f -name '*.go' \
  -print0 | xargs -0 gsed -i -e '/package/{a\//go:generate autometrics --inst-all --no-doc' -e ':a;n;ba}'

Manually

The manual changes you need to do are:

main.go
//go:generate autometrics
 
//autometrics:doc
func RouteHandler(args interface{}) (err error) { // Name the error return value; this is an optional but recommended change
        // ...
        return nil
}
💡

If you want the generated metrics to contain the function success rate, you must name the error return value. This is why we recommend to name the error value you return for the function you want to instrument.

Generate the documentation and instrumentation code

As you have installed the generator as part of the prerequisites, it will take care of the rest, and you can simply call go generate with an optional environment variable:

Shell
AM_PROMETHEUS_URL=http://localhost:9090/ go generate ./...

The generator will augment your doc comment to add quick links to metrics (using the Prometheus URL as base URL), and add a unique defer statement that will take care of instrumenting your code.

The environment variable AM_PROMETHEUS_URL controls the base URL of the instance that is scraping the deployed version of your code. Having an environment variable means you can change the generated links without touching your code. Default value: http://localhost:9090/.

💡

If you do not want to have lengthy documentation generated on top of the function, you can use //autometrics:inst annotation instead of //autometrics:doc.

Make metrics available to Prometheus

The last step now is to actually expose the generated metrics to the Prometheus instance.

For Prometheus the shortest way is to add the handler code in your main entrypoint (this example also shows the Init call when choosing to use OpenTelemetry to handle metrics):

main.go
import (
	autometrics "github.com/autometrics-dev/autometrics-go/otel/autometrics"
	"github.com/prometheus/client_golang/prometheus/promhttp"
)
 
func main() {
	autometrics.Init(
		autometrics.WithService("web-server"),
		autometrics.WithMeterName("web-server"),
		autometrics.WithCommit("anySHA"),
		autometrics.WithVersion("2.1.37"),
	)
	http.Handle("/metrics", promhttp.Handler())
}

This is the shortest way to initialize and expose the metrics that autometrics will use in the generated code.

You're set! You can now start your app and preview the metrics.

Viewing the metrics

Using Autometrics Explorer

Autometrics Explorer is an open source accompanying utility to preview and validate your metrics locally. It will automatically run Prometheus under the hood for you and show you Autometrics-instrumented functions in a web UI.

See Local Development for more information.

shell
brew install autometrics-dev/tap/am
 
am start <YOUR_APP_METRICS_ENDPOINT>
Setting up SLOs in FastifyAdding version information