prometheus/client_golang para Go: guia completo

1. O que é e para que serve

A biblioteca prometheus/client_golang é o cliente oficial para o sistema de monitoramento Prometheus, escrito em Go. Ela oferece aos desenvolvedores um conjunto de ferramentas poderoso e flexível para coletar, agregar e exportar métricas de aplicações Go. O Prometheus, por sua vez, é um dos sistemas de coleta de métricas e monitoramento mais populares no mundo DevOps e em tecnologias em nuvem, especialmente no ecossistema Kubernetes.

Para que serve? Na arquitetura moderna de microsserviços, é essencial entender como sua aplicação está se comportando: quantas requisições ela processa, qual a latência das respostas, quanta memória está consumindo, com que frequência ocorrem erros. O prometheus/client_golang permite instrumentar seu código facilmente, adicionando essas métricas. A biblioteca fornece automaticamente um endpoint (geralmente /metrics) que o Prometheus pode "scrape" (coletar) em intervalos regulares. Isso permite criar dashboards no Grafana, configurar alertas e ter uma visão completa da saúde do seu serviço.

Os principais recursos da biblioteca incluem suporte aos quatro tipos básicos de métricas do Prometheus: Counter (contador que só aumenta), Gauge (medidor que pode aumentar ou diminuir), Histogram (histograma para medir distribuições de valores, como tempo de resposta) e Summary (semelhante ao histograma, mas calcula quantis no lado do cliente). Além disso, a biblioteca oferece "coletores" convenientes para métricas padrão do Go (memória, goroutines, GC) e do servidor HTTP.

2. Instalação

A instalação da biblioteca é feita com o comando padrão go get. Certifique-se de ter o Go versão 1.16 ou superior instalado (recomenda-se a versão estável mais recente).

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

Após executar esses comandos, a dependência será adicionada ao seu go.mod. O pacote prometheus contém o núcleo da biblioteca (tipos de métricas, registro), enquanto o promhttp fornece o manipulador HTTP para exportar as métricas.

3. Início rápido — exemplo mínimo funcional

Vamos criar uma aplicação mínima que exporta uma métrica — o número de requisições HTTP processadas.

package main

import (
    "fmt"
    "net/http"

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

var (
    // Define um contador de requisições com o rótulo "path"
    requestsTotal = prometheus.NewCounterVec(
        prometheus.CounterOpts{
            Name: "http_requests_total",
            Help: "Número total de requisições HTTP.",
        },
        []string{"path"},
    )
)

func init() {
    // Registra a métrica no registro global
    prometheus.MustRegister(requestsTotal)
}

func main() {
    // Manipulador para a rota principal
    http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
        // Incrementa o contador para o caminho "/"
        requestsTotal.WithLabelValues("/").Inc()
        fmt.Fprintf(w, "Olá, Mundo!")
    })

    // Manipulador para o endpoint de métricas do Prometheus
    http.Handle("/metrics", promhttp.Handler())

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

Execute este código (go run main.go), abra no navegador http://localhost:8080/metrics. Você verá várias métricas, incluindo nossa http_requests_total. Cada vez que você acessar http://localhost:8080/, o valor do contador aumentará.