web

Web application instrumented in seconds

This is an example application to show how fast you can setup autometrics.

It shows the generator usage and sets up Prometheus to showcase the "automatically generated links" feature.

Quick start

# Go to the root of the repo
cd ../..
# Build all the images
docker compose -f docker-compose.prometheus-example.yaml build
# Run all the services
docker compose -f docker-compose.prometheus-example.yaml up

Then open main in your editor and interact with the documentation links!

Alert generation

Optionnally, create a slack integration with an "incoming webhook" for one of your channels, and put the URL of the webhook (a secret!) in slack_url.txt in the configs directory. That will enable alerting in Slack directly through Alertmanager.

You can see that the name of the service "API" comes directly from the annotation in the code.

You can even monitor all the alerts triggering through Prometheus or Alertmanager:

Dependencies

In order to run this example you need:

• Docker
• Docker Compose

Explanations

Setup

The basic code used is in main.go.orig for demonstration purposes. Note that the code has a autometrics.Init() method call that initialize the metrics, and adds a /metrics handler to serve prometheus metrics

We then just used go generate ./... to generate the documentation strings and the automatic metric collection calls (in defer statements)

You can obtain the same file by simply replacing the original one and calling go generate again to see what it does:

mv cmd/main.go{.orig,}
go generate ./...

Or you can play with the functions (rename them, change the name of the returned error value, or even remove the error return value entirely), and call go generate ./... again to see how the generator handles all code changes for you. The generator is idempotent.

Building the docker image

Build the web-server in an image. There are 2 important things in the image recipe:

• The context of the image is the root of the repository, only so that this example runs the development version of the code, and
• There is a specific build script that uses Go linker flags to inject build and version information in the binary.

docker build --build-arg VERSION=1.0.0 -t web-server .

Start the services

In one terminal you can launch the image and the small helper script to poll the the server:

cd ../..
docker compose -f docker-compose.prometheus-example.yaml up

Check the links on Prometheus

The metrics won't appear immediately, due to Prometheus needing to poll them first, but after approximatively 10s, you will see that the autometrics metrics get automatically filled by the code. You just needed 2 lines of code (the Init call, and the /metrics prometheus handler) and 1 comment per function to instrument everything.

Watch alerts trigger

The random function called by the poll_server helper will eventually fall below alert threshold, you can monitor prometheus catching on that and triggering the alert on the Alerts page of your instance:

In the "real" world setting, these alerts would be automatically routed with an Alertmanager configuration to the correct notification service:

This demo example has a minimal configuration for alerts that expects a file slack_url.txt to be passed in docker-compose context. Create the file in the configs folder, and if the file exists, the triggered alerts automatically go on Slack to the configured channel:

Original input

The "original" input file for the webserver (before the call to go generate ./...) can be found here