golang slog
- Repo stars 0
- Author repo skills-registry
- Domain
- AI
- Author-declared agents
- No explicit declaration found; this is not inferred or tested compatibility
- Static check
- 88 / 100 · heuristic scan, not runtime safety proof
- Runtime evidence
- Not run; no isolated runtime test evidence is currently recorded
- Author / version / license
- @tomevault-io · no license declared
- Token usage
- Moderate
- Setup complexity
- Guided setup
- External API key
- Not required
- Operating systems
- Unspecified (assume cross-platform)
- Runtime requirements
- No explicit requirements detected
- Detected file/system behavior
-
- Read-only
- Write / modify
- Env read
- Network behavior
- External requests
- Install commands
- None (reference only)
Heads up: Tool permissions are not declared; actual access depends on the runtime.
# Golang slog
Use this skill when implementing structured logging in Go with the standard library `log/slog` package.
Use it alongside the `structured-logging` skill:
- `structured-logging` defines the cross-language schema, field naming, safety, and observability rules
- `golang-slog` shows how to implement those rules idiomatically in Go with `log/slog`
## When to Use
- Adding structured logging to a Go service or CLI
- Replacing ad-hoc `log.Printf` calls with structured events
- Standardising common log fields across Go services
- Building request-scoped, worker-scoped, or job-scoped loggers
- Implementing redaction, log schema normalisation, or dynamic log levels
## Default Stance
Unless there is a clear reason not to, prefer these defaults:
- Use the standard library **`log/slog`** for Go 1.21+
- Prefer a **`Format` config** such as `json` or `text`, rather than a bare `JSON` boolean
- Use **`JSONHandler` in production** and **`TextHandler` locally**
- Construct the logger once during application startup
- Attach stable application metadata once with **`Logger.With(...)`**
- Keep the **schema aligned with the `structured-logging` skill**
- Prefer **typed attrs** like `slog.String`, `slog.Int`, `slog.Int64`, `slog.Duration`, `slog.Bool`
- Prefer **`InfoContext` / `ErrorContext` / `LogAttrs`** when a `context.Context` is available
- Use **`WithGroup`** or `slog.Group(...)` for nested structured context
- Use **`ReplaceAttr`** and **`LogValuer`** for schema normalisation and redaction
- Pass `*slog.Logger` as a dependency instead of hiding it in global state when possible
## Version Notes
- `log/slog` is in the Go standard library starting with **Go 1.21**
- `slog.MultiHandler` is a **newer addition**; only use it if your project's Go version supports it
- If your codebase targets older Go versions, use your existing logging stack instead of forcing `slog`
## Schema Alignment with `structured-logging`
The `structured-logging` skill recommends canonical fields like:
- `timestamp`
- `level`
- `message`
- `service`
- `environment`
- `application_version`
- `application_commit`
- `request_id`
- `trace_id`
- `span_id`
- `user_id`
- `operation`
- `outcome`
- `duration_ms`
- `error_kind`
- `error_code`
- `error_message`
By default, `slog` emits built-in keys such as:
- `time`
- `level`
- `msg`
- `source`
If you want Go logs to match the shared schema exactly, rename built-in keys with `HandlerOptions.ReplaceAttr`.
## Recommended Logger Bootstrap
Centralise logger construction in `main` or a small bootstrap package.
```go
package logging
import (
"fmt"
"io"
"log/slog"
)
type Format string
const (
FormatJSON Format = "json"
FormatText Format = "text"
)
type config struct {
environment string
service string
applicationVersion string
applicationCommit string
format Format
addSource bool
level slog.Leveler
replaceAttr func(groups []string, a slog.Attr) slog.Attr
}
type Option func(*config)
func WithEnvironment(v string) Option {
return func(c *config) { c.environment = v }
}
func WithService(v string) Option {
return func(c *config) { c.service = v }
}
func WithApplicationVersion(v string) Option {
return func(c *config) { c.applicationVersion = v }
}
func WithApplicationCommit(v string) Option {
return func(c *config) { c.applicationCommit = v }
}
func WithFormat(v Format) Option {
return func(c *config) { c.format = v }
}
func WithAddSource(v bool) Option {
return func(c *config) { c.addSource = v }
}
func WithLevel(v slog.Leveler) Option {
return func(c *config) { c.level = v }
}
func WithReplaceAttr(fn func(groups []string, a slog.Attr) slog.Attr) Option {
return func(c *config) { c.replaceAttr = fn }
}
func LevelVarFromString(v string) (*slog.LevelVar, error) {
var level slog.LevelVar
if err := level.UnmarshalText([]byte(v)); err != nil {
return nil, fmt.Errorf("parse log level %q: %w", v, err)
}
return &level, nil
}
func New(w io.Writer, opts ...Option) (*slog.Logger, error) {
cfg := config{
format: FormatJSON,
level: slog.LevelInfo,
replaceAttr: func(groups []string, a slog.Attr) slog.Attr {
switch a.Key {
case slog.TimeKey:
a.Key = "timestamp"
case slog.MessageKey:
a.Key = "message"
}
return a
},
}
for _, opt := range opts {
opt(&cfg)
}
handlerOptions := &slog.HandlerOptions{
AddSource: cfg.addSource,
Level: cfg.level,
ReplaceAttr: cfg.replaceAttr,
}
var handler slog.Handler
switch cfg.format {
case FormatJSON:
handler = slog.NewJSONHandler(w, handlerOptions)
case FormatText:
handler = slog.NewTextHandler(w, handlerOptions)
default:
return nil, fmt.Errorf("unsupported log format: %q", cfg.format)
}
logger := slog.New(handler).With(
slog.String("service", cfg.service),
slog.String("environment", cfg.environment),
slog.String("application_version", cfg.applicationVersion),
slog.String("application_commit", cfg.applicationCommit),
)
return logger, nil
}
```
Example use:
```go
level, err := logging.LevelVarFromString("info")
if err != nil {
return err
}
logger, err := logging.New(os.Stdout,
logging.WithService("users-api"),
logging.WithEnvironment("production"),
logging.WithApplicationVersion("1.8.0"),
logging.WithApplicationCommit("a1b2c3d4"),
logging.WithFormat(logging.FormatJSON),
logging.WithLevel(level),
)
if err != nil {
return err
}
```
Guidance:
- Build one base logger at startup
- Prefer **functional options** when the bootstrap needs several optional settings
- Add `service`, `environment`, `application_version`, and `application_commit` there
- Prefer a **format enum/string** like `json` or `text` over a `JSON bool`
- Use `JSONHandler` for production ingestion
- Use `TextHandler` only when human readability is more important than strict machine parsing
## Global vs Injected Logger
Prefer:
- Constructing the logger at startup
- Injecting `*slog.Logger` into servers, services, workers, and repositories that need it
Avoid:
- Scattering calls to `slog.Default()` throughout the codebase without a reason
- Using package globals for everything
`SetDefault` is acceptable at the process boundary if you explicitly want top-level `slog.Info(...)` and legacy `log.Print(...)` calls to flow through the same handler, but keep that decision near startup.
## Common Attribute Strategy
### Stable Application Metadata
Attach these once to the base logger:
```go
baseLogger := logger.With(
slog.String("service", "users-api"),
slog.String("environment", "production"),
slog.String("application_version", "1.8.0"),
slog.String("application_commit", "a1b2c3d4"),
)
```
### Request- or Job-Scoped Metadata
Attach these at the request/job boundary:
```go
requestLogger := baseLogger.With(
slog.String("request_id", requestID),
slog.String("trace_id", traceID),
slog.String("span_id", spanID),
slog.String("user_id", userID),
)
```
Prefer deriving child loggers with `With(...)` rather than repeating the same attrs on every line.
## Context Usage
If a `context.Context` is available, prefer the `...Context` forms:
- `logger.InfoContext(ctx, ...)`
- `logger.ErrorContext(ctx, ...)`
- `logger.LogAttrs(ctx, ...)`
Why:
- custom handlers may extract trace/span metadata from the context
- it keeps logs aligned with request-scoped and tracing-aware systems
Rules:
- pass context when you already have one
- do not create fake contexts just to log
- do not treat context as a generic service locator
## HTTP Request Pattern
Derive a request logger at the boundary and reuse it for the whole flow.
```go
func (s *Server) handleGetUser(w http.ResponseWriter, r *http.Request) {
start := time.Now()
logger := s.logger.With(
slog.String("request_id", requestIDFromRequest(r)),
slog.String("trace_id", traceIDFromContext(r.Context())),
slog.String("http_method", r.Method),
slog.String("http_route", "/users/{id}"),
)
user, err := s.userService.GetByID(r.Context(), chi.URLParam(r, "id"))
if err != nil {
logger.ErrorContext(r.Context(), "get user failed",
slog.String("operation", "get_user"),
slog.String("outcome", "failure"),
slog.String("error_kind", "user_lookup_failed"),
slog.String("error_message", "failed to fetch user"),
slog.Int64("duration_ms", time.Since(start).Milliseconds()),
)
return
}
logger.InfoContext(r.Context(), "http request completed",
slog.String("operation", "get_user"),
slog.String("outcome", "success"),
slog.Int("http_status_code", http.StatusOK),
slog.Int64("duration_ms", time.Since(start).Milliseconds()),
)
_ = user
}
```
Keep boundary logs summary-oriented. Avoid logging every internal function call in production.
## Prefer Typed Attrs
Prefer:
```go
logger.Info("user authenticated",
slog.String("user_id", userID),
slog.String("operation", "login"),
slog.Int64("duration_ms", duration.Milliseconds()),
)
```
Over large alternating key/value calls when they get dense or performance-sensitive.
Notes:
- alternating key/value syntax is valid and ergonomic for small calls
- typed attrs are clearer in larger calls
- typed attrs also avoid mistakes that produce `!BADKEY`
## Hot Paths and `LogAttrs`
If profiling shows logging overhead matters, prefer `LogAttrs` with typed attrs.
```go
logger.LogAttrs(ctx, slog.LevelInfo, "cache refresh completed",
slog.String("operation", "refresh_cache"),
slog.String("outcome", "success"),
slog.Int64("duration_ms", duration.Milliseconds()),
)
```
Use this especially in high-frequency code paths.
## Grouping Attributes
Use groups when nested context improves clarity or prevents key collisions.
```go
logger.Info("request finished",
slog.Group("request",
slog.String("method", r.Method),
slog.String("route", "/users/{id}"),
),
slog.Group("auth",
slog.String("user_id", userID),
slog.String("actor_type", "user"),
),
)
```
Use `WithGroup("http")` or `slog.Group("http", ...)` when multiple subsystems would otherwise reuse keys like `id`, `status`, or `method`.
## Error Logging
Log errors as structured events, not only as formatted strings.
Prefer:
```go
logger.ErrorContext(ctx, "invoice payment failed",
slog.String("operation", "charge_invoice"),
slog.String("outcome", "failure"),
slog.String("error_kind", "payment_gateway_error"),
slog.String("error_code", "card_declined"),
slog.String("error_message", "payment provider declined charge"),
slog.String("user_id", userID),
slog.Int64("duration_ms", duration.Milliseconds()),
)
```
Guidance:
- prefer stable domain fields like `error_kind` and `error_code`
- keep `error_message` safe and sanitised
- include the raw `error` value only when useful and safe
- avoid logging the same failure at every layer
When you do need the raw error object:
```go
logger.ErrorContext(ctx, "dependency call failed",
slog.Any("error", err),
slog.String("dependency", "billing-api"),
)
```
`JSONHandler` formats error-valued attrs as strings.
## Redaction and Sensitive Data
Never log secrets directly.
Use `LogValuer` for type-level redaction:
```go
type Token string
func (Token) LogValue() slog.Value {
return slog.StringValue("REDACTED")
}
```
Use `ReplaceAttr` for cross-cutting redaction or key normalisation:
```go
opts := &slog.HandlerOptions{
ReplaceAttr: func(groups []string, a slog.Attr) slog.Attr {
if a.Key == "authorization" || a.Key == "token" {
return slog.String(a.Key, "REDACTED")
}
return a
},
}
```
Prefer type-local redaction with `LogValuer` when the data type itself is sensitive. Use `ReplaceAttr` when you need a handler-wide policy.
## Performance Guidance
- Use `Logger.With(...)` for common attrs instead of repeating them
- Prefer `LogAttrs` in hot paths
- Use typed attrs for common scalar values
- Avoid expensive string formatting before checking whether a level is enabled
- Pass values directly when possible instead of eagerly calling `.String()`
- Use `LogValuer` to defer expensive computation for debug logs
Example:
```go
if logger.Enabled(ctx, slog.LevelDebug) {
logger.DebugContext(ctx, "computed plan",
slog.Any("plan", buildDebugPlan(input)),
)
}
```
Avoid:
```go
logger.DebugContext(ctx, "computed plan",
slog.String("plan", buildDebugPlan(input).String()),
)
```
if `buildDebugPlan` is expensive and debug logging may be disabled.
## Dynamic Levels
Use `slog.LevelVar` when the level may change at runtime.
```go
var level = new(slog.LevelVar)
level.Set(slog.LevelInfo)
logger := slog.New(slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{
Level: level,
}))
```
If your level comes from config, flags, or environment variables, a small helper is reasonable:
```go
func LevelVarFromString(v string) (*slog.LevelVar, error) {
var level slog.LevelVar
if err := level.UnmarshalText([]byte(v)); err != nil {
return nil, fmt.Errorf("parse log level %q: %w", v, err)
}
return &level, nil
}
```
This is appropriate for CLIs, services with admin-configurable verbosity, or temporary incident debugging.
## Bridging the Old `log` Package
If you still have legacy `log.Print` / `log.Printf` calls, you can centralise output with:
```go
slog.SetDefault(logger)
```
That allows the default `log` package to emit through the configured `slog` handler.
Use this only as a deliberate application-wide choice, not as a substitute for dependency injection.
## Testing Guidance
For tests around logging:
- write to a `bytes.Buffer`
- use `ReplaceAttr` to remove or normalise time/source fields
- assert on structured output, not on fragile formatting details
- prefer JSON output in tests when machine-readable assertions are easier
Example:
```go
var buf bytes.Buffer
logger := slog.New(slog.NewJSONHandler(&buf, &slog.HandlerOptions{
ReplaceAttr: func(groups []string, a slog.Attr) slog.Attr {
if a.Key == slog.TimeKey {
return slog.Attr{}
}
return a
},
}))
```
## Review Checklist
When reviewing Go `slog` usage, check for:
- `log/slog` used consistently instead of mixed ad-hoc logging styles
- base logger created centrally at startup
- stable common attrs attached with `With(...)`
- shared schema aligned with the `structured-logging` skill
- `ReplaceAttr` used when canonical key renaming is needed
- `InfoContext` / `ErrorContext` used when context already exists
- `LogAttrs` used in hot paths where it matters
- structured error fields instead of only formatted strings
- redaction for secrets and sensitive values
- no repeated noisy logs for the same failure across layers
- JSON logs used for production ingestion
## Anti-Patterns
Avoid these unless there is a strong reason:
- logging with `fmt.Sprintf` into one giant string
- using `slog.Any` for everything when typed attrs are clearer
- eagerly computing expensive debug fields when debug is disabled
- forcing every function to call `slog.Default()`
- burying the logger in context as a universal service locator
- logging secrets, tokens, or raw auth headers
- leaving built-in keys as `time`/`msg` when the rest of the platform expects `timestamp`/`message`
- emitting text logs in production when downstream systems expect JSON
- logging every internal function call instead of boundary summaries
## Quick Template
```go
level := new(slog.LevelVar)
level.Set(slog.LevelInfo)
logger := slog.New(slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{
Level: level,
ReplaceAttr: func(groups []string, a slog.Attr) slog.Attr {
switch a.Key {
case slog.TimeKey:
a.Key = "timestamp"
case slog.MessageKey:
a.Key = "message"
}
return a
},
})).With(
slog.String("service", "users-api"),
slog.String("environment", "production"),
slog.String("application_version", "1.0.0"),
slog.String("application_commit", "abcdef12"),
)
logger.Info("user authenticated",
slog.String("request_id", requestID),
slog.String("trace_id", traceID),
slog.String("user_id", userID),
slog.String("operation", "login"),
slog.String("outcome", "success"),
slog.Int64("duration_ms", duration.Milliseconds()),
)
```
---
> Source: [brpaz/agent-skills](https://github.com/brpaz/agent-skills) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-05-23 -->
Sections and files
Listed in source order.
sections -> When to Use → Default Stance → Version Notes → Schema Alignment with structured-logging → Recommended Logger Bootstrap → Global vs Injected Logger
terms -> log/slog · Format config · JSONHandler in production · TextHandler locally · Logger.With(...) · schema aligned with the structured-logging skill · typed attrs · InfoContext / ErrorContext / LogAttrs
files/cmd -> log/slog · structured-logging · golang-slog · log.Printf · Format · text · JSONHandler · TextHandler
body sha256 -> df8c8e63ceb0
When to Use
Adding structured logging to a Go service or CLI Replacing ad-hoc
log.Printfcalls with structured events Standardising common log fields across Go services Building request-scoped, worker-scoped, or job-scoped loggers Implementing redaction, log schema normalisation, or dynamic log levelsDefault Stance
Unless there is a clear reason not to, prefer these defaults: Use the standard library
log/slogfor Go 1.21+ Prefer aFormatconfig such asjsonortext, rather than a bareJSONboolean UseJSONHandlerin production andTextHandlerlocally Construct the logger once during application startupVersion Notes
log/slogis in the Go standard library starting with Go 1.21slog.MultiHandleris a newer addition; only use it if your project's Go version supports it If your codebase targets older Go versions, use your existing logging stack instead of forcingslogSchema Alignment with structured-logging
The
structured-loggingskill recommends canonical fields like:timestamplevelmessageserviceRecommended Logger Bootstrap
Centralise logger construction in
mainor a small bootstrap package. Example use: Guidance: Build one base logger at startup Prefer functional options when the bootstrap needs several optional settings