prometheus/client_golang para Go: guía completa

1. ¿Qué es y para qué sirve?

La biblioteca prometheus/client_golang es el cliente oficial para el sistema de monitoreo Prometheus, escrito en el lenguaje Go. Proporciona a los desarrolladores un conjunto de herramientas potente y flexible para recolectar, agregar y exportar métricas desde aplicaciones Go. Prometheus, a su vez, es uno de los sistemas de recolección de métricas y monitoreo más populares en el mundo DevOps y la nube, especialmente en el ecosistema Kubernetes.

¿Para qué sirve? En la arquitectura moderna de microservicios es fundamental entender cómo funciona tu aplicación: cuántas solicitudes procesa, cuál es la latencia de respuesta, cuánta memoria consume, con qué frecuencia ocurren errores. prometheus/client_golang te permite instrumentar tu código fácilmente, añadiendo estas métricas. La biblioteca proporciona automáticamente un endpoint (generalmente /metrics) que Prometheus puede "scrape" (consultar) periódicamente. Esto te permite crear dashboards en Grafana, configurar alertas y obtener una visión completa del estado de tu servicio.

Las capacidades clave de la biblioteca incluyen soporte para los cuatro tipos principales de métricas de Prometheus: Counter (contador que solo aumenta), Gauge (medidor que puede aumentar y disminuir), Histogram (histograma para medir la distribución de valores, como tiempos de respuesta) y Summary (similar al histograma, pero calcula cuantiles del lado del cliente). Además, la biblioteca ofrece "collectors" convenientes para métricas estándar de Go (memoria, gorutinas, GC) y del servidor HTTP.

2. Instalación

La instalación de la biblioteca se realiza con el comando estándar go get. Asegúrate de tener instalado Go versión 1.16 o superior (se recomienda la última versión estable).

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

Después de ejecutar estos comandos, aparecerá la dependencia en tu archivo go.mod. El paquete prometheus contiene el núcleo de la biblioteca (tipos de métricas, registro), mientras que promhttp proporciona el manejador HTTP para exportar las métricas.

3. Inicio rápido — ejemplo mínimo funcional

Vamos a crear una aplicación mínima que exporte una métrica: la cantidad de solicitudes HTTP procesadas.

package main

import (
    "fmt"
    "net/http"

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

var (
    // Definimos un contador de solicitudes con la etiqueta "path"
    requestsTotal = prometheus.NewCounterVec(
        prometheus.CounterOpts{
            Name: "http_requests_total",
            Help: "Número total de solicitudes HTTP.",
        },
        []string{"path"},
    )
)

func init() {
    // Registramos la métrica en el registro global
    prometheus.MustRegister(requestsTotal)
}

func main() {
    // Manejador para la ruta principal
    http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
        // Incrementamos el contador para la ruta "/"
        requestsTotal.WithLabelValues("/").Inc()
        fmt.Fprintf(w, "¡Hola, Mundo!")
    })

    // Manejador para el endpoint de métricas de Prometheus
    http.Handle("/metrics", promhttp.Handler())

    fmt.Println("Servidor iniciado en :8080")
    http.ListenAndServe(":8080", nil)
}

Ejecuta este código (go run main.go), abre en tu navegador http://localhost:8080/metrics. Verás muchas métricas, incluyendo nuestra http_requests_total. Cada vez que visites http://localhost:8080/, el valor del contador aumentará.

4. Métodos/funciones/clases principales

4.1. prometheus.NewCounter / prometheus.NewCounterVec