Registro Estructurado con slog

log/slog es el registrador estructurado de la biblioteca estándar de Go: campos clave-valor, salida por niveles y manejadores conectables para JSON, texto o receptores personalizados.

Resumen

El registro estructurado significa que cada línea transporta campos analizables por máquina (user_id, trace_id, err) en lugar de texto libre.

Go 1.21 añadió log/slog para reemplazar el log.Printf ad hoc y reducir la dependencia de registradores de terceros para la mayoría de los servicios.

Los manejadores controlan el formato de salida y el filtrado; los métodos Logger adjuntan atributos contextuales que fluyen a los registradores hijos.

La migración desde log y zap a menudo comienza envolviendo manejadores y haciendo coincidir los nombres de campo que tu plataforma de registro ya indexa.

Receta

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

logger := slog.New(slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{
    Level: slog.LevelInfo,
    AddSource: true,
}))
slog.SetDefault(logger)
slog.Info("payment captured", "order_id", orderID, "amount_cents", amount)

Cuándo usar esto:

• Nuevos servicios de Go que desean dependencias exclusivas de la biblioteca estándar.
• Registros JSON enviados a Loki, Elasticsearch o Cloud Logging.
• Middleware que registra solicitudes HTTP con nombres de atributos consistentes.
• Bibliotecas que aceptan *slog.Logger para registro inyectable.
• Migración gradual desde log.Printf sin reescribir cada sitio de llamada a la vez.

Ejemplo de Trabajo

package main
 
import (
    "context"
    "log/slog"
    "net/http"
    "os"
    "time"
)
 
type ctxKey string
 
const loggerKey ctxKey = "logger"
 
func main() {
    base := slog.New(slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{
        Level: slog.LevelDebug,
    }))
    slog.SetDefault(base)
 
    mux := http.NewServeMux()
    mux.Handle("GET /orders/{id}", injectLogger(base.With("service", "orders-api"))(
        accessLog(http.HandlerFunc(getOrder)),
    ))
 
    srv := &http.Server{Addr: ":8080", Handler: mux}
    slog.Info("listening", "addr", srv.Addr)
    if err := srv.ListenAndServe(); err != nil {
        slog.Error("server stopped", "err", err)
        os.Exit(1)
    }
}
 
func injectLogger(l *slog.Logger) func(http.Handler) http.Handler {
    return func(next http.Handler) http.Handler {
        return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
            reqLog := l.With("request_id", r.Header.Get("X-Request-ID"))
            ctx := context.WithValue(r.Context(), loggerKey, reqLog)
            next.ServeHTTP(w, r.WithContext(ctx))
        })
    }
}
 
func loggerFrom(ctx context.Context) *slog.Logger {
    if l, ok := ctx.Value(loggerKey).(*slog.Logger); ok {
        return l
    }
    return slog.Default()
}
 
func accessLog(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        start := time.Now()
        next.ServeHTTP(w, r)
        loggerFrom(r.Context()).Info("request complete",
            "method", r.Method,
            "path", r.URL.Path,
            "duration_ms", time.Since(start).Milliseconds(),
        )
    })
}
 
func getOrder(w http.ResponseWriter, r *http.Request) {
    id := r.PathValue("id")
    loggerFrom(r.Context()).Info("fetch order", "order_id", id)
    w.Write([]byte(`{"id":"` + id + `"}`))
}

Lo que esto demuestra:

• Manejador JSON con nivel explícito y registrador predeterminado para todo el servicio.
• Registradores hijos a través de With para request_id por solicitud sin mutar el padre.
• *slog.Logger transportado en el contexto para manejadores en capas profundas de la pila de llamadas.
• Registro de acceso separado del registro de negocio con campos de correlación compartidos.

Inmersión Profunda

Cómo Funciona

• slog.Logger contiene un Handler y atributos persistentes opcionales de With / WithGroup.
• Cada llamada a Info, Warn, Error construye un slog.Record (hora, nivel, mensaje, atributos) y lo pasa al manejador.
• Los manejadores implementan Enabled, Handle y WithAttrs / WithGroup para la inmutabilidad al derivar registradores hijos.
• slog.SetDefault conecta el registrador de todo el proceso utilizado por las llamadas de nivel superior de slog.Info.

Manejadores de un Vistazo

Niveles

Establece HandlerOptions.Level para filtrar registros por debajo del umbral antes de que se ejecute Handle.

Notas de Go

// Campos costosos perezosos - evaluados solo si el nivel está habilitado
slog.Info("snapshot", "payload", slog.LogValuerFunc(func() slog.Value {
    return slog.StringValue(expensiveSerialize())
}))
 
// Grupos anidan atributos en JSON: {"request":{"method":"GET"}}
log := logger.WithGroup("request")
log.Info("in", "method", r.Method, "path", r.URL.Path)

Migrando desde log y zap

Trampas Comunes

• Registrar antes de SetDefault: Los primeros registros en main usan el valor predeterminado de texto. Configura el manejador antes de que otros paquetes registren.
• Claves de atributo duplicadas: Las claves posteriores con el mismo nombre pueden confundir a los analizadores JSON; usa convenciones de nombres consistentes.
• Registrar secretos: Nunca registres encabezados de autenticación, contraseñas o números de tarjeta completos (PAN). Redacta en un envoltorio Handle personalizado.
• Nombre del atributo Error: Usa "err", err consistentemente; algunas plataformas mapean error a columnas especiales.
• Campos de alta cardinalidad: Registrar IDs de usuario sin procesar en cada línea de depuración aumenta el costo de almacenamiento; muestrea o agrega en métricas en su lugar.
• Falta AddSource en producción: Las líneas de origen ayudan a la depuración pero agregan asignaciones de memoria; habilítalo selectivamente.
• Predeterminado global en pruebas: Las pruebas que analizan registros deben inyectar un manejador slog.New(slog.NewTextHandler(&buf, nil)).

Alternativas

Preguntas Frecuentes

Relacionado

• Conceptos Básicos de Observabilidad - Inicios rápidos de slog y salud
• Go en Producción: Registros, Métricas, Trazas y Señales - Visión general de los tres pilares
• Trazas de OpenTelemetry en Servicios Go - IDs de traza en campos de registro
• Mejores Prácticas de Observabilidad - Cardinalidad y reglas de guardia
• Cadenas de Middleware y Contexto de Solicitud - Patrones de middleware HTTP

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