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:

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(orthedefaultGOBIN (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"
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(
		nil,
		autometrics.DefBuckets,
		autometrics.BuildInfo{},
                nil,
	)

Add go:generate autometrics to your code

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

Install the go generator using go install as usual:

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

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:

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(
		"web-server",
		autometrics.DefBuckets,
		autometrics.BuildInfo{},
                nil,
	)
	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>

Configure your Prometheus

Make sure your Prometheus is configured correctly to find the metrics.

See the Configuring Prometheus section for deploy target-specific instructions.

Example configuration:

prometheus.yml
scrape_configs:
  - job_name: my-app
    metrics_path: /metrics
    static_configs:
      # Replace the port with the port your app listens on
      - targets: ['<host>:<port>']
    # For a real deployment, you would want the scrape interval to be
    # longer but for testing, you want the data to show up quickly
    scrape_interval: 200ms
Setting up SLOs in FastifyAdding version information