prometheus/client_golang for Go: Complete Guide

1. What It Is and Why You Need It

The prometheus/client_golang library is the official Go client for the Prometheus monitoring system. It provides developers with a powerful and flexible toolkit for collecting, aggregating, and exporting metrics from Go applications. Prometheus is one of the most popular metrics collection and monitoring systems in the DevOps and cloud-native world, especially within the Kubernetes ecosystem.

Why do you need it? In modern microservice architectures, it's critical to understand how your application is performing: how many requests it handles, what the response latency is, how much memory it consumes, and how often errors occur. prometheus/client_golang makes it easy to instrument your code by adding these metrics. The library automatically provides an endpoint (typically /metrics) that Prometheus can scrape on a schedule. This allows you to build dashboards in Grafana, set up alerts, and get a complete picture of your service's health.

Key features of the library include support for Prometheus's four core metric types: Counter (a monotonically increasing counter), Gauge (a value that can go up or down), Histogram (for measuring value distributions, e.g., response times), and Summary (similar to a histogram but calculates quantiles on the client side). Additionally, the library provides convenient collectors for standard Go metrics (memory, goroutines, GC) and HTTP server metrics.

2. Installation

Install the library using the standard go get command. Make sure you have Go version 1.16 or higher installed (the latest stable version is recommended).

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

After running these commands, the dependency will appear in your go.mod file. The prometheus package contains the core of the library (metric types, registration), while promhttp provides the HTTP handler for exporting metrics.

3. Quick Start — Minimal Working Example

Let's create a minimal application that exports one metric — the number of processed HTTP requests.

package main

import (
    "fmt"
    "net/http"

    "github.com/prometheus/client_golang/prometheus"
    "github.com/prometheus/client_golang/prometheus/promhttp"
)

var (
    // Define a request counter with a "path" label
    requestsTotal = prometheus.NewCounterVec(
        prometheus.CounterOpts{
            Name: "http_requests_total",
            Help: "Total number of HTTP requests.",
        },
        []string{"path"},
    )
)

func init() {
    // Register the metric in the global registry
    prometheus.MustRegister(requestsTotal)
}

func main() {
    // Handler for the root path
    http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
        // Increment the counter for the "/" path
        requestsTotal.WithLabelValues("/").Inc()
        fmt.Fprintf(w, "Hello, World!")
    })

    // Handler for the Prometheus metrics endpoint
    http.Handle("/metrics", promhttp.Handler())

    fmt.Println("Server started on :8080")
    http.ListenAndServe(":8080", nil)
}

Run this code (go run main.go), then open http://localhost:8080/metrics in your browser. You'll see many metrics, including our http_requests_total. Each time you visit http://localhost:8080/, the counter value will increase.

4. Key Methods/Functions/Classes

4.1. prometheus.NewCounter / prometheus.NewCounterVec