WIP: slog support

.github/workflows/tests.yaml

@@ -9,7 +9,7 @@ jobs:
   test:
     strategy:
       matrix:
-        version: [ '1.15', '1.16', '1.17', '1.18' ]
+        version: [ '1.15', '1.16', '1.17', '1.18', '1.19', '1.20', '1.21.0-rc.4' ]
         platform: [ ubuntu-latest, macos-latest, windows-latest ]
     runs-on: ${{ matrix.platform }}
     steps:

README.md

@@ -74,6 +74,28 @@ received:
 If the Go standard library had defined an interface for logging, this project
 probably would not be needed.  Alas, here we are.
 
+When the Go developers started developing such an interface with
+[slog](https://github.com/golang/go/issues/56345), they adopted some of the
+logr design but also left out some parts and changed others:
+
+| Feature | logr | slog |
+|---------|------|------|
+| High-level API | `Logger` (passed by value) | `Logger` (passed by [pointer](https://github.com/golang/go/issues/59126)) |
+| Low-level API | `LogSink` | `Handler` |
+| Stack unwinding | done by `LogSink` | done by `Logger` |
+| Skipping helper functions | `WithCallDepth`, `WithCallStackHelper` | [not supported by Logger](https://github.com/golang/go/issues/59145) |
+| Generating a value for logging on demand | `Marshaler` | `LogValuer` |
+| Log levels | >= 0, higher meaning "less important" | positive and negative, with 0 for "info" and higher meaning "more important" |
+| Error log entries | always logged, don't have a verbosity level | normal log entries with level >= `LevelError` |
+| Passing logger via context | `NewContext`, `FromContext` | no API |
+| Adding a name to a logger | `WithName` | no API |
+| Grouping of key/value pairs | not supported | `WithGroup`, `GroupValue` |
+
+The high-level slog API is explicitly meant to be one of many different APIs
+that can be layered on top of a shared `slog.Handler`. logr is one such
+alternative API, with interoperability as [described
+below](#slog-interoperability).
+
 ### Inspiration
 
 Before you consider this package, please read [this blog post by the
@@ -119,6 +141,63 @@ There are implementations for the following logging libraries:
 - **github.com/go-kit/log**: [gokitlogr](https://github.com/tonglil/gokitlogr) (also compatible with github.com/go-kit/kit/log since v0.12.0)
 - **bytes.Buffer** (writing to a buffer): [bufrlogr](https://github.com/tonglil/buflogr) (useful for ensuring values were logged, like during testing)
 
+## slog interoperability
+
+Interoperability goes both ways, using the `logr.Logger` API with a `slog.Handler`
+and using the `slog.Logger` API with a `logr.LogSink`. logr provides `ToSlog` and
+`FromSlog` API calls to convert between a `logr.Logger` and a `slog.Logger`. Because
+the `slog.Logger` API is optional, there are also variants of these calls which
+work directly with a `slog.Handler`.
+
+Ideally, the backend should support both logr and slog. In that case, log calls
+can go from the high-level API to the backend with no intermediate glue
+code. Because of a conflict in the parameters of the common Enabled method, it
+is [not possible to implement both interfaces in the same
+type](https://github.com/golang/go/issues/59110). A second type and methods for
+converting from one type to the other are needed. Here is an example:
+
+```
+// logSink implements logr.LogSink and logr.SlogImplementor.
+type logSink struct { ... }
+
+func (l *logSink) Enabled(lvl int) bool { ... }
+...
+
+// logHandler implements slog.Handler.
+type logHandler logSink
+
+func (l *logHandler) Enabled(ctx context.Context, slog.Level) bool { ... }
+...
+
+// Explicit support for converting between the two types is needed by logr
+// because it cannot do type assertions.
+
+func (l *logSink) GetSlogHandler() slog.Handler { return (*logHandler)(l) }
+func (l *logHandler) GetLogrLogSink() logr.LogSink { return (*logSink)(l) }
+```
+
+Such a backend also should support values that implement specific interfaces
+from both packages for logging (`logr.Marshaler`, `slog.LogValuer`). logr does not
+convert between those.
+
+If a backend only supports `logr.LogSink`, then `ToSlog` uses
+[`slogHandler`](sloghandler.go) to implement the `logr.Handler` on top of that
+`logr.LogSink`. This solution is problematic because there is no way to log the
+correct call site. All log entries with `slog.Level` >= `slog.LevelInfo` (= 0)
+and < `slog.LevelError` get logged as info message with logr level 0, >=
+`slog.LevelError` as error message and negative levels as debug messages with
+negated level (i.e. `slog.LevelDebug` = -4 becomes
+`V(4).Info`). `slog.LogValuer` will not get used. Applications which care about
+these aspects should switch to a logr implementation which supports slog.
+
+If a backend only supports slog.Handler, then `FromSlog` uses
+[`slogSink`](slogsink.go). This solution is more viable because call sites can
+be logged correctly. However, `logr.Marshaler` will not get used. Types that
+support `logr.Marshaler` should also support
+`slog.LogValuer`. `logr.Logger.Error` logs with `slog.ErrorLevel`,
+`logr.Logger.Info` with the negated level (i.e. `V(0).Info` uses `slog.Level` 0
+= `slog.InfoLevel`, `V(4).Info` uses `slog.Level` -4 = `slog.DebugLevel`).
+
 ## FAQ
 
 ### Conceptual
@@ -242,7 +321,9 @@ Otherwise, you can start out with `0` as "you always want to see this",
 
 Then gradually choose levels in between as you need them, working your way
 down from 10 (for debug and trace style logs) and up from 1 (for chattier
-info-type logs.)
+info-type logs). For reference, slog pre-defines -4 for debug logs
+(corresponds to 4 in logr), which matches what is
+[recommended for Kubernetes](https://github.com/kubernetes/community/blob/master/contributors/devel/sig-instrumentation/logging.md#what-method-to-use).
 
 #### How do I choose my keys?
 

slog.go

@@ -0,0 +1,81 @@
+//go:build go1.21
+// +build go1.21
+
+/*
+Copyright 2023 The logr Authors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package logr
+
+import (
+	"log/slog"
+)
+
+// SlogImplementor is an interface that a logr.LogSink can implement
+// to support efficient logging through the slog.Logger API.
+type SlogImplementor interface {
+	// GetSlogHandler returns a handler which uses the same settings as the logr.LogSink.
+	GetSlogHandler() slog.Handler
+}
+
+// LogrImplementor is an interface that a slog.Handler can implement
+// to support efficient logging through the logr.Logger API.
+type LogrImplementor interface {
+	// GetLogrLogSink returns a sink which uses the same settings as the slog.Handler.
+	GetLogrLogSink() LogSink
+}
+
+// ToSlog returns a slog.Logger which writes to the same backend as the logr.Logger.
+func ToSlog(logger Logger) *slog.Logger {
+	return slog.New(ToSlogHandler(logger))
+}
+
+// ToSlog returns a slog.Handler which writes to the same backend as the logr.Logger.
+func ToSlogHandler(logger Logger) slog.Handler {
+	if slogImplementor, ok := logger.GetSink().(SlogImplementor); ok {
+		handler := slogImplementor.GetSlogHandler()
+		return handler
+	}
+
+	return &slogHandler{sink: logger.GetSink()}
+}
+
+// FromSlog returns a logr.Logger which writes to the same backend as the slog.Logger.
+func FromSlog(logger *slog.Logger) Logger {
+	return FromSlogHandler(logger.Handler())
+}
+
+// FromSlog returns a logr.Logger which writes to the same backend as the slog.Handler.
+func FromSlogHandler(handler slog.Handler) Logger {
+	if logrImplementor, ok := handler.(LogrImplementor); ok {
+		logSink := logrImplementor.GetLogrLogSink()
+		return New(logSink)
+	}
+
+	return New(&slogSink{handler: handler})
+}
+
+func levelFromSlog(level slog.Level) int {
+	if level >= 0 {
+		// logr has no level lower than 0, so we have to truncate.
+		return 0
+	}
+	return int(-level)
+}
+
+func levelToSlog(level int) slog.Level {
+	// logr starts at info = 0 and higher values go towards debugging (negative in slog).
+	return slog.Level(-level)
+}

slog_test.go

@@ -0,0 +1,72 @@
+//go:build go1.21
+// +build go1.21
+
+/*
+Copyright 2023 The logr Authors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package logr_test
+
+import (
+	"errors"
+	"fmt"
+	"log/slog"
+	"os"
+
+	"github.com/go-logr/logr"
+	"github.com/go-logr/logr/funcr"
+)
+
+var debugWithoutTime = &slog.HandlerOptions{
+	ReplaceAttr: func(groups []string, a slog.Attr) slog.Attr {
+		if a.Key == "time" {
+			return slog.Attr{}
+		}
+		return a
+	},
+	Level: slog.LevelDebug,
+}
+
+func ExampleFromSlog() {
+	logger := logr.FromSlog(slog.New(slog.NewTextHandler(os.Stdout, debugWithoutTime)))
+
+	logger.Info("hello world")
+	logger.Error(errors.New("fake error"), "ignore me")
+	logger.WithValues("x", 1, "y", 2).WithValues("str", "abc").WithName("foo").WithName("bar").V(4).Info("with values, verbosity and name")
+
+	// Output:
+	// level=INFO msg="hello world"
+	// level=ERROR msg="ignore me" err="fake error"
+	// level=DEBUG msg="foo/bar: with values, verbosity and name" x=1 y=2 str=abc
+}
+
+func ExampleToSlog() {
+	logger := logr.ToSlog(funcr.New(func(prefix, args string) {
+		if prefix != "" {
+			fmt.Fprintln(os.Stdout, prefix, args)
+		} else {
+			fmt.Fprintln(os.Stdout, args)
+		}
+	}, funcr.Options{}))
+
+	logger.Info("hello world")
+	logger.Error("ignore me", "err", errors.New("fake error"))
+	logger.With("x", 1, "y", 2).WithGroup("group").With("str", "abc").Warn("with values and group")
+
+	// Output:
+	// "level"=0 "msg"="hello world"
+	// "msg"="ignore me" "error"=null "err"="fake error"
+	// "level"=0 "msg"="with values and group" "x"=1 "y"=2 "group.str"="abc"
+}

sloghandler.go

@@ -0,0 +1,71 @@
+//go:build go1.21
+// +build go1.21
+
+/*
+Copyright 2023 The logr Authors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package logr
+
+import (
+	"context"
+	"log/slog"
+)
+
+type slogHandler struct {
+	sink        LogSink
+	groupPrefix string
+}
+
+func (l *slogHandler) Enabled(ctx context.Context, level slog.Level) bool {
+	return l.sink.Enabled(levelFromSlog(level))
+}
+
+func (l *slogHandler) Handle(ctx context.Context, record slog.Record) error {
+	kvList := make([]any, 0, 2*record.NumAttrs())
+	record.Attrs(func(attr slog.Attr) bool {
+		kvList = append(kvList, appendPrefix(l.groupPrefix, attr.Key), attr.Value.Any())
+		return true
+	})
+	if record.Level >= slog.LevelError {
+		l.sink.Error(nil, record.Message, kvList...)
+	} else {
+		l.sink.Info(levelFromSlog(record.Level), record.Message, kvList...)
+	}
+	return nil
+}
+
+func (l slogHandler) WithAttrs(attrs []slog.Attr) slog.Handler {
+	kvList := make([]any, 0, 2*len(attrs))
+	for _, attr := range attrs {
+		kvList = append(kvList, appendPrefix(l.groupPrefix, attr.Key), attr.Value.Any())
+	}
+	l.sink = l.sink.WithValues(kvList...)
+	return &l
+}
+
+func (l slogHandler) WithGroup(name string) slog.Handler {
+	l.groupPrefix = appendPrefix(l.groupPrefix, name)
+	return &l
+}
+
+func appendPrefix(prefix, name string) string {
+	if prefix == "" {
+		return name
+	}
+	return prefix + "." + name
+}
+
+var _ slog.Handler = &slogHandler{}