std/log/slog

import "github.com/eugenioenko/goalchemy/std/log/slog"

Package slog provides structured logging with Go’s log/slog API. Records from the default logger and from NewHostHandler go to a sink the host application installs, rendered like slog.TextHandler without the time; without a sink, records at LevelWarn and above are written to standard error. Values are rendered through std/fmt, source locations are not recorded, and there is no TextHandler or JSONHandler.

const (
  TimeKey    = "time"
  LevelKey   = "level"
  MessageKey = "msg"
  SourceKey  = "source"
)

Keys for the built-in attributes.

Debug

func Debug(msg string, args ...any)

Debug calls Logger.Debug on the default logger.

DebugContext

func DebugContext(ctx context.Context, msg string, args ...any)

DebugContext calls Logger.DebugContext on the default logger.

Error

func Error(msg string, args ...any)

Error calls Logger.Error on the default logger.

ErrorContext

func ErrorContext(ctx context.Context, msg string, args ...any)

ErrorContext calls Logger.ErrorContext on the default logger.

Info

func Info(msg string, args ...any)

Info calls Logger.Info on the default logger.

InfoContext

func InfoContext(ctx context.Context, msg string, args ...any)

InfoContext calls Logger.InfoContext on the default logger.

Log

func Log(ctx context.Context, level Level, msg string, args ...any)

Log calls Logger.Log on the default logger.

LogAttrs

func LogAttrs(ctx context.Context, level Level, msg string, attrs ...Attr)

LogAttrs calls Logger.LogAttrs on the default logger.

SetDefault

func SetDefault(l *Logger)

SetDefault makes l the default Logger.

Warn

func Warn(msg string, args ...any)

Warn calls Logger.Warn on the default logger.

WarnContext

func WarnContext(ctx context.Context, msg string, args ...any)

WarnContext calls Logger.WarnContext on the default logger.

type Attr

type Attr struct {
  Key   string
  Value Value
}

An Attr is a key-value pair.

Any

func Any(key string, value any) Attr

Any returns an Attr for value, as AnyValue converts it.

Bool

func Bool(key string, v bool) Attr

Bool returns an Attr for a bool.

Duration

func Duration(key string, v time.Duration) Attr

Duration returns an Attr for a time.Duration.

Float64

func Float64(key string, v float64) Attr

Float64 returns an Attr for a float64.

Group

func Group(key string, args ...any) Attr

Group returns an Attr for a group of attributes built from alternating keys and values, as in Logger.Log.

GroupAttrs

func GroupAttrs(key string, attrs ...Attr) Attr

GroupAttrs returns an Attr for a group of attrs.

Int

func Int(key string, value int) Attr

Int returns an Attr for an int, stored as an int64.

Int64

func Int64(key string, value int64) Attr

Int64 returns an Attr for an int64.

String

func String(key, value string) Attr

String returns an Attr for a string value.

Time

func Time(key string, v time.Time) Attr

Time returns an Attr for a time.Time.

Uint64

func Uint64(key string, v uint64) Attr

Uint64 returns an Attr for a uint64.

Attr.Equal

func (a Attr) Equal(b Attr) bool

Equal reports whether a and b have equal keys and values.

Attr.String

func (a Attr) String() string

String returns key=value.

type Handler

type Handler interface {
  Enabled(context.Context, Level) bool
  Handle(context.Context, Record) error
  WithAttrs(attrs []Attr) Handler
  WithGroup(name string) Handler
}

A Handler handles log records produced by a Logger.

var DiscardHandler Handler = discardHandler{}

DiscardHandler discards all log output.

type HandlerOptions

type HandlerOptions struct {
  // AddSource is ignored: source locations are not recorded.
  AddSource bool
  // Level is the minimum level to handle. If nil, the host application's
  // minimum level alone decides.
  Level Leveler
  // ReplaceAttr is called to rewrite each non-group attribute before it is
  // rendered, as in log/slog.
  ReplaceAttr func(groups []string, a Attr) Attr
}

HandlerOptions are options for the host handler.

type HostHandler

type HostHandler struct {
}

HostHandler sends records to the host application’s log sink. It renders attributes like log/slog’s TextHandler: group names prefix keys with “.”, and the sink receives the key/value pairs and the rendered line, which omits the time.

NewHostHandler

func NewHostHandler(opts *HandlerOptions) *HostHandler

NewHostHandler creates a HostHandler with opts, or with default options if opts is nil.

HostHandler.Enabled

