Golang slog ve log: Go'da Yapılandırılmış Loglama

Tek örnekte slog

log/slog (Go 1.21) yapılandırılmış kayıtlar yazar: bir mesaj, bir seviye ve anahtar-değer nitelikleri.

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

Her satır time=... level=INFO msg="user logged in" user=ada attempts=1 olarak çıkar. Her değer ayrı bir alan olduğu için bir log toplayıcı (Loki, Elasticsearch, CloudWatch, Datadog) serbest metin üzerinde düzenli ifadeler kullanmadan user=ada ya da level=ERROR ile filtreleyebilir.

Bu sayfadaki örnekler, çıktı sırayla görünsün diye os.Stdout'a yazar. Gerçek bir serviste loglar genellikle varsayılan logger'ın da yazdığı yer olan os.Stderr'e gider.

Seviyeler

Handler minimum seviyesinin altındaki kayıtları atar ve varsayılan minimum Info'dur. Level: slog.LevelDebug ile bir handler yapılandırana kadar slog.Debug(...)'ın hiçbir şey yazdırmamasının nedeni budur. Değerler arasındaki boşluklar slog.Level(2) gibi özel seviyelere yer bırakır.

Seviyeyi çalışma zamanında (bir bayraktan, bir yönetim endpoint'inden ya da bir sinyalden) değiştirmek için seçeneklere bir slog.LevelVar koyun ve daha sonra onun üzerinde Set çağırın:

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

Text mi, JSON mu

slog.NewTextHandler, terminalde okunması kolay key=value çiftleri yazar. slog.NewJSONHandler, çoğu log hattının beklediği biçim olan satır başına bir JSON nesnesi yazar. Loglama çağrıları aynı kalır; yalnızca handler değişir.

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

Değerler tiplerini korur: JSON çıktısında status bir sayı, retry bir boolean'dır; bir time.Duration text'te 42ms, JSON'da nanosaniye olarak yazdırılır ve bir error mesajını yazdırır. ReplaceAttr, nitelikleri yeniden yazmak ya da kaldırmak için kancadır; burada zaman damgasını atmak için, pratikte ise anahtarları yeniden adlandırmak (msg'yi message yapmak) ya da değerleri maskelemek için kullanılır.

Nitelikler

Gevşek tipli biçim anahtarları ve değerleri sırayla yazar: "user", "ada", "attempts", 3. Kısadır ve tek bir başarısızlık biçimi vardır: tek sayıda argüman. Artan değer !BADKEY anahtarı altında loglanır. go vet bunu yakalar:

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

Tip güvenliği ve biraz daha az bellek ayırma için nitelik kurucularını, sık çalışan bir yolda loglarken de LogAttrs'ı kullanın:

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

Kod tabanı genelinde anahtarlar için tek bir adlandırma geleneği kullanın (bir pakette userID, bir başkasında uid değil, her yerde user_id). Log sisteminizdeki sorgular buna bağlıdır.

With: bağlam taşıyan logger'lar

logger.With(attrs...), bu nitelikleri her kayda ekleyen yeni bir logger döndürür. İstek ya da iş başına bir tane oluşturun, yazdığı her satır birbirine bağlanabilir:

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

Her satır, her çağrıda tekrarlanmadan service, version, request_id ve user taşır. slog.Group nitelikleri iç içe koyar; JSON handler'ı bunu iç içe bir nesne olarak ("payment":{"amount":25,"currency":"USD"}), text handler'ı ise noktalı anahtarlar olarak (payment.amount=25) yazar. logger.WithGroup("db"), o logger'ın sonraki her niteliğini bir grubun altına koyar.

İstek kapsamlı logger'ı bir parametre ya da struct alanı olarak aşağıya aktarın. Onu bir context.Context içinde saklamak mümkündür ama bağımlılığı gizler; slog'un InfoContext(ctx, ...) metotları context'i handler'a aktarır, özel bir handler da bunu trace ID'lerini çıkarmak için kullanabilir.

LogValuer ile sırları gizlemek

Bir tip slog.LogValuer'ı gerçekleştirerek nasıl loglanacağını kontrol edebilir. Bu, değeri kim loglarsa loglasın parolaları ve token'ları logların dışında tutar:

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 yalnızca ID'sini ve e-postasını loglar, tek başına loglanan bir Token ise REDACTED yazdırır. Handler LogValue'yu yalnızca kayıt gerçekten yazıldığında çağırır, bu yüzden hesaplanması pahalı değerler için de işe yarar.

Klasik log paketi

log, slog'dan eskidir ve küçük programlar ve betikler için hâlâ uygundur. Standart hataya tarih ve saat önekiyle satırlar yazar:

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

Üç fonksiyon çıkış yapar ya da panic olur ve fark önemlidir:

• log.Fatal, log.Fatalf, log.Fatalln yazdırır ve sonra os.Exit(1) çağırır. Ertelenmiş çağrılar çalışmaz. Onları başlangıç başarısızlıkları için main içinde kullanın, kütüphane kodunda ya da istek handler'larında asla kullanmayın.
• log.Panic ve benzerleri yazdırır ve sonra panic yapar, bu yüzden ertelenmiş çağrılar çalışır ve panic recover edilebilir.
• Diğer her fonksiyon yalnızca bir satır yazar.

Bir dosyaya loglamak için onu açıp log.New'a ya da log.SetOutput'a aktarın; io.MultiWriter(os.Stderr, f) ikisine birden yazar.

log ve slog birlikte

slog.SetDefault(logger), logger'ı üst seviye slog.Info fonksiyonları için varsayılan yapar ve log paketinin çıktısını da onun üzerinden yönlendirir. Kodunuzdaki ya da bağımlılıklardaki var olan log.Printf çağrıları o zaman Info seviyesinde yapılandırılmış kayıtlar olarak çıkar:

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

SetDefault'tan önce varsayılan slog logger'ı log paketi üzerinden yazar; çıplak bir slog.Info("hi")'ın 2026/09/23 14:30:00 INFO hi yazdırmasının nedeni budur.

Pratik kurallar

• Bir hatayı ya loglayın ya döndürün, ikisini birden değil. Bir hatayı loglayıp döndüren bir fonksiyon aynı başarısızlığın çağrı yığınının her seviyesinde loglanmasına yol açar. Hataları bağlamla yukarı döndürün ve ele alındıkları yerde bir kez loglayın.
• Değişken veriyi mesaja değil niteliklere koyun. logger.Info("user created", "user_id", id) bir log sisteminde iyi gruplanır; logger.Info(fmt.Sprintf("user %d created", id)) her kullanıcı için farklı bir mesaj oluşturur.
• Sırları ya da tam istek gövdelerini asla loglamayın. Maskelemek için LogValuer ya da ReplaceAttr kullanın.
• Production'da JSON, geliştirmede text kullanın. Handler'ı başlangıçta bir bayraktan ya da bir ortam değişkeninden seçin.
• Seviyeleri bilinçli seçin. Her şey Error seviyesinde loglanırsa hatalar üzerindeki alarmlar gürültüye dönüşür.