Logging Estruturado com slog

log/slog é o logger estruturado da biblioteca padrão do Go: campos chave-valor, saída com níveis e handlers plugáveis para JSON, texto ou sinks customizados.

Resumo

Logging estruturado significa que cada linha carrega campos analisáveis por máquina (user_id, trace_id, err) em vez de texto livre.

Go 1.21 adicionou log/slog para substituir o log.Printf ad hoc e reduzir a dependência de loggers de terceiros para a maioria dos serviços.

Handlers controlam o formato de saída e a filtragem; métodos Logger anexam atributos contextuais que fluem para loggers filhos.

A migração de log e de zap geralmente começa encapsulando handlers e combinando os nomes de campo que sua plataforma de log já indexa.

Receita

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

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

Quando usar isso:

• Novos serviços Go que desejam dependências apenas da biblioteca padrão
• Logs JSON enviados para Loki, Elasticsearch ou Cloud Logging
• Middleware que registra requisições HTTP com nomes de atributos consistentes
• Bibliotecas que aceitam *slog.Logger para logging injetável
• Migração gradual do log.Printf sem reescrever todos os pontos de chamada de uma vez

Exemplo de Trabalho

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("escutando", "addr", srv.Addr)
    if err := srv.ListenAndServe(); err != nil {
        slog.Error("servidor parado", "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("requisição completa",
            "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("buscando pedido", "order_id", id)
    w.Write([]byte(`{"id":"` + id + `"}`))
}

O que isso demonstra:

• Handler JSON com nível explícito e logger padrão para todo o serviço
• Loggers filhos via With para request_id por requisição sem mutar o pai
• *slog.Logger transportado por contexto para handlers profundos na pilha de chamadas
• Logging de acesso separado do logging de negócios com campos de correlação compartilhados

Mergulho Profundo

Como Funciona

• slog.Logger contém um Handler e atributos persistentes opcionais de With / WithGroup.
• Cada chamada Info, Warn, Error constrói um slog.Record (tempo, nível, mensagem, atributos) e o passa para o handler.
• Handlers implementam Enabled, Handle e WithAttrs / WithGroup para imutabilidade ao derivar loggers filhos.
• slog.SetDefault configura o logger de todo o processo usado pelas chamadas de nível superior slog.Info.

Handlers em Resumo

Níveis

Defina HandlerOptions.Level para filtrar registros abaixo do limite antes que Handle seja executado.

Notas Go

// Campos caros preguiçosos - avaliados apenas se o nível estiver habilitado
slog.Info("snapshot", "payload", slog.LogValuerFunc(func() slog.Value {
    return slog.StringValue(expensiveSerialize())
}))
 
// Grupos aninham atributos em JSON: {"request":{"method":"GET"}}
log := logger.WithGroup("request")
log.Info("in", "method", r.Method, "path", r.URL.Path)

Migrando de log e zap

Armadilhas

• Logging antes de SetDefault - Logs iniciais em main usam o padrão de texto. Configure o handler antes que outros pacotes registrem.
• Chaves de atributo duplicadas - Chaves posteriores com o mesmo nome podem confundir parsers JSON; use convenções de nomenclatura consistentes.
• Registrar segredos - Nunca registre cabeçalhos de autenticação, senhas ou PANs completos. Redija em um wrapper Handle customizado.
• Nome do atributo Error - Use "err", err consistentemente; algumas plataformas mapeiam error para colunas especiais.
• Campos de alta cardinalidade - Registrar IDs de usuário brutos em cada linha de debug aumenta o custo de armazenamento; amostre ou agregue em métricas em vez disso.
• AddSource ausente em produção - Linhas de origem ajudam na depuração, mas adicionam alocação; habilite seletivamente.
• Padrão global em testes - Testes que analisam logs devem injetar um handler slog.New(slog.NewTextHandler(&buf, nil)).

Alternativas

FAQs

Relacionados

• Noções Básicas de Observabilidade - Inícios rápidos de slog e saúde
• Go em Produção: Logs, Métricas, Traces e Sinais - Visão geral dos três pilares
• OpenTelemetry Tracing em Serviços Go - IDs de trace em campos de log
• Melhores Práticas de Observabilidade - Regras de cardinalidade e plantão
• Cadeias de Middleware e Contexto de Requisição - Padrões de middleware HTTP

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