Documentation
¶
Overview ¶
Package xlog is a small structured logger facade over a pluggable Core.
The package-level API intentionally does not know about JSON, slog, zap, or any other concrete backend. Backends implement Core; adapters live in separate packages.
Index ¶
- Constants
- Variables
- func ContextWithFields(ctx context.Context, fields ...Field) context.Context
- func IntoContext(ctx context.Context, logger *Logger) context.Context
- func NewSlogHandler(l *Logger) slog.Handler
- type AsyncPolicy
- type AtomicLevel
- type CheckedEntry
- type Config
- type ContextLogger
- func (c *ContextLogger) Critical(ctx context.Context, msg string, fields ...Field)
- func (c *ContextLogger) Debug(ctx context.Context, msg string, fields ...Field)
- func (c *ContextLogger) Enabled(level Level) bool
- func (c *ContextLogger) Error(ctx context.Context, msg string, fields ...Field)
- func (c *ContextLogger) Info(ctx context.Context, msg string, fields ...Field)
- func (c *ContextLogger) Level() Level
- func (c *ContextLogger) Log(ctx context.Context, level Level, msg string, fields ...Field)
- func (c *ContextLogger) Logger() *Logger
- func (c *ContextLogger) Sync() error
- func (c *ContextLogger) Trace(ctx context.Context, msg string, fields ...Field)
- func (c *ContextLogger) Warn(ctx context.Context, msg string, fields ...Field)
- func (c *ContextLogger) With(fields ...Field) *ContextLogger
- type Core
- type DurationFormat
- type Encoder
- type Event
- type Field
- func Email(key, value string) Field
- func ErrorCause(err error) Field
- func ErrorChain(err error) Field
- func Errors(key string, errs []error) Field
- func FieldsFromContext(ctx context.Context) []Field
- func Generic[T any](key string, value T, append xfield.AppendFunc[T]) Field
- func Secret(key, value string) Field
- func ValueOf[T xfield.Value](key string, value T) Field
- type FieldEncoder
- type Level
- type LevelEnabler
- type LevelReader
- type Logger
- func (l *Logger) AppendName(sub string) *Logger
- func (l *Logger) Check(level Level, msg string) *CheckedEntry
- func (l *Logger) CheckCritical(msg string) *CheckedEntry
- func (l *Logger) CheckDebug(msg string) *CheckedEntry
- func (l *Logger) CheckError(msg string) *CheckedEntry
- func (l *Logger) CheckInfo(msg string) *CheckedEntry
- func (l *Logger) CheckTrace(msg string) *CheckedEntry
- func (l *Logger) CheckWarn(msg string) *CheckedEntry
- func (l *Logger) Core() Core
- func (l *Logger) Critical(msg string, fields ...Field)
- func (l *Logger) Ctx() *ContextLogger
- func (l *Logger) Debug(msg string, fields ...Field)
- func (l *Logger) Enabled(level Level) bool
- func (l *Logger) Error(msg string, fields ...Field)
- func (l *Logger) Info(msg string, fields ...Field)
- func (l *Logger) Level() Level
- func (l *Logger) Log(level Level, msg string, fields ...Field)
- func (l *Logger) Name() string
- func (l *Logger) PrependName(prefix string) *Logger
- func (l *Logger) ReplaceName(name string) *Logger
- func (l *Logger) Sync() error
- func (l *Logger) Trace(msg string, fields ...Field)
- func (l *Logger) Warn(msg string, fields ...Field)
- func (l *Logger) With(fields ...Field) *Logger
- func (l *Logger) WithContext(ctx context.Context) *Logger
- type NopCore
- type Observer
- type Option
- func WithAsync(buffer int, policy AsyncPolicy) Option
- func WithAtomicLevel(level *AtomicLevel) Option
- func WithCaller(enabled bool) Option
- func WithCallerSkip(skip int) Option
- func WithClock(clock func() time.Time) Option
- func WithContextFieldExtractor(fn func(context.Context) []Field) Option
- func WithCore(core Core) Option
- func WithDurationFormat(format DurationFormat) Option
- func WithEncoder(encoder Encoder) Option
- func WithFields(fields ...Field) Option
- func WithLevel(level Level) Option
- func WithLevelEnabler(leveler LevelEnabler) Option
- func WithObserver(observer Observer) Option
- func WithPretty() Option
- func WithSampling(first, thereafter uint64) Option
- func WithSink(writer io.Writer) Option
- func WithStacktrace(level Level) Option
- func WithTimeLayout(layout string) Option
- func WithWriter(writer io.Writer) Option
- func WithoutPretty() Option
- type PrettyMode
Constants ¶
const ( TraceLevel = xcore.TraceLevel DebugLevel = xcore.DebugLevel InfoLevel = xcore.InfoLevel WarnLevel = xcore.WarnLevel ErrorLevel = xcore.ErrorLevel CriticalLevel = xcore.CriticalLevel AsyncBlock = xcore.AsyncBlock AsyncDropNewest = xcore.AsyncDropNewest AsyncDropOldest = xcore.AsyncDropOldest DurationString = xfield.DurationString DurationNanos = xfield.DurationNanos FieldTime = xfield.TimeKey FieldLevel = xfield.LevelKey FieldLogger = xfield.LoggerKey FieldMessage = xfield.MessageKey FieldError = xfield.ErrorKey )
Variables ¶
var ( String = xfield.String Bool = xfield.Bool Int = xfield.Int Int64 = xfield.Int64 Uint = xfield.Uint Uint64 = xfield.Uint64 Float64 = xfield.Float64 Duration = xfield.Duration Time = xfield.Time Err = xfield.Err Error = xfield.Error Any = xfield.Any Custom = xfield.Custom CustomFn = xfield.CustomFunc )
Functions ¶
func ContextWithFields ¶
func NewSlogHandler ¶ added in v1.2.0
NewSlogHandler returns a log/slog Handler that writes every slog record into l, so libraries logging through the stdlib slog API end up in the same stream and format as the rest of the application:
slog.SetDefault(slog.New(xlog.NewSlogHandler(logger)))
Behaviour:
- Levels: slog levels map onto xlog levels by rounding down to the nearest named slog level: below Debug → Trace, [Debug, Info) → Debug, [Info, Warn) → Info, [Warn, Error) → Warn, [Error, Error+4) → Error and Error+4 or higher → Critical. Enabled follows l's level, including a dynamic one (WithAtomicLevel).
- Attrs keep their kind: string, int64, uint64, float64, bool, time and duration become the matching xlog fields (durations honour the logger's DurationFormat), values implementing error become error fields and everything else is written as Any. LogValuers are resolved.
- Groups: xlog fields are flat, so groups (slog.Group and WithGroup) become dotted key prefixes: slog.Group("req", slog.String("id", "1")) is written as "req.id". Groups without attrs are omitted, a group with an empty key is inlined, and attrs with an empty key are dropped.
- Context: the record's context is passed through as on the ContextLogger path, so ContextWithFields values and a WithContextFieldExtractor (e.g. OTel trace_id/span_id) are attached to slog.InfoContext and friends.
- Time: the record's time is used; a zero record time is stamped by the core.
- Caller: with WithCaller enabled, "caller" is taken from the record's PC, i.e. the slog call site (WithCallerSkip does not apply). Records without a PC get no caller field. The logger name and stacktrace settings apply as for any other log call.
A nil l yields a handler that discards everything.
Types ¶
type AsyncPolicy ¶
type AsyncPolicy = xcore.AsyncPolicy
type AtomicLevel ¶
type AtomicLevel = xcore.AtomicLevel
func NewAtomicLevel ¶
func NewAtomicLevel(level Level) *AtomicLevel
type CheckedEntry ¶
type CheckedEntry struct {
// contains filtered or unexported fields
}
func (*CheckedEntry) Write ¶
func (e *CheckedEntry) Write(fields ...Field)
type Config ¶
type Config struct {
Level Level
Leveler LevelEnabler
Writer io.Writer
Fields []Field
Clock func() time.Time
TimeLayout string
DurationFormat DurationFormat
Encoder Encoder
Core Core
Observer Observer
ContextFields func(context.Context) []Field
Caller bool
CallerSkip int
Stacktrace *Level
SampleFirst uint64
SampleThereafter uint64
AsyncBuffer int
AsyncPolicy AsyncPolicy
UseAsync bool
Pretty PrettyMode
}
func DefaultConfig ¶
func DefaultConfig() Config
type ContextLogger ¶
type ContextLogger struct {
// contains filtered or unexported fields
}
ContextLogger mirrors Logger but takes a context.Context as the first argument on every logging method. Each call attaches fields carried in the context (ContextWithFields) and passes the context through to the Event so context-aware backends (e.g. the slog adapter) and OTel-style integrations can read request-scoped values. The underlying Logger is bound once.
func (*ContextLogger) Critical ¶
func (c *ContextLogger) Critical(ctx context.Context, msg string, fields ...Field)
func (*ContextLogger) Debug ¶
func (c *ContextLogger) Debug(ctx context.Context, msg string, fields ...Field)
func (*ContextLogger) Enabled ¶
func (c *ContextLogger) Enabled(level Level) bool
func (*ContextLogger) Error ¶
func (c *ContextLogger) Error(ctx context.Context, msg string, fields ...Field)
func (*ContextLogger) Info ¶
func (c *ContextLogger) Info(ctx context.Context, msg string, fields ...Field)
func (*ContextLogger) Level ¶
func (c *ContextLogger) Level() Level
func (*ContextLogger) Log ¶
Log writes at the given level. Entry point for adapters mapping an external level enum onto xlog at runtime.
func (*ContextLogger) Logger ¶
func (c *ContextLogger) Logger() *Logger
Logger returns the underlying Logger.
func (*ContextLogger) Sync ¶
func (c *ContextLogger) Sync() error
func (*ContextLogger) Trace ¶
func (c *ContextLogger) Trace(ctx context.Context, msg string, fields ...Field)
func (*ContextLogger) Warn ¶
func (c *ContextLogger) Warn(ctx context.Context, msg string, fields ...Field)
func (*ContextLogger) With ¶
func (c *ContextLogger) With(fields ...Field) *ContextLogger
With returns a ContextLogger whose underlying Logger carries the extra fields.
type Core ¶
func NewAsyncCore ¶
func NewAsyncCore(next Core, buffer int, policy AsyncPolicy, observer Observer) Core
func NewFilterCore ¶
func NewFilterCore(next Core, leveler LevelEnabler) Core
func NewHookCore ¶
func NewSamplerCore ¶
func NewTeeCore ¶
type DurationFormat ¶ added in v1.1.0
type DurationFormat = xfield.DurationFormat
type FieldEncoder ¶
type Level ¶
func ParseLevel ¶
ParseLevel parses "trace" | "debug" | "info" | "warn" | "warning" | "error" | "err" | "critical" | "crit" | "fatal" (case-insensitive).
type LevelEnabler ¶
type LevelEnabler = xcore.LevelEnabler
type LevelReader ¶
type LevelReader = xcore.LevelReader
type Logger ¶
type Logger struct {
// contains filtered or unexported fields
}
func Default ¶
func Default() *Logger
Default returns a JSON logger at info level writing to stdout.
func FromContext ¶
func New ¶
New constructs a Logger. The name is optional and can be set or extended later with Named, zap-style.
func NewConsole ¶
NewConsole constructs a human-readable Logger. Use Named to set/extend the name.
func (*Logger) AppendName ¶
AppendName returns a child whose name is parent.name + "." + sub. Example: logger("api").AppendName("db") → "api.db". Empty sub returns the receiver unchanged.
func (*Logger) CheckCritical ¶
func (l *Logger) CheckCritical(msg string) *CheckedEntry
func (*Logger) CheckDebug ¶
func (l *Logger) CheckDebug(msg string) *CheckedEntry
func (*Logger) CheckError ¶
func (l *Logger) CheckError(msg string) *CheckedEntry
func (*Logger) CheckInfo ¶
func (l *Logger) CheckInfo(msg string) *CheckedEntry
func (*Logger) CheckTrace ¶
func (l *Logger) CheckTrace(msg string) *CheckedEntry
func (*Logger) CheckWarn ¶
func (l *Logger) CheckWarn(msg string) *CheckedEntry
func (*Logger) Level ¶
Level reports the current minimum level. A dynamic leveler that implements LevelReader (e.g. *AtomicLevel) is read live, so it reflects Set; otherwise the configured static level is returned.
func (*Logger) Log ¶
Log writes at the given level. Primary entry point for adapters that map an external level enum onto xlog at runtime.
func (*Logger) PrependName ¶
PrependName returns a child whose name is prefix + "." + parent.name. Useful for stamping an app-level root on top of a component-named logger (e.g. component owns "api.db", app prepends "main" → "main.api.db"). Empty prefix returns the receiver unchanged.
func (*Logger) ReplaceName ¶
ReplaceName returns a child with name set to name, discarding any existing chain. Pass "" to clear the name entirely.
type Option ¶
type Option func(*Config)
func WithAsync ¶
func WithAsync(buffer int, policy AsyncPolicy) Option
func WithAtomicLevel ¶
func WithAtomicLevel(level *AtomicLevel) Option
func WithCaller ¶
func WithCallerSkip ¶
func WithContextFieldExtractor ¶
WithContextFieldExtractor registers a function that derives extra fields from the context on every ContextLogger call (Info(ctx, ...) etc.). Use it to attach request-scoped data such as OTel trace_id/span_id to each log without coupling the core to any specific library. The plain Logger path has no context and is unaffected.
func WithDurationFormat ¶ added in v1.1.0
func WithDurationFormat(format DurationFormat) Option
WithDurationFormat selects how the built-in JSON and console encoders render time.Duration values: DurationString ("1.5s", the default) or DurationNanos (integer nanoseconds). Custom encoders set via WithEncoder are unaffected.
func WithEncoder ¶
func WithFields ¶
func WithLevelEnabler ¶
func WithLevelEnabler(leveler LevelEnabler) Option
func WithObserver ¶
func WithPretty ¶
func WithPretty() Option
func WithSampling ¶
func WithStacktrace ¶
func WithTimeLayout ¶
func WithWriter ¶
func WithoutPretty ¶
func WithoutPretty() Option
type PrettyMode ¶
type PrettyMode int
PrettyMode controls human-readable output for JSON loggers.
const ( // PrettyAuto enables pretty output when XLOG_PRETTY env is truthy or, if // the env is unset, when the writer is a TTY. This is the default. PrettyAuto PrettyMode = iota // PrettyOn forces pretty output regardless of env or TTY. PrettyOn // PrettyOff forces raw JSON output regardless of env or TTY. PrettyOff )
Directories
¶
| Path | Synopsis |
|---|---|
|
contrib
|
|
|
libs/aws
module
|
|
|
libs/otel
module
|
|
|
libs/pgx
module
|
|
|
loggers/apex
module
|
|
|
loggers/charm
module
|
|
|
loggers/gokit
module
|
|
|
loggers/hclog
module
|
|
|
loggers/log15
module
|
|
|
loggers/logrus
module
|
|
|
loggers/phuslu
module
|
|
|
loggers/slog
module
|
|
|
loggers/zap
module
|
|
|
loggers/zerolog
module
|
|
|
internal
|
|
|
pkg
|
|