log

package
v0.21.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 31, 2026 License: BSD-3-Clause Imports: 13 Imported by: 0

Documentation

Overview

Package log provides access to log/slog structured logging with opinionated defaults and integration with flags.

The Logger is a context service, which works like the codec provider in the marshal extension: it has a default action, accumulates Option values which initialize it, and is added to and retrieved from the context. Unlike that provider, loggers are named, which allows an app to provide more than one. The default logger has the empty string as its name and is retrieved with FromContext(ctx, "").

The log functions in this package delegate to the default logger. Those which take a context obtain it from the context; those which don't bridge to the current app in order to find it. When there is no default logger, they fall back to the slog default.

Index

Constants

View Source 
const (
	LevelDebug = slog.LevelDebug
	LevelInfo  = slog.LevelInfo
	LevelWarn  = slog.LevelWarn
	LevelError = slog.LevelError
)

The names of the commonly used levels

Variables

This section is empty.

Functions

func ContextValue added in v0.20.0 

func ContextValue(l *Logger) cli.Action

ContextValue provides an action that registers the given logger with its name and sets it into the context.

func Debug 

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

Debug logs a message with the given arguments at the Debug level

func DebugContext 

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

DebugContext logs a message with the given arguments at the Debug level, using the specified context

func Error 

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

Error logs a message with the given arguments at the Error level

func ErrorContext 

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

ErrorContext logs a message with the given arguments at the Error level, using the specified context

func FlagsAndArgs added in v0.20.0 

func FlagsAndArgs() cli.Action

FlagsAndArgs is an action which provides the default flags for the default logger to the application. Despite its name, which is conventional, this action provides no args.

func Info 

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

Info logs a message with the given arguments at the Info level

func InfoContext 

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

InfoContext logs a message with the given arguments at the Info level, using the specified context

func Log 

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

Log logs a message with the given arguments at the specified level

func LogAttrs 

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

LogAttrs logs a message with the given arguments at the specified level

func SetAddSource added in v0.20.0 

func SetAddSource(name string, v ...bool) cli.Action

SetAddSource causes the logger named by name to include the source position of log statements and provides reasonable defaults for initializing a flag.

func SetLevel added in v0.20.0 

func SetLevel(name string, v ...Level) cli.Action

SetLevel sets the minimum level of the logger named by name and provides reasonable defaults for initializing a flag.

func SetLogFormat added in v0.20.0 

func SetLogFormat(name string, v ...LogFormat) cli.Action

SetLogFormat sets the format of the logger named by name and provides reasonable defaults for initializing a flag.

func Warn 

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

Warn logs a message with the given arguments at the Warn level

func WarnContext 

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

WarnContext logs a message with the given arguments at the Warn level, using the specified context

func With 

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

With returns a derived logger with attributes already set

Types

type ContextServices added in v0.20.0 

type ContextServices struct {
	// contains filtered or unexported fields
}

ContextServices provides an adapter around the context which tracks the loggers that have been registered with the app. Each app gets its own instance, which is initialized with the app.

func Services added in v0.20.0 

func Services(c context.Context) *ContextServices

Services gets the context services for working with loggers. This function panics if the context does not contain context services, which are initialized with the app

func (*ContextServices) Lookup added in v0.20.0 

func (c *ContextServices) Lookup(name string) (*Logger, bool)

Lookup obtains the logger which was registered with the given name, if any. The default logger is registered with the empty string as its name.

func (*ContextServices) Register added in v0.20.0 

func (c *ContextServices) Register(l *Logger)

Register adds the logger to the services using its name. Any logger which was previously registered with the same name is replaced.

type Level 

type Level = slog.Level

Level is the severity of a log message

type LogFormat added in v0.20.0 

type LogFormat int

LogFormat names the log/slog handler which backs a Logger. 

const (
	// TextFormat writes logs using [slog.TextHandler].  This is the default.
	TextFormat LogFormat = iota

	// JSONFormat writes logs using [slog.JSONHandler].
	JSONFormat
)

The available formats for log output

func (LogFormat) MarshalText added in v0.20.0 

func (f LogFormat) MarshalText() ([]byte, error)

MarshalText provides the textual representation

func (LogFormat) NewHandler added in v0.20.0 

func (f LogFormat) NewHandler(w io.Writer, opts *slog.HandlerOptions) slog.Handler

NewHandler creates the handler which corresponds to the format

func (LogFormat) String added in v0.20.0 

func (f LogFormat) String() string

String provides the name of the format

func (*LogFormat) UnmarshalText added in v0.20.0 

func (f *LogFormat) UnmarshalText(b []byte) error

UnmarshalText converts the textual representation

type Logger added in v0.20.0 

type Logger struct {
	// Action specifies the action which defines the action to run when this value
	// is added to a pipeline. Typically, this is an initializer set via WithDefaultAction
	cli.Action
	// contains filtered or unexported fields
}

Logger provides a named logger, typically retrieved from the context. A logger delegates to log/slog, creating the handler on demand from the options which have been applied to it.

The default logger is named with the empty string. It is the logger that the log functions in this package delegate to and the only one which obtains flags from FlagsAndArgs.

func FromContext added in v0.20.0 

func FromContext(ctx context.Context, name string) *Logger

FromContext retrieves the logger with the given name from the context. The default logger has the empty string as its name. This function panics if the logger is not present in the context.

func New added in v0.20.0 

func New(opts ...Option) *Logger

New creates a new logger. By default, adding the Logger to the pipeline registers it with its name and in the context, which is required for most use cases, and, for the default logger, adds flags.

func (*Logger) Apply added in v0.20.0 

func (l *Logger) Apply(opts ...Option)

Apply will apply the given options to the logger

func (*Logger) Debug added in v0.20.0 

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

Debug logs a message with the given arguments at the Debug level

func (*Logger) DebugContext added in v0.20.0 

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

DebugContext logs a message with the given arguments at the Debug level, using the specified context

func (*Logger) Error added in v0.20.0 

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

Error logs a message with the given arguments at the Error level

func (*Logger) ErrorContext added in v0.20.0 

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

ErrorContext logs a message with the given arguments at the Error level, using the specified context

func (*Logger) Info added in v0.20.0 

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

Info logs a message with the given arguments at the Info level

func (*Logger) InfoContext added in v0.20.0 

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

InfoContext logs a message with the given arguments at the Info level, using the specified context

func (*Logger) Log added in v0.20.0 

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

Log logs a message with the given arguments at the specified level

func (*Logger) LogAttrs added in v0.20.0 

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

LogAttrs logs a message with the given attributes at the specified level

func (*Logger) Logger added in v0.20.0 

func (l *Logger) Logger() *slog.Logger

Logger obtains the underlying logger, which is created on demand from the options which have been applied. As a special case, the slog default is used when the receiver is nil.

func (*Logger) Name added in v0.20.0 

func (l *Logger) Name() string

Name obtains the name of the logger. The default logger has the empty string as its name.

func (*Logger) Pipeline added in v0.20.0 

func (l *Logger) Pipeline() cli.Action

Pipeline retrieves the logger's action as a pipeline

func (*Logger) Warn added in v0.20.0 

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

Warn logs a message with the given arguments at the Warn level

func (*Logger) WarnContext added in v0.20.0 

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

WarnContext logs a message with the given arguments at the Warn level, using the specified context

func (*Logger) With added in v0.20.0 

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

With returns a derived logger with attributes already set

type Option added in v0.20.0 

type Option interface {
	cli.Action
	// contains filtered or unexported methods
}

Option defines an option for initialization of a Logger. An option is also an action, which applies it to the logger it names within the context.

func WithAction added in v0.20.0 

func WithAction(v cli.Action) Option

WithAction sets the Action to use

func WithAddSource added in v0.20.0 

func WithAddSource(v bool) Option

WithAddSource sets whether the handler computes the source file and line of the log statement, corresponding to slog.HandlerOptions.AddSource.

func WithDefaultAction added in v0.20.0 

func WithDefaultAction() Option

WithDefaultAction sets the default action, which registers the logger with its name and in the context, and, if it is the default logger, also adds the flags from FlagsAndArgs.

func WithLevel added in v0.20.0 

func WithLevel(v Level) Option

WithLevel sets the minimum level of the messages which are logged, corresponding to slog.HandlerOptions.Level.

func WithLogFormat added in v0.20.0 

func WithLogFormat(v LogFormat) Option

WithLogFormat sets the format of the log output, which determines the handler that the logger uses.

func WithName added in v0.20.0 

func WithName(name string) Option

WithName names the logger. The default logger has the empty string as its name. This option is meant for use with New; renaming a logger which has already been registered doesn't change its registration.

func WithOutput added in v0.20.0 

func WithOutput(w io.Writer) Option

WithOutput sets the writer that the logger writes to. By default, this is the Stderr of the app.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.