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 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:
import (
autometrics "github.com/autometrics-dev/autometrics-go/prometheus/autometrics"
)
And then in your main function initialize the metrics:
autometrics.Init(
nil,
autometrics.DefBuckets,
autometrics.BuildInfo{},
nil,
)
Add go:generate autometrics
to your code
The manual changes you need to do are:
//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:
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:
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"
"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.
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:
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