Golang log/slog: TextHandler, JSONHandler: incorrect docs

Go version

go1.24

Output of go env in your module/workspace:

AR='ar'
CC='cc'
CGO_CFLAGS='-O2 -g'
CGO_CPPFLAGS=''
CGO_CXXFLAGS='-O2 -g'
CGO_ENABLED='1'
CGO_FFLAGS='-O2 -g'
CGO_LDFLAGS='-O2 -g'
CXX='c++'
GCCGO='gccgo'
GO111MODULE=''
GOARCH='arm64'
GOARM64='v8.0'
GOAUTH='netrc'
GOBIN=''
GOCACHE='/Users/08d2/Library/Caches/go-build'
GOCACHEPROG=''
GODEBUG=''
GOENV='/Users/08d2/Library/Application Support/go/env'
GOEXE=''
GOEXPERIMENT=''
GOFIPS140='off'
GOFLAGS=''
GOGCCFLAGS='-fPIC -arch arm64 -pthread -fno-caret-diagnostics -Qunused-arguments -fmessage-length=0 -ffile-prefix-map=/var/folders/3j/jnfkmqxn2pq4r58r0dcqg1k00000gn/T/go-build1706432072=/tmp/go-build -gno-record-gcc-switches -fno-common'
GOHOSTARCH='arm64'
GOHOSTOS='darwin'
GOINSECURE=''
GOMOD='/dev/null'
GOMODCACHE='/Users/08d2/pkg/mod'
GONOPROXY=''
GONOSUMDB=''
GOOS='darwin'
GOPATH='/Users/08d2'
GOPRIVATE=''
GOPROXY='https://proxy.golang.org,direct'
GOROOT='/opt/homebrew/Cellar/go/1.24.2/libexec'
GOSUMDB='sum.golang.org'
GOTELEMETRY='local'
GOTELEMETRYDIR='/Users/08d2/Library/Application Support/go/telemetry'
GOTMPDIR=''
GOTOOLCHAIN='auto'
GOTOOLDIR='/opt/homebrew/Cellar/go/1.24.2/libexec/pkg/tool/darwin_arm64'
GOVCS=''
GOVERSION='go1.24.2'
GOWORK=''
PKG_CONFIG='pkg-config'

What did you do?

https://pkg.go.dev/log/slog#TextHandler.Handle

If the Record's level is zero, the level is omitted. Otherwise, the key is "level" and the value of Level.String is output.

https://pkg.go.dev/log/slog#JSONHandler.Handle

If the Record's level is zero, the level is omitted. Otherwise, the key is "level" and the value of Level.String is output.

--

https://go.dev/play/p/gPX5U_TilI6

package main

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

func main() {
    th := slog.NewTextHandler(os.Stderr, nil)
    th.Handle(context.TODO(), slog.NewRecord(time.Now().UTC(), 0, "message 1", 0))
    jh := slog.NewJSONHandler(os.Stderr, nil)
    jh.Handle(context.TODO(), slog.NewRecord(time.Now().UTC(), 0, "message 2", 0))
}

Handle gets Record values with level == 0 in both cases.

What did you see happen?

time=2009-11-10T23:00:00.000Z level=INFO msg="message 1"
{"time":"2009-11-10T23:00:00Z","level":"INFO","msg":"message 2"}

What did you expect to see?

time=2009-11-10T23:00:00.000Z level=INFO msg="message 1"
{"time":"2009-11-10T23:00:00Z","level":"INFO","msg":"message 2"}

The level value is not omitted. Which is correct, I think! The docs just need to be fixed.

Comment From: gabyhelp

Related Issues

• log/slog: TextHandler logs an empty Source struct when used as `log` output #73808 (closed)
• log/slog: Using `SetDefault` causes `level` and `msg` being rendered wrong if log called in a panic recovery middleware #64015 (closed)
• testing/slogtest: Parsing example fails when level is Error or Warn #62115 (closed)
• log/slog: inconsistent handling of empty groups #61067 (closed)
• log/slog: slog.SetDefault side effects log.Print is not respecting level #57396 (closed)
• log/slog: logger discards errors from handler #66579 (closed)
• slog/log: Concurrent writes to TextHandler and JSONHandler lose log lines. #61321 (closed)
• log/slog: JSONHandler does not format the source attribute in conformance with its documentation #60329 (closed)
• log/slog: "[HandlerOptions.Level]" doc syntax not rendered correctly on pkgsite #64485 (closed)

Related Documentation

• Package slog > type HandlerOptions 1.21

_{(Emoji vote if this was helpful or unhelpful; more detailed feedback welcome in this discussion.)}

Comment From: gopherbot

Change https://go.dev/cl/680055 mentions this issue: log/slog: fix level doc on handlers