Bibliotecas cliente de Prometheus y OpenTelemetry

Los servicios Go en producción exponen métricas de Prometheus para paneles y trazas de OpenTelemetry para la depuración de latencia de solicitudes.

Las bibliotecas cliente se encuentran en el borde HTTP/gRPC y envuelven las llamadas salientes sin reemplazar tu pila de logging.

Receta

Tarjeta de receta de referencia rápida - lista para copiar y pegar.

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")

Cuándo recurrir a esto:

• Los SREs necesitan métricas RED (tasa, errores, duración) por ruta y dependencia
• Los ingenieros de guardia rastrean solicitudes lentas entre servicios
• Kubernetes recopila /metrics o un colector de OTel recibe OTLP
• Estandarizas las bibliotecas de observabilidad en servidores chi, Gin y gRPC

Ejemplo de Trabajo

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))
}

Lo que esto demuestra:

• Histograma de Prometheus con etiquetas de baja cardinalidad (method, route, status)
• Patrones de ruta chi para estabilidad de etiquetas (evita URLs crudas con IDs)
• promhttp.Handler en una ruta dedicada para scrapers
• Middleware HTTP de OTel envolviendo el router para propagación de trazas

Inmersión Profunda

Cómo Funciona

• Cliente Prometheus registra colectores en un registro; promhttp expone el formato de exposición de texto.
• SDK de OpenTelemetry configura TracerProvider, exportadores (OTLP gRPC/HTTP) y atributos de recursos (service.name).
• otelhttp crea spans alrededor de los manejadores y propaga las cabeceras traceparent.
• Las métricas responden a "¿cuánto y cuán rápido?"; las trazas responden a "¿qué salto fue lento?".

Tipos de Métricas (Prometheus)

Esquema de Arranque de OTel

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

• Ejecuta un sidecar colector o un punto final OTLP a nivel de clúster en Kubernetes.
• Alinea service.name con las etiquetas de despliegue para la búsqueda de trazas.

Notas de Go

• Usa promauto solo cuando un único registro sea suficiente; las bibliotecas deben aceptar parámetros prometheus.Registerer.
• gRPC usa interceptores go.opentelemetry.io/contrib/instrumentation/google.golang.org/grpc/otelgrpc de manera similar.
• Nunca pongas IDs de usuario o segmentos de ruta ilimitados en las etiquetas de métricas.

Trampas Comunes

• Etiquetas de alta cardinalidad - /users/123 por solicitud explota las series. Solución: usa chi.RoutePattern() o nombres de ruta con plantillas.
• Doble instrumentación - métricas del framework más middleware personalizado duplican recuentos. Solución: un propietario por nombre de métrica en ADR.
• Registro global de Prometheus en bibliotecas - los paquetes importados registran colectores inesperadamente. Solución: pasa prometheus.Registerer a los constructores.
• Falta de cierre del tracer - los exportadores por lotes descartan spans al salir. Solución: Shutdown en SIGTERM con tiempo de espera de vaciado gradual.
• Scraping del puerto principal desde Internet - /metrics filtra detalles operativos. Solución: oyente separado o política de red en el puerto de administración.
• Muestreo de trazas al 100% siempre - el costo se dispara a escala. Solución: muestreo basado en el padre o probabilístico ajustado por entorno.

NzA2MjAyfDI5M29pZ2N8b2kuc2VkaXVnZWRvYw==

Alternativas

Preguntas Frecuentes

Relacionado

• Métricas de Prometheus y Paneles de Uso RED - metodología RED
• OpenTelemetry Tracing en Servicios Go - pipeline de trazas
• Producción Go: Logs, Métricas, Trazas y Señales - tres pilares
• Conceptos Básicos de Observabilidad - iniciadores de salud y slog
• Logging: zap vs zerolog vs slog - correlacionar logs con trazas

Versiones de Stack: Esta página fue escrita para Go 1.26.x (predeterminado GC de Green Tea, go fix modernizers - verificar parche en la compilación), chi (última - verificar en la compilación), gin (última - verificar en la compilación), echo (última - verificar en la compilación), google.golang.org/grpc (última - verificar en la compilación), sigs.k8s.io/controller-runtime (última - verificar en la compilación), kubebuilder (última - verificar en la compilación), tinygo (última - verificar objetivos de placa en la compilación), wazero (última - verificar en la compilación) y golangci-lint (última - verificar conjunto de linters en la compilación).