Integrating Prometheus Client with Go Applications for Custom Metrics

Today we're going to be exploring the process of integrating the Prometheus client with a GoLang application. For the uninitiated, Prometheus is a powerful open-source system monitoring and alerting toolkit which can help you keep tabs on your systems, even in a complex, highly distributed context. Read more on What is Prometheus below.

This tutorial is designed to guide you step-by-step to emit custom metrics from your GoLang application using the Prometheus client. Let's get started.

Read more on Prometheus Metrics Types.

Pre-requisites

1. Basic knowledge of GoLang

2. Familiarity with Docker

3. Go environment set up on your system

4. Docker installed on your system

Step 1: Installing the Prometheus Go client library

To start, let's install the Prometheus client_golang library which provides all the necessary APIs to instrument our application. You can fetch it by running the following command:

go get github.com/prometheus/client_golang/prometheus
go get github.com/prometheus/client_golang/prometheus/promhttp

Step 2: Implementing Prometheus Metrics

Let's start by creating a new Go file. In this file, we're going to implement the main Prometheus metric types: Counter, Gauge, Histogram, and Summary. Here's an example of how you can create and register these metrics.

package main

import (
    "github.com/prometheus/client_golang/prometheus"
    "github.com/prometheus/client_golang/prometheus/promhttp"
    "net/http"
)

var (
    httpRequestsTotal = prometheus.NewCounterVec(
        prometheus.CounterOpts{
            Name: "http_requests_total",
            Help: "Number of HTTP requests",
        },
        []string{"path"},
    )

    httpRequestDuration = prometheus.NewHistogramVec(
        prometheus.HistogramOpts{
            Name:    "http_request_duration_seconds",
            Help:    "Duration of HTTP requests",
            Buckets: prometheus.DefBuckets,
        },
        []string{"path"},
    )
)

func init() {
    // Metrics have to be registered to be exposed:
    prometheus.MustRegister(httpRequestsTotal)
    prometheus.MustRegister(httpRequestDuration)
}

In this snippet, we're defining a counter http_requests_total that will track the total number of HTTP requests our application receives, and a histogram http_request_duration_seconds to track the duration of these requests. Both metrics are labeled by the request path.

Step 3: Instrumenting your application

Once you've defined your metrics, the next step is to instrument your application. This means integrating the metrics into your application code so that they are updated as your application runs. For example, let's add a handler for the /hello path that increments the counter and records the request duration:

func main() {
    http.Handle("/metrics", promhttp.Handler())
    http.HandleFunc("/hello", func(w http.ResponseWriter, r *http.Request) {
        timer := prometheus.NewTimer(httpRequestDuration.WithLabelValues("/hello"))
        defer timer.ObserveDuration()
        httpRequestsTotal.WithLabelValues("/hello").Inc()

        w.Write([]byte("Hello, World!"))
    })
    http.ListenAndServe(":8080", nil)
}

This server will now track the total number of requests and their duration for the /hello path, and expose these metrics at the /metrics path.

Step 4: Running Prometheus

To monitor these metrics, we'll need to run a Prometheus server. For simplicity, we can run it in a Docker container. First, create a prometheus.yml configuration file:

global:
  scrape_interval:     15s 


  evaluation_interval: 15s 

scrape_configs:
  - job_name: 'golang_app'
    static_configs:
    - targets: ['host.docker.internal:8080']

This configuration tells Prometheus to scrape metrics from your application every 15 seconds. Now, you can start the Prometheus server with Docker:

docker run -d -p 9090:9090 -v /path/to/prometheus.yml:/etc/prometheus/prometheus.yml prom/prometheus

Step 5: Visualizing Metrics

Open your browser and navigate to http://localhost:9090/graph. You can enter your metric name (e.g., http_requests_total) in the "Expression" input, then click "Execute" to view your metrics.

And there you have it! You have successfully integrated the Prometheus client into your Go application and are now collecting custom metrics. Remember, this is just a basic introduction. Prometheus and Go offer many more powerful features that you can explore as your application's monitoring needs grow.