Instrumenting Golang server in 5 min

Image for post
Image for post

Getting started with Prometheus and Docker and you have no idea where to begin ? I can assure you it is relatively easy. This tutorial is for absolute Docker and Prometheus beginners. However, to keep the tutorial short and precise, the following is assumed knowledge:

  • Good feel and understanding of and the different types of metrics available i.e. Histogram , Gauge, Counter and Summary.
  • Basic understanding of Docker (We will not touch on orchestration or anything of that sort. However, if you’d like to monitor a Docker Stack kindly refer to Monitoring Docker Stack).
  • Basic understanding of HTTP metrics and their usage. We will be collecting metrics such as latencies , Bad Requests count and OK Requests count.

Prometheus and docker in a nutshell

There are numerous articles that cover the basics of Docker, with A beginner-Friendly Introduction to Containers, VMs and Docker being a winner for me.

On the other hand, Prometheus is a mere tool used to monitor usage and performance of an app. Yes it has various other uses but for purposes of this tutorial, usage and performance will be the main focus.

To monitor your app, you can either use Exporters or Instrumentation method. I have chosen Instrumentation for this tutorial. Mainly because it allows me to monitor everything, including customs metrics.


  • Ensure Docker is installed and running
  • Ensure Golang is installed. Run the command go version to test.

Dummy Golang hello app

For purposes of this tutorial, I have chosen to use Golang but you can also achieve the same thing with C#. Just grab a Prometheus client library here.

Below is a simple Golang app and all it does is to say “hello” to you.

Run the app on the terminal and hit the endpoint from the browser as shown below:

Image for post
Image for post

Prometheus support

Next step will be to go get the Prometheus Golang client library. Execute the following on the terminal:

go get

Prometheus Histrogram is suitable for collecting metrics such as HTTP latencies, number of requests and total number of errors. I have added Prometheus support on the code above, now there’s a new endpoint /metrics to expose all metrics collected from our server. This endpoint is required by Prometheus for metrics scrapping. Pay attention to how I have created a Histogram and how I have registered it with Prometheus.

Hit the endpoint /metrics from the browser you should be able to get our Histogram:

Image for post
Image for post

Docker support

The next step will be to move the app into a container. To do so, you will need a Dockerfile to define your container image. It is recommended to make use of Docker multistage building mainly because the Golang images are slightly bigger so you use them for building the App then move the compiled binaries to an Alpine image for execution.

Go ahead and write a Dockerfile and place it in your project directory as indicated below:

Run the following command to build the image. Ensure you’re in the project directory

docker build -t greeter .

Integration #TheFinalStep

How does it all come together? We can achieve all of this nicely with a compose file by deploying a stack with both containers but for the purposes of this tutorial I will deploy these individually. The plan is to run Prometheus in a container and map a config file(promtheus.yml) into the container.

Deploying the sample go server built above

You can kick off a container for your app by just executing the following command.

docker run --name greetpeople -d -p 8009:8009 greeter:latest

Get the container IP by running this command

docker inspect greetpeople

Scroll down to the Networks section, grab the “IP Address” listed. This will be used in the next section.

Deploying prometheus to monitor our server

We will start off by pulling an image from Docker hub.

docker pull prom/prometheus

Create another directory in the project parent directory, named Prometheus. After you will create a Prometheus config file within the Prometheus directory and name it Prometheus.yml. This will define all jobs you need Prometheus to monitor. As you can see in the config file below there are two jobs:

  • Prometheus
  • GreetPeople service deployed in the container above

Now replace the IP on the targets section of the GreetPeople service with the one you retrieved above.

Now save the file and execute the following command to kick off the Prometheus container:

docker run --name prometheus -d -p 9090:9090 -v /opt/docker/prometheus:/etc/prometheus prom/prometheus:latest

The -v flag maps my Prometheus folder (containing the prometheus.yml file) to a directory in the container where Prometheus will be expecting the config file. Reason behind this mapping of the config file is to eliminate the need to restart the container whenever changes are made to the config file.

From here you can hit the url http://localhost:9090 on your browser to see Prometheus. You can then search for the following metrics on the big search box (as shown below):

  • How long does it take to say Hello? for this we can take the average execution over the last 10 min
rate(greeting_seconds_sum[10m]) / rate(greeting_seconds_count[10m])
  • How many OK Requests do we get
greeting_seconds_count{code="200"}  // total request 
rate(greeting_seconds_count{code="200"}[1m]) //increase rate in the last min
  • How many Bad Requests did we get
greeting_seconds_count{code="400"}  // total request 
rate(greeting_seconds_count{code="400"}[1m]) //increase rate in the last min
Image for post
Image for post


This was just to show you how you can achieve this in the most simplest way. A recommended way would be to use docker-compose to kick off the containers in a Stack and maybe Grafana for the UI.

I hope you find the guidelines helpful. As a first time blogger, your feedback would be highly appreciated

Written by

Software Engineer

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store