Bibliotecas Cliente Prometheus & OpenTelemetry

Serviços Go em produção expõem métricas Prometheus para dashboards e traces OpenTelemetry para depuração de latência de requisições.

As bibliotecas cliente ficam na borda HTTP/gRPC e envolvem chamadas de saída sem substituir sua pilha de logging.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

import (
    "net/http"
    "github.com/prometheus/client_golang/prometheus/promhttp"
)
 
http.Handle("/metrics", promhttp.Handler())

import (
    "go.opentelemetry.io/otel"
    "go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp"
)
 
handler := otelhttp.NewHandler(mux, "api")

Quando usar isso:

• SREs precisam de métricas RED (rate, errors, duration) por rota e dependência
• Engenheiros de plantão rastreiam requisições lentas entre serviços
• Kubernetes coleta /metrics ou um coletor OTel recebe OTLP
• Você padroniza bibliotecas de observabilidade entre servidores chi, Gin e gRPC

Exemplo de Trabalho

package main
 
import (
    "context"
    "log"
    "net/http"
    "time"
 
    "github.com/go-chi/chi/v5"
    "github.com/go-chi/chi/v5/middleware"
    "github.com/prometheus/client_golang/prometheus"
    "github.com/prometheus/client_golang/prometheus/promauto"
    "github.com/prometheus/client_golang/prometheus/promhttp"
    "go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp"
    "go.opentelemetry.io/otel"
    sdktrace "go.opentelemetry.io/otel/sdk/trace"
    "go.opentelemetry.io/otel/trace"
)
 
var (
    httpDuration = promauto.NewHistogramVec(prometheus.HistogramOpts{
        Name:    "http_request_duration_seconds",
        Help:    "HTTP request latency",
        Buckets: prometheus.DefBuckets,
    }, []string{"method", "route", "status"})
)
 
func initTracer() trace.TracerProvider {
    tp := sdktrace.NewTracerProvider()
    otel.SetTracerProvider(tp)
    return tp
}
 
func metricsMiddleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        start := time.Now()
        ww := middleware.NewWrapResponseWriter(w, r.ProtoMajor)
        next.ServeHTTP(ww, r)
        route := chi.RouteContext(r.Context()).RoutePattern()
        httpDuration.WithLabelValues(r.Method, route, http.StatusText(ww.Status())).Observe(time.Since(start).Seconds())
    })
}
 
func main() {
    tp := initTracer()
    defer func() { _ = tp.Shutdown(context.Background()) }()
 
    r := chi.NewRouter()
    r.Use(metricsMiddleware)
    r.Get("/health", func(w http.ResponseWriter, r *http.Request) { w.WriteHeader(200) })
    r.Handle("/metrics", promhttp.Handler())
 
    root := otelhttp.NewHandler(r, "api")
    log.Fatal(http.ListenAndServe(":8080", root))
}

O que isso demonstra:

• Histograma Prometheus com labels de baixa cardinalidade (method, route, status)
• Padrões de rota chi para estabilidade de labels (evite URLs brutas com IDs)
• promhttp.Handler em um caminho dedicado para scrapers
• Middleware HTTP OTel envolvendo o router para propagação de trace

Mergulho Profundo

Como Funciona

• Cliente Prometheus registra coletores em um registro; promhttp expõe o formato de exposição de texto.
• SDK OpenTelemetry configura TracerProvider, exportadores (OTLP gRPC/HTTP) e atributos de recurso (service.name).
• otelhttp cria spans em torno de handlers e propaga headers traceparent.
• Métricas respondem "quanto e quão rápido"; traces respondem "qual salto foi lento".

Tipos de Métricas (Prometheus)

Esboço de Bootstrap OTel

exporter, _ := otlptracegrpc.New(ctx)
tp := sdktrace.NewTracerProvider(
    sdktrace.WithBatcher(exporter),
    sdktrace.WithResource(resource.NewWithAttributes(
        semconv.SchemaURL,
        semconv.ServiceName("orders-api"),
    )),
)
otel.SetTracerProvider(tp)

• Execute um coletor sidecar ou endpoint OTLP em todo o cluster no Kubernetes.
• Alinhe service.name com labels de implantação para busca de traces.

Notas Go

• Use promauto apenas quando um único registro for suficiente; bibliotecas devem aceitar parâmetros prometheus.Registerer.
• gRPC usa interceptadores go.opentelemetry.io/contrib/instrumentation/google.golang.org/grpc/otelgrpc de forma semelhante.
• Nunca coloque IDs de usuário ou segmentos de caminho ilimitados em labels de métricas.

Armadilhas

• Labels de alta cardinalidade - /users/123 por requisição explode as séries. Correção: use chi.RoutePattern() ou nomes de rota com template.
• Instrumentação dupla - métricas do framework mais middleware personalizado duplicam contagens. Correção: um proprietário por nome de métrica no ADR.
• Registro Prometheus global em bibliotecas - pacotes importados registram coletores inesperadamente. Correção: passe prometheus.Registerer para os construtores.
• Desligamento de tracer ausente - exportadores em lote descartam spans na saída. Correção: Shutdown em SIGTERM com tempo limite de esvaziamento gracioso.
• Coleta da porta principal da internet - /metrics vaza detalhes operacionais. Correção: listener separado ou política de rede na porta de administração.
• Amostragem de trace em 100% sempre - o custo explode em escala. Correção: amostragem baseada no pai ou probabilística ajustada por ambiente.

NzA2MjAyfDI5M29pZ2N8b2kuc2VkaXVnZWRvYw==

Alternativas

FAQs

Relacionados

• Métricas Prometheus e Dashboards de Uso RED - metodologia RED
• OpenTelemetry Tracing em Serviços Go - pipeline de trace
• Produção Go: Logs, Métricas, Traces e Sinais - três pilares
• Noções Básicas de Observabilidade - iniciadores de saúde e slog
• Logging: zap vs zerolog vs slog - correlacionar logs com traces

Versões de Stack: Esta página foi escrita para Go 1.26.x (GC padrão Green Tea, go fix modernizers - verifique o patch na compilação), chi (última - verifique na compilação), gin (última - verifique na compilação), echo (última - verifique na compilação), google.golang.org/grpc (última - verifique na compilação), sigs.k8s.io/controller-runtime (última - verifique na compilação), kubebuilder (última - verifique na compilação), tinygo (última - verifique os alvos de placa na compilação), wazero (última - verifique na compilação) e golangci-lint (última - verifique o conjunto de linters na compilação).