slog et log en Golang : les logs structurés en Go

slog en un exemple

log/slog (Go 1.21) écrit des enregistrements structurés : un message, un niveau et des attributs clé-valeur.

package main

import (
	"log/slog"
	"os"
)

func main() {
	opts := &slog.HandlerOptions{Level: slog.LevelDebug}
	logger := slog.New(slog.NewTextHandler(os.Stdout, opts))

	logger.Debug("cache lookup", "key", "user:42", "hit", false)
	logger.Info("user logged in", "user", "ada", "attempts", 1)
	logger.Warn("slow query", "table", "orders", "ms", 812)
	logger.Error("payment failed", "order", 1017, "err", "card declined")
}

Chaque ligne sort sous la forme time=... level=INFO msg="user logged in" user=ada attempts=1. Comme chaque valeur est un champ séparé, un collecteur de logs (Loki, Elasticsearch, CloudWatch, Datadog) peut filtrer sur user=ada ou level=ERROR sans expressions régulières sur du texte libre.

Les exemples de cette page écrivent sur os.Stdout pour que la sortie apparaisse dans l'ordre. Dans un vrai service, les logs vont généralement sur os.Stderr, qui est aussi là où écrit le logger par défaut.

Niveaux

Le handler écarte les enregistrements sous son niveau minimal, et le minimum par défaut est Info. C'est pourquoi slog.Debug(...) n'affiche rien tant que vous n'avez pas configuré un handler avec Level: slog.LevelDebug. Les écarts entre les valeurs laissent de la place pour des niveaux personnalisés comme slog.Level(2).

Pour changer le niveau à l'exécution (depuis un flag, un endpoint d'administration ou un signal), placez un slog.LevelVar dans les options et appelez Set dessus plus tard :

var level slog.LevelVar // zero value: Info
logger := slog.New(slog.NewJSONHandler(os.Stderr, &slog.HandlerOptions{Level: &level}))
level.Set(slog.LevelDebug) // from now on, debug records are written

Texte ou JSON

slog.NewTextHandler écrit des paires key=value, faciles à lire dans un terminal. slog.NewJSONHandler écrit un objet JSON par ligne, le format qu'attendent la plupart des pipelines de logs. Les appels de journalisation restent les mêmes ; seul le handler change.

package main

import (
	"errors"
	"log/slog"
	"os"
	"time"
)

func main() {
	// Drop the time attribute so the output is the same on every run.
	noTime := func(groups []string, a slog.Attr) slog.Attr {
		if a.Key == slog.TimeKey && len(groups) == 0 {
			return slog.Attr{}
		}
		return a
	}

	text := slog.New(slog.NewTextHandler(os.Stdout, &slog.HandlerOptions{ReplaceAttr: noTime}))
	json := slog.New(slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{ReplaceAttr: noTime}))

	for _, l := range []*slog.Logger{text, json} {
		l.Info("request served",
			"method", "GET",
			"path", "/items/7",
			"status", 200,
			"duration", 42*time.Millisecond,
		)
		l.Error("request failed", "err", errors.New("db timeout"), "retry", true)
	}
}

Les valeurs gardent leur type : status est un nombre dans la sortie JSON et retry un booléen, un time.Duration s'affiche 42ms en texte et en nanosecondes en JSON, et une error affiche son message. ReplaceAttr est le point d'accroche pour réécrire ou supprimer des attributs, utilisé ici pour retirer l'horodatage, et en pratique pour renommer des clés (msg en message) ou masquer des valeurs.

Attributs

La forme faiblement typée alterne clés et valeurs : "user", "ada", "attempts", 3. Elle est courte, et elle a un seul mode d'échec : un nombre impair d'arguments. La valeur restante est journalisée sous la clé !BADKEY. go vet le détecte :

./main.go:14:2: call to slog.Info missing a final value

Pour la sécurité du typage et un peu moins d'allocations, utilisez les constructeurs d'attributs, et LogAttrs pour journaliser dans un chemin critique :

logger.Info("order placed",
	slog.Int("order_id", 1017),
	slog.String("currency", "EUR"),
	slog.Float64("total", 59.90),
	slog.Duration("took", elapsed),
)

logger.LogAttrs(ctx, slog.LevelInfo, "order placed", slog.Int("order_id", 1017))

Utilisez une seule convention de nommage des clés dans toute la base de code (user_id partout, pas userID dans un package et uid dans un autre). Les requêtes dans votre système de logs en dépendent.

With : des loggers qui transportent du contexte

logger.With(attrs...) renvoie un nouveau logger qui ajoute ces attributs à chaque enregistrement. Créez-en un par requête ou par tâche, et toutes les lignes qu'il écrit peuvent être reliées entre elles :

package main

import (
	"log/slog"
	"os"
)

func handleRequest(base *slog.Logger, requestID, user string) {
	log := base.With("request_id", requestID, "user", user)

	log.Info("loading cart")
	log.Info("charging card", slog.Group("payment", "amount", 25, "currency", "USD"))
	log.Warn("inventory low", "sku", "A-17", "left", 2)
}

func main() {
	noTime := func(groups []string, a slog.Attr) slog.Attr {
		if a.Key == slog.TimeKey && len(groups) == 0 {
			return slog.Attr{}
		}
		return a
	}
	base := slog.New(slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{ReplaceAttr: noTime}))
	base = base.With("service", "checkout", "version", "1.4.2")

	handleRequest(base, "req-81", "ada")
}

Chaque ligne porte service, version, request_id et user sans les répéter à chaque appel. slog.Group imbrique des attributs, que le handler JSON écrit comme un objet imbriqué ("payment":{"amount":25,"currency":"USD"}) et le handler texte comme des clés pointées (payment.amount=25). logger.WithGroup("db") place tous les attributs suivants de ce logger sous un groupe.

Transmettez le logger lié à la requête en paramètre ou dans un champ de struct. Le stocker dans un context.Context est possible mais masque la dépendance ; les méthodes InfoContext(ctx, ...) de slog transmettent le context au handler, qu'un handler personnalisé peut utiliser pour en extraire des identifiants de trace.

Masquer les secrets avec LogValuer

Un type peut contrôler la façon dont il est journalisé en implémentant slog.LogValuer. Cela garde les mots de passe et les jetons hors des logs, quel que soit celui qui journalise la valeur :

package main

import (
	"log/slog"
	"os"
)

type Token string

func (Token) LogValue() slog.Value {
	return slog.StringValue("REDACTED")
}

type User struct {
	ID    int
	Email string
	Token Token
}

func (u User) LogValue() slog.Value {
	return slog.GroupValue(
		slog.Int("id", u.ID),
		slog.String("email", u.Email),
	)
}

func main() {
	noTime := func(groups []string, a slog.Attr) slog.Attr {
		if a.Key == slog.TimeKey && len(groups) == 0 {
			return slog.Attr{}
		}
		return a
	}
	logger := slog.New(slog.NewTextHandler(os.Stdout, &slog.HandlerOptions{ReplaceAttr: noTime}))

	u := User{ID: 7, Email: "ada@example.com", Token: "s3cr3t"}
	logger.Info("login", "user", u)
	logger.Info("token refresh", "token", u.Token)
}

User ne journalise que son identifiant et son e-mail, et un Token journalisé seul affiche REDACTED. Le handler n'appelle LogValue que lorsque l'enregistrement est réellement écrit, donc cela fonctionne aussi pour des valeurs coûteuses à calculer.

Le package log classique

log est antérieur à slog et convient toujours aux petits programmes et aux scripts. Il écrit des lignes sur la sortie d'erreur standard avec un préfixe de date et d'heure :

package main

import (
	"log"
	"os"
)

func main() {
	log.SetOutput(os.Stdout) // default is os.Stderr
	log.SetFlags(0)          // no timestamp, so the output is the same every run
	log.Println("plain line")
	log.Printf("processed %d files", 12)

	log.SetFlags(log.Lshortfile)
	log.SetPrefix("[worker] ")
	log.Println("with file:line and a prefix")

	errLog := log.New(os.Stdout, "ERROR ", log.Lmsgprefix)
	errLog.Println("a separate logger with its own prefix")
}

Trois familles de fonctions quittent ou provoquent un panic, et la différence compte :

• log.Fatal, log.Fatalf, log.Fatalln affichent puis appellent os.Exit(1). Les appels différés ne s'exécutent pas. Utilisez-les dans main pour les échecs au démarrage, jamais dans du code de bibliothèque ni dans des handlers de requêtes.
• log.Panic et ses variantes affichent puis provoquent un panic, donc les appels différés s'exécutent et le panic peut être récupéré.
• Toutes les autres fonctions écrivent simplement une ligne.

Pour journaliser dans un fichier, ouvrez-le et passez-le à log.New ou log.SetOutput ; io.MultiWriter(os.Stderr, f) écrit dans les deux.

log et slog ensemble

slog.SetDefault(logger) fait de logger le logger par défaut des fonctions de haut niveau slog.Info, et fait aussi passer la sortie du package log par lui. Les appels log.Printf existants dans votre code ou vos dépendances sortent alors sous forme d'enregistrements structurés au niveau Info :

slog.SetDefault(slog.New(slog.NewJSONHandler(os.Stderr, nil)))
log.Printf("legacy message") // {"time":"...","level":"INFO","msg":"legacy message"}

Avant SetDefault, le logger slog par défaut écrit via le package log, c'est pourquoi un simple slog.Info("hi") affiche 2026/09/23 14:30:00 INFO hi.

Règles pratiques

• Journalisez ou renvoyez une erreur, pas les deux. Une fonction qui journalise une erreur et la renvoie fait journaliser le même échec à chaque niveau de la pile d'appels. Remontez les erreurs avec du contexte, et journalisez une fois là où elles sont traitées.
• Mettez les données variables dans les attributs, pas dans le message. logger.Info("user created", "user_id", id) se regroupe bien dans un système de logs ; logger.Info(fmt.Sprintf("user %d created", id)) crée un message différent pour chaque utilisateur.
• Ne journalisez jamais de secrets ni de bodies de requête complets. Utilisez LogValuer ou ReplaceAttr pour masquer.
• Utilisez JSON en production, texte en développement. Choisissez le handler au démarrage à partir d'un flag ou d'une variable d'environnement.
• Choisissez les niveaux délibérément. Si tout est journalisé en Error, les alertes sur les erreurs deviennent du bruit.