Getting started in Go

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


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:

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:

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


Import the library in your code

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

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

And then in your main function initialize the metrics:


Add go:generate autometrics to your code


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

# 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}'


The manual changes you need to do are:

//go:generate autometrics
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:

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):

import (
	autometrics "github.com/autometrics-dev/autometrics-go/otel/autometrics"
func main() {
	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.

brew install autometrics-dev/tap/am