func (h *HostHandler) Enabled(_ context.Context, level Level) bool

Enabled reports whether both the handler’s level and the host sink accept level.

HostHandler.Handle

func (h *HostHandler) Handle(_ context.Context, r Record) error

Handle renders r and sends it to the host sink.

HostHandler.WithAttrs

func (h *HostHandler) WithAttrs(attrs []Attr) Handler

WithAttrs returns a HostHandler whose records include attrs.

HostHandler.WithGroup

func (h *HostHandler) WithGroup(name string) Handler

WithGroup returns a HostHandler that qualifies later keys with name.

type Kind

type Kind int

Kind is the kind of a Value.

const (
  KindAny Kind = iota
  KindBool
  KindDuration
  KindFloat64
  KindInt64
  KindString
  KindTime
  KindUint64
  KindGroup
  KindLogValuer
)

The kinds of Values.

Kind.String

func (k Kind) String() string

type Level

type Level int

A Level is the importance or severity of a log event.

const (
  LevelDebug Level = -4
  LevelInfo  Level = 0
  LevelWarn  Level = 4
  LevelError Level = 8
)

Names for common levels.

Level.AppendText

func (l Level) AppendText(b []byte) ([]byte, error)

AppendText appends the level’s name to b.

Level.Level

func (l Level) Level() Level

Level returns l, so a Level is a Leveler.

Level.MarshalText

func (l Level) MarshalText() ([]byte, error)

MarshalText returns the level’s name.

Level.String

func (l Level) String() string

String returns a name for the level, such as “WARN” or “INFO+2”.

Level.UnmarshalText

func (l *Level) UnmarshalText(data []byte) error

UnmarshalText parses a level name produced by String, ignoring case.

type LevelVar

type LevelVar struct {
}

A LevelVar is a Level variable that can change while handlers use it.

LevelVar.Level

func (v *LevelVar) Level() Level

Level returns v’s level.

LevelVar.MarshalText

func (v *LevelVar) MarshalText() ([]byte, error)

MarshalText returns the name of v’s level.

LevelVar.Set

func (v *LevelVar) Set(l Level)

Set sets v’s level to l.

LevelVar.String

func (v *LevelVar) String() string

String returns “LevelVar(” + the level name + “)”.

LevelVar.UnmarshalText

func (v *LevelVar) UnmarshalText(data []byte) error

UnmarshalText sets v’s level from a level name.

type Leveler

type Leveler interface {
  Level() Level
}

A Leveler provides a Level value.

type LogValuer

type LogValuer interface {
  LogValue() Value
}

A LogValuer is any Go value that can convert itself into a Value for logging.

type Logger

type Logger struct {
}

A Logger records structured information about each call to its Log, Debug, Info, Warn and Error methods and passes it to a Handler.

Default

func Default() *Logger

Default returns the default Logger, which sends records to the host application’s log sink.

New

func New(h Handler) *Logger

New creates a new Logger with the given non-nil Handler.

With

func With(args ...any) *Logger

With calls Logger.With on the default logger.

Logger.Debug

func (l *Logger) Debug(msg string, args ...any)

Debug logs at LevelDebug.

Logger.DebugContext

func (l *Logger) DebugContext(ctx context.Context, msg string, args ...any)

DebugContext logs at LevelDebug with the given context.

Logger.Enabled

func (l *Logger) Enabled(ctx context.Context, level Level) bool

Enabled reports whether l emits log records at the given level.

Logger.Error

func (l *Logger) Error(msg string, args ...any)

Error logs at LevelError.

Logger.ErrorContext

func (l *Logger) ErrorContext(ctx context.Context, msg string, args ...any)

ErrorContext logs at LevelError with the given context.

Logger.Handler

func (l *Logger) Handler() Handler

Handler returns l’s Handler.

Logger.Info

func (l *Logger) Info(msg string, args ...any)

Info logs at LevelInfo.

Logger.InfoContext

func (l *Logger) InfoContext(ctx context.Context, msg string, args ...any)

InfoContext logs at LevelInfo with the given context.

Logger.Log

func (l *Logger) Log(ctx context.Context, level Level, msg string, args ...any)

Log emits a log record with the current time and the given level and message. args are alternating keys and values, or Attrs.

Logger.LogAttrs

func (l *Logger) LogAttrs(ctx context.Context, level Level, msg string, attrs ...Attr)

LogAttrs is a more efficient version of Logger.Log that accepts only Attrs.

Logger.Warn

func (l *Logger) Warn(msg string, args ...any)

Warn logs at LevelWarn.

Logger.WarnContext

func (l *Logger) WarnContext(ctx context.Context, msg string, args ...any)

WarnContext logs at LevelWarn with the given context.

Logger.With

func (l *Logger) With(args ...any) *Logger

With returns a Logger that includes the given attributes in each output.

Logger.WithGroup

func (l *Logger) WithGroup(name string) *Logger

WithGroup returns a Logger that starts a group, if name is non-empty.

type Record

type Record struct {
  // Time is when the record was created; the zero time is omitted.
  Time time.Time
  // Message is the log message.
  Message string
  // Level is the level of the event.
  Level Level
  // PC is always zero: source locations are not recorded.
  PC int
  // contains filtered or unexported fields
}

A Record holds information about a log event.

NewRecord

func NewRecord(t time.Time, level Level, msg string, pc int) Record

NewRecord creates a Record from the given arguments. Use Record.AddAttrs to add attributes. pc is kept for source compatibility and is ignored.

Record.Add

func (r *Record) Add(args ...any)

Add converts args to Attrs as Logger.Log does and appends them to the Record’s list, omitting empty groups.

Record.AddAttrs

func (r *Record) AddAttrs(attrs ...Attr)

AddAttrs appends the given Attrs to the Record’s list, omitting empty groups.

Record.Attrs

func (r Record) Attrs(f func(Attr) bool)

Attrs calls f on each Attr in the Record. Iteration stops if f returns false.

Record.Clone

func (r Record) Clone() Record

Clone returns a copy of the record whose attributes are not shared.

Record.NumAttrs

func (r Record) NumAttrs() int

NumAttrs returns the number of attributes in the Record.

type Value

type Value struct {
}

A Value can represent any Go value without allocating for the common kinds.

AnyValue

func AnyValue(v any) Value

AnyValue returns a Value for v, using the kind that matches v’s type.

BoolValue

func BoolValue(v bool) Value

BoolValue returns a Value for a bool.

DurationValue

func DurationValue(v time.Duration) Value

DurationValue returns a Value for a time.Duration.

Float64Value

func Float64Value(v float64) Value

Float64Value returns a Value for a floating-point number.

GroupValue

func GroupValue(as ...Attr) Value

GroupValue returns a new Value for a list of Attrs, omitting empty groups.

Int64Value

func Int64Value(v int64) Value

Int64Value returns a Value for an int64.

IntValue

func IntValue(v int) Value

IntValue returns a Value for an int.

StringValue

func StringValue(value string) Value

StringValue returns a Value for a string.

TimeValue

func TimeValue(v time.Time) Value

TimeValue returns a Value for a time.Time.

Uint64Value

func Uint64Value(v uint64) Value

Uint64Value returns a Value for a uint64.

Value.Any

func (v Value) Any() any

Any returns v’s value as an any.

Value.Bool

func (v Value) Bool() bool

Bool returns v’s value as a bool. It panics if v is not a bool.

Value.Duration

func (v Value) Duration() time.Duration

Duration returns v’s value as a time.Duration. It panics if v is not a time.Duration.

Value.Equal

func (v Value) Equal(w Value) bool

Equal reports whether v and w represent the same Go value.

Value.Float64

func (v Value) Float64() float64

Float64 returns v’s value as a float64. It panics if v is not a float64.

Value.Group

func (v Value) Group() []Attr

Group returns v’s value as a []Attr. It panics if v’s Kind is not KindGroup.

Value.Int64

func (v Value) Int64() int64

Int64 returns v’s value as an int64. It panics if v is not a signed integer.

Value.Kind

func (v Value) Kind() Kind

Kind returns v’s Kind.

Value.LogValuer

func (v Value) LogValuer() LogValuer

LogValuer returns v’s value as a LogValuer. It panics if v is not a LogValuer.

Value.Resolve

func (v Value) Resolve() (rv Value)

Resolve repeatedly calls LogValue on v while it implements LogValuer, and returns the result. A LogValue panic resolves to an error value.

Value.String

func (v Value) String() string

String returns v’s value as a string, formatted like fmt.Sprint.

Value.Time

func (v Value) Time() time.Time

Time returns v’s value as a time.Time. It panics if v is not a time.Time.

Value.Uint64

func (v Value) Uint64() uint64

Uint64 returns v’s value as a uint64. It panics if v is not an unsigned integer.