README
¶
slog shim
Go 1.21 introduced a new structured logging package, log/slog, to the standard library.
Although it's been eagerly anticipated by many, widespread adoption isn't expected to occur immediately,
especially since updating to Go 1.21 is a decision that most libraries won't make overnight.
Before this package was added to the standard library, there was an experimental version available at golang.org/x/exp/slog.
While it's generally advised against using experimental packages in production,
this one served as a sort of backport package for the last few years,
incorporating new features before they were added to the standard library (like slices, maps or errors).
This package serves as a bridge, helping libraries integrate slog in a backward-compatible way without having to immediately update their Go version requirement to 1.21. On Go 1.21 (and above), it acts as a drop-in replacement for log/slog, while below 1.21 it falls back to golang.org/x/exp/slog.
How does it achieve backwards compatibility?
Although there's no consensus on whether dropping support for older Go versions is considered backward compatible, a majority seems to believe it is. (I don't have scientific proof for this, but it's based on conversations with various individuals across different channels.)
This package adheres to that interpretation of backward compatibility. On Go 1.21, the shim uses type aliases to offer the same API as slog/log.
Once a library upgrades its version requirement to Go 1.21, it should be able to discard this shim and use log/slog directly.
For older Go versions, the library might become unstable after removing the shim. However, since those older versions are no longer supported, the promise of backward compatibility remains intact.
Installation
go get github.com/sagikazarmark/slog-shim
Usage
Import this package into your library and use it in your public API:
package mylib
import slog "github.com/sagikazarmark/slog-shim"
func New(logger *slog.Logger) MyLib {
// ...
}
When using the library, clients can either use log/slog (when on Go 1.21) or golang.org/x/exp/slog (below Go 1.21):
package main
import "log/slog"
// OR
import "golang.org/x/exp/slog"
mylib.New(slog.Default())
Make sure consumers are aware that your API behaves differently on different Go versions.
Once you bump your Go version requirement to Go 1.21, you can drop the shim entirely from your code:
package mylib
- import slog "github.com/sagikazarmark/slog-shim"
+ import "log/slog"
func New(logger *slog.Logger) MyLib {
// ...
}
License
The project is licensed under a BSD-style license.
Documentation
¶
Index ¶
- Constants
- func Debug(msg string, args ...any)
- func DebugContext(ctx context.Context, msg string, args ...any)
- func Error(msg string, args ...any)
- func ErrorContext(ctx context.Context, msg string, args ...any)
- func Info(msg string, args ...any)
- func InfoContext(ctx context.Context, msg string, args ...any)
- func Log(ctx context.Context, level Level, msg string, args ...any)
- func LogAttrs(ctx context.Context, level Level, msg string, attrs ...Attr)
- func NewLogLogger(h Handler, level Level) *log.Logger
- func SetDefault(l *Logger)
- func Warn(msg string, args ...any)
- func WarnContext(ctx context.Context, msg string, args ...any)
- type Attr
- func Any(key string, value any) Attr
- func Bool(key string, v bool) Attr
- func Duration(key string, v time.Duration) Attr
- func Float64(key string, v float64) Attr
- func Group(key string, args ...any) Attr
- func Int(key string, value int) Attr
- func Int64(key string, value int64) Attr
- func String(key, value string) Attr
- func Time(key string, v time.Time) Attr
- func Uint64(key string, v uint64) Attr
- type Handler
- type HandlerOptions
- type JSONHandler
- type Kind
- type Level
- type LevelVar
- type Leveler
- type LogValuer
- type Logger
- type Record
- type Source
- type TextHandler
- type Value
- func AnyValue(v any) Value
- func BoolValue(v bool) Value
- func DurationValue(v time.Duration) Value
- func Float64Value(v float64) Value
- func GroupValue(as ...Attr) Value
- func Int64Value(v int64) Value
- func IntValue(v int) Value
- func StringValue(value string) Value
- func TimeValue(v time.Time) Value
- func Uint64Value(v uint64) Value
Constants ¶
const ( // TimeKey is the key used by the built-in handlers for the time // when the log method is called. The associated Value is a [time.Time]. TimeKey = slog.TimeKey // LevelKey is the key used by the built-in handlers for the level // of the log call. The associated value is a [Level]. LevelKey = slog.LevelKey // MessageKey is the key used by the built-in handlers for the // message of the log call. The associated value is a string. MessageKey = slog.MessageKey // SourceKey is the key used by the built-in handlers for the source file // and line of the log call. The associated value is a string. SourceKey = slog.SourceKey )
Keys for "built-in" attributes.
const ( KindAny = slog.KindAny KindBool = slog.KindBool KindDuration = slog.KindDuration KindFloat64 = slog.KindFloat64 KindInt64 = slog.KindInt64 KindString = slog.KindString KindTime = slog.KindTime KindUint64 = slog.KindUint64 KindGroup = slog.KindGroup KindLogValuer = slog.KindLogValuer )
The following list is sorted alphabetically, but it's also important that KindAny is 0 so that a zero Value represents nil.
Variables ¶
This section is empty.
Functions ¶
func DebugContext ¶
DebugContext calls Logger.DebugContext on the default logger.
func ErrorContext ¶
ErrorContext calls Logger.ErrorContext on the default logger.
func InfoContext ¶
InfoContext calls Logger.InfoContext on the default logger.
func NewLogLogger ¶
NewLogLogger returns a new log.Logger such that each call to its Output method dispatches a Record to the specified handler. The logger acts as a bridge from the older log API to newer structured logging handlers.
func SetDefault ¶
func SetDefault(l *Logger)
SetDefault makes l the default Logger. After this call, output from the log package's default Logger (as with log.Print, etc.) will be logged at LevelInfo using l's Handler.
Types ¶
type Attr ¶
An Attr is a key-value pair.
func Any ¶
Any returns an Attr for the supplied value. See [Value.AnyValue] for how values are treated.
func Group ¶
Group returns an Attr for a Group Value. The first argument is the key; the remaining arguments are converted to Attrs as in [Logger.Log].
Use Group to collect several key-value pairs under a single key on a log line, or as the result of LogValue in order to log a single value as multiple Attrs.
type Handler ¶
A Handler handles log records produced by a Logger..
A typical handler may print log records to standard error, or write them to a file or database, or perhaps augment them with additional attributes and pass them on to another handler.
Any of the Handler's methods may be called concurrently with itself or with other methods. It is the responsibility of the Handler to manage this concurrency.
Users of the slog package should not invoke Handler methods directly. They should use the methods of Logger instead.
type HandlerOptions ¶
type HandlerOptions = slog.HandlerOptions
HandlerOptions are options for a TextHandler or JSONHandler. A zero HandlerOptions consists entirely of default values.
type JSONHandler ¶
type JSONHandler = slog.JSONHandler
JSONHandler is a Handler that writes Records to an io.Writer as line-delimited JSON objects.
func NewJSONHandler ¶
func NewJSONHandler(w io.Writer, opts *HandlerOptions) *JSONHandler
NewJSONHandler creates a JSONHandler that writes to w, using the given options. If opts is nil, the default options are used.
type Level ¶
A Level is the importance or severity of a log event. The higher the level, the more important or severe the event.
const ( LevelDebug Level = slog.LevelDebug LevelInfo Level = slog.LevelInfo LevelWarn Level = slog.LevelWarn LevelError Level = slog.LevelError )
Level numbers are inherently arbitrary, but we picked them to satisfy three constraints. Any system can map them to another numbering scheme if it wishes.
First, we wanted the default level to be Info, Since Levels are ints, Info is the default value for int, zero.
Second, we wanted to make it easy to use levels to specify logger verbosity. Since a larger level means a more severe event, a logger that accepts events with smaller (or more negative) level means a more verbose logger. Logger verbosity is thus the negation of event severity, and the default verbosity of 0 accepts all events at least as severe as INFO.
Third, we wanted some room between levels to accommodate schemes with named levels between ours. For example, Google Cloud Logging defines a Notice level between Info and Warn. Since there are only a few of these intermediate levels, the gap between the numbers need not be large. Our gap of 4 matches OpenTelemetry's mapping. Subtracting 9 from an OpenTelemetry level in the DEBUG, INFO, WARN and ERROR ranges converts it to the corresponding slog Level range. OpenTelemetry also has the names TRACE and FATAL, which slog does not. But those OpenTelemetry levels can still be represented as slog Levels by using the appropriate integers.
Names for common levels.
type LevelVar ¶
A LevelVar is a Level variable, to allow a Handler level to change dynamically. It implements Leveler as well as a Set method, and it is safe for use by multiple goroutines. The zero LevelVar corresponds to LevelInfo.
type Leveler ¶
A Leveler provides a Level value.
As Level itself implements Leveler, clients typically supply a Level value wherever a Leveler is needed, such as in HandlerOptions. Clients who need to vary the level dynamically can provide a more complex Leveler implementation such as *LevelVar.
type LogValuer ¶
A LogValuer is any Go value that can convert itself into a Value for logging.
This mechanism may be used to defer expensive operations until they are needed, or to expand a single value into a sequence of components.
type Logger ¶
A Logger records structured information about each call to its Log, Debug, Info, Warn, and Error methods. For each call, it creates a Record and passes it to a Handler.
To create a new Logger, call New or a Logger method that begins "With".
type Record ¶
A Record holds information about a log event. Copies of a Record share state. Do not modify a Record after handing out a copy to it. Call NewRecord to create a new Record. Use [Record.Clone] to create a copy with no shared state.
type TextHandler ¶
type TextHandler = slog.TextHandler
TextHandler is a Handler that writes Records to an io.Writer as a sequence of key=value pairs separated by spaces and followed by a newline.
func NewTextHandler ¶
func NewTextHandler(w io.Writer, opts *HandlerOptions) *TextHandler
NewTextHandler creates a TextHandler that writes to w, using the given options. If opts is nil, the default options are used.
type Value ¶
A Value can represent any Go value, but unlike type any, it can represent most small values without an allocation. The zero Value corresponds to nil.
func AnyValue ¶
AnyValue returns a Value for the supplied value.
If the supplied value is of type Value, it is returned unmodified.
Given a value of one of Go's predeclared string, bool, or (non-complex) numeric types, AnyValue returns a Value of kind String, Bool, Uint64, Int64, or Float64. The width of the original numeric type is not preserved.
Given a time.Time or time.Duration value, AnyValue returns a Value of kind KindTime or KindDuration. The monotonic time is not preserved.
For nil, or values of all other types, including named types whose underlying type is numeric, AnyValue returns a value of kind KindAny.
func DurationValue ¶
DurationValue returns a Value for a time.Duration.
func Float64Value ¶
Float64Value returns a Value for a floating-point number.
func GroupValue ¶
GroupValue returns a new Value for a list of Attrs. The caller must not subsequently mutate the argument slice.
func StringValue ¶
StringValue returns a new Value for a string.
Source Files