README
¶
slogx 
Module slogx provides extensions and helpers for the log/slog package.
Packages
Package slogx
Package slogx provides Logger as an alternative to slog.Logger, which focuses on performance and makes several design changes to improve it:
- It does not provide convenience methods for attributes that may affect performance. All methods accept attributes only as slog.Attr.
- It provides an option to disable the inclusion of source information in the log Record. This can improve performance by up to 100% in cases where the source information is not included by the Handler anyway.
- Its With method does not immediately call the handler's WithAttrs method, instead it buffers up to 4 attributes which are then added to each log Record. This improves performance when you need to define a temporary set of attributes in a function and log a few messages with those attributes a few times. It also greatly improves performance when the logger is disabled. This is because calling WithAttrs is quite an expensive operation, especially if the Handler is wrapped multiple times. That is, each layer will call the underlying handler's WithAttrs method and cause a lot of allocations. But what if the message is discarded because the logger is disabled? Yes, it will be a waste of CPU time. So for temporary With attribute sets, it is usually more efficient to keep them on the Logger. If any of the WithGroup, Handler, or LongTerm methods are called later, the temporary attributes will be flushed using the WithAttrs method.
- It provides the WithLongTerm method, which acts as a sequence of With and LongTerm method calls and is needed for cases where the resulting logger is intended to be reused multiple times and may reside in a rather long-lived context.
Performance
- See benchmark results for details.
Documentation
¶
Overview ¶
Package slogx provides extensions to the slog package. It focuses on performance and simplicity. Only functions working with slog.Attr are provided. Any slower alternatives are not supported.
Index ¶
- Constants
- func Debug(msg string, attrs ...slog.Attr)
- func Discard() slog.Handler
- func Error(msg string, attrs ...slog.Attr)
- func ErrorAttr(err error) slog.Attr
- func Info(msg string, attrs ...slog.Attr)
- func Join(handlers ...slog.Handler) slog.Handler
- func Log(level slog.Level, msg string, attrs ...slog.Attr)
- func Warn(msg string, attrs ...slog.Attr)
- type AttrPack
- type ContextLogger
- func (l *ContextLogger) Debug(ctx context.Context, msg string, attrs ...slog.Attr)
- func (l *ContextLogger) Enabled(ctx context.Context, level slog.Level) bool
- func (l *ContextLogger) Error(ctx context.Context, msg string, attrs ...slog.Attr)
- func (l *ContextLogger) Handler() slog.Handler
- func (l *ContextLogger) Info(ctx context.Context, msg string, attrs ...slog.Attr)
- func (l *ContextLogger) Log(ctx context.Context, level slog.Level, msg string, attrs ...slog.Attr)
- func (l *ContextLogger) LogAttrs(ctx context.Context, level slog.Level, msg string, attrs ...slog.Attr)
- func (l *ContextLogger) LogWithCallerSkip(ctx context.Context, skip int, level slog.Level, msg string, ...)
- func (l *ContextLogger) Logger() *Logger
- func (l *ContextLogger) LongTerm() *ContextLogger
- func (l *ContextLogger) SlogLogger() *slog.Logger
- func (l *ContextLogger) Warn(ctx context.Context, msg string, attrs ...slog.Attr)
- func (l *ContextLogger) With(attrs ...slog.Attr) *ContextLogger
- func (l *ContextLogger) WithGroup(group string) *ContextLogger
- func (l *ContextLogger) WithLongTerm(attrs ...slog.Attr) *ContextLogger
- func (l *ContextLogger) WithSource(enabled bool) *ContextLogger
- type Logger
- func (l *Logger) ContextLogger() *ContextLogger
- func (l *Logger) Debug(msg string, attrs ...slog.Attr)
- func (l *Logger) DebugContext(ctx context.Context, msg string, attrs ...slog.Attr)
- func (l *Logger) Enabled(ctx context.Context, level slog.Level) bool
- func (l *Logger) Error(msg string, attrs ...slog.Attr)
- func (l *Logger) ErrorContext(ctx context.Context, msg string, attrs ...slog.Attr)
- func (l *Logger) Handler() slog.Handler
- func (l *Logger) Info(msg string, attrs ...slog.Attr)
- func (l *Logger) InfoContext(ctx context.Context, msg string, attrs ...slog.Attr)
- func (l *Logger) Log(level slog.Level, msg string, attrs ...slog.Attr)
- func (l *Logger) LogAttrs(ctx context.Context, level slog.Level, msg string, attrs ...slog.Attr)
- func (l *Logger) LogContext(ctx context.Context, level slog.Level, msg string, attrs ...slog.Attr)
- func (l *Logger) LongTerm() *Logger
- func (l *Logger) SlogLogger() *slog.Logger
- func (l *Logger) Warn(msg string, attrs ...slog.Attr)
- func (l *Logger) WarnContext(ctx context.Context, msg string, attrs ...slog.Attr)
- func (l *Logger) With(attrs ...slog.Attr) *Logger
- func (l *Logger) WithGroup(group string) *Logger
- func (l *Logger) WithLongTerm(attrs ...slog.Attr) *Logger
- func (l *Logger) WithSource(enabled bool) *Logger
- type TweakHandlerBuilder
Constants ¶
const (
// ErrorKey is the key used for the error attribute.
ErrorKey = "error"
)
Variables ¶
This section is empty.
Functions ¶
Types ¶
type AttrPack ¶
type AttrPack struct {
// contains filtered or unexported fields
}
AttrPack is a an optimized pack of attributes.
type ContextLogger ¶
type ContextLogger struct {
// contains filtered or unexported fields
}
ContextLogger is an alternative to Logger having only methods with context for logging messages.
func NewContextLogger ¶
func NewContextLogger(handler slog.Handler) *ContextLogger
NewContextLogger returns a new ContextLogger with the given handler.
func (*ContextLogger) Handler ¶
func (l *ContextLogger) Handler() slog.Handler
Handler returns the associated handler.
func (*ContextLogger) LogAttrs ¶
func (l *ContextLogger) LogAttrs(ctx context.Context, level slog.Level, msg string, attrs ...slog.Attr)
LogAttrs logs a message at the given level.
func (*ContextLogger) LogWithCallerSkip ¶
func (l *ContextLogger) LogWithCallerSkip(ctx context.Context, skip int, level slog.Level, msg string, attrs ...slog.Attr)
LogWithCallerSkip logs a message at the given level with additional skipping of the specified amount of call stack frames.
func (*ContextLogger) Logger ¶
func (l *ContextLogger) Logger() *Logger
Logger returns a new Logger with the associated handler.
func (*ContextLogger) LongTerm ¶
func (l *ContextLogger) LongTerm() *ContextLogger
LongTerm returns a new Logger with the attributes applied to the handler.
func (*ContextLogger) SlogLogger ¶
func (l *ContextLogger) SlogLogger() *slog.Logger
SlogLogger returns a new slog.Logger that logs to the associated handler.
func (*ContextLogger) With ¶
func (l *ContextLogger) With(attrs ...slog.Attr) *ContextLogger
With returns a new ContextLogger with the given attributes.
func (*ContextLogger) WithGroup ¶
func (l *ContextLogger) WithGroup(group string) *ContextLogger
WithGroup returns a new ContextLogger with the given group.
func (*ContextLogger) WithLongTerm ¶
func (l *ContextLogger) WithLongTerm(attrs ...slog.Attr) *ContextLogger
WithLongTerm returns a new ContextLogger with the given attributes optimized for multiple usage.
func (*ContextLogger) WithSource ¶
func (l *ContextLogger) WithSource(enabled bool) *ContextLogger
WithSource returns a new ContextLogger that includes the source file and line in the log record if [enabled] is true.
type Logger ¶
type Logger struct {
// contains filtered or unexported fields
}
Logger is a simple logger that logs to a slog.Handler. It is an alternative to slog.Logger focused on performance and simplicity. It forces to use slog.Attr for log attributes and does not support slow alternatives provided by slog.Logger. It also takes slog.Attr in Logger.With because it is the only high performance way to add attributes.
func Default ¶
func Default() *Logger
Default returns a new Logger with the default handler from slog.Default.
func (*Logger) ContextLogger ¶
func (l *Logger) ContextLogger() *ContextLogger
ContextLogger returns a new ContextLogger that takes context in logging methods.
func (*Logger) DebugContext ¶
DebugContext logs a message at the debug level with the given context.
func (*Logger) ErrorContext ¶
ErrorContext logs a message at the error level with the given context.
func (*Logger) InfoContext ¶
InfoContext logs a message at the info level with the given context.
func (*Logger) LogContext ¶
LogContext logs a message at the given level.
func (*Logger) SlogLogger ¶
SlogLogger returns a new slog.Logger that logs to the associated handler.
func (*Logger) WarnContext ¶
WarnContext logs a message at the warn level with the given context.
func (*Logger) With ¶
With returns a new Logger with the given attributes optimized for short usage (one or two times).
func (*Logger) WithLongTerm ¶
WithLongTerm returns a new Logger with the given attributes optimized for long usage.
type TweakHandlerBuilder ¶
type TweakHandlerBuilder struct {
// contains filtered or unexported fields
}
TweakHandlerBuilder is a builder for a new handler based on existing handler.
func TweakHandler ¶
func TweakHandler(handler slog.Handler) TweakHandlerBuilder
TweakHandler returns a builder for a new handler based on existing handler.
func (TweakHandlerBuilder) Result ¶
func (b TweakHandlerBuilder) Result() slog.Handler
Result returns the new handler.
func (TweakHandlerBuilder) WithDynamicAttr ¶
func (b TweakHandlerBuilder) WithDynamicAttr(attr func(context.Context) slog.Attr) TweakHandlerBuilder
WithDynamicAttr adds a dynamic attribute to the handler.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
example
|
|
|
longterm
Package main provides an example of using the slogx logger.
|
Package main provides an example of using the slogx logger. |
|
internal
|
|
|
mock
Package mock provides a mock slog.Handler implementation and other helpers.
|
Package mock provides a mock slog.Handler implementation and other helpers. |
|
Package slogc provides context-centric logging facilities based on [slogx] and [slog] packages.
|
Package slogc provides context-centric logging facilities based on [slogx] and [slog] packages. |