README
¶
log
This structured logging library is developed with reference to Go's standard log/slog package. Although slog provides a solid foundation for structured logging, it does not support delayed field loading with the With method, resulting in premature evaluation of dynamic values. This reduces flexibility and efficiency in scenarios where log attributes—such as timestamps, request IDs, or metrics—require runtime computation. To address this, we rewrote this library.
Install
go get github.com/nexuer/log
Performance
After benchmarking, the overall performance is comparable to that of slog.
Documentation
¶
Index ¶
- Constants
- Variables
- func AddFlags(fs *flag.FlagSet)
- func Close() error
- func Debug(args ...any)
- func DebugS(msg string, kvs ...any)
- func Debugf(format string, args ...any)
- func Error(args ...any)
- func ErrorS(err error, msg string, kvs ...any)
- func Errorf(format string, args ...any)
- func Fatal(args ...any)
- func FatalS(err error, msg string, kvs ...any)
- func Fatalf(format string, args ...any)
- func FileWriter(path string, size int64, backups int64, compress ...bool) io.Writer
- func Info(args ...any)
- func InfoS(msg string, kvs ...any)
- func Infof(format string, args ...any)
- func MultiWriter(writers ...io.Writer) io.Writer
- func SetDefault(l *Logger)
- func TryMultiWriter(strategy ByteCountStrategy, writers ...io.Writer) io.Writer
- func Warn(args ...any)
- func WarnS(msg string, kvs ...any)
- func Warnf(format string, args ...any)
- func WithCallerDepth(ctx context.Context, depth int) context.Context
- type ByteCountStrategy
- type Config
- type Field
- func Any(key string, value any) Field
- func Bool(key string, v bool) Field
- func Duration(key string, v time.Duration) Field
- func Float64(key string, v float64) Field
- func Group(key string, kvs ...any) Field
- func Int(key string, value int) Field
- func Int64(key string, value int64) Field
- func String(key, value string) Field
- func Time(key string, v time.Time) Field
- func Uint64(key string, v uint64) Field
- type FileConfig
- type Format
- type Handler
- type HandlerOptions
- type Kind
- type Level
- type Logger
- func (l *Logger) Close() error
- func (l *Logger) Context() context.Context
- func (l *Logger) Debug(args ...any)
- func (l *Logger) DebugS(msg string, kvs ...any)
- func (l *Logger) Debugf(format string, args ...any)
- func (l *Logger) Error(args ...any)
- func (l *Logger) ErrorS(err error, msg string, kvs ...any)
- func (l *Logger) Errorf(format string, args ...any)
- func (l *Logger) Fatal(args ...any)
- func (l *Logger) FatalS(err error, msg string, kvs ...any)
- func (l *Logger) Fatalf(format string, args ...any)
- func (l *Logger) Handle(ctx context.Context, w io.Writer, level Level, msg string, kvs ...any) error
- func (l *Logger) Info(args ...any)
- func (l *Logger) InfoS(msg string, kvs ...any)
- func (l *Logger) Infof(format string, args ...any)
- func (l *Logger) Log(ctx context.Context, level Level, msg string, kvs ...any) error
- func (l *Logger) SetHandler(h Handler) *Logger
- func (l *Logger) SetLevel(level Level) *Logger
- func (l *Logger) SetOutput(w io.Writer) *Logger
- func (l *Logger) Warn(args ...any)
- func (l *Logger) WarnS(msg string, kvs ...any)
- func (l *Logger) Warnf(format string, args ...any)
- func (l *Logger) With(kvs ...any) *Logger
- func (l *Logger) WithContext(ctx context.Context) *Logger
- func (l *Logger) WithFields(fields ...Field) *Logger
- func (l *Logger) Write(p []byte) (n int, err error)
- func (l *Logger) Writer() io.Writer
- type Manager
- type Output
- type Readonly
- func (r *Readonly) Debug(args ...any)
- func (r *Readonly) Debugf(format string, args ...any)
- func (r *Readonly) Error(args ...any)
- func (r *Readonly) Errorf(format string, args ...any)
- func (r *Readonly) Info(args ...any)
- func (r *Readonly) Infof(format string, args ...any)
- func (r *Readonly) Warn(args ...any)
- func (r *Readonly) Warnf(format string, args ...any)
- func (r *Readonly) Write(p []byte) (int, error)
- type Replacer
- type Source
- 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 ...Field) Value
- func Int64Value(v int64) Value
- func IntValue(v int) Value
- func ResolveValuer(ctx context.Context, valuer Valuer) Value
- func SourceValue(v *Source) Value
- func StringValue(value string) Value
- func TimeValue(v time.Time) Value
- func Uint64Value(v uint64) Value
- func UintValue(v uint) Value
- func ValuerValue(valuer Valuer) Value
- func (v Value) Any() any
- func (v Value) Bool() bool
- func (v Value) Duration() time.Duration
- func (v Value) Equal(w Value) bool
- func (v Value) Float64() float64
- func (v Value) Group() []Field
- func (v Value) Int64() int64
- func (v Value) Kind() Kind
- func (v Value) Resolve(ctx context.Context) (rv Value)
- func (v Value) Source() *Source
- func (v Value) String() string
- func (v Value) Time() time.Time
- func (v Value) Uint64() uint64
- func (v Value) Valuer() Valuer
- type Valuer
Constants ¶
const ( // LevelKey is the key used by the built-in handlers for the level // of the log call. LevelKey = "level" // MessageKey is the key used by the built-in handlers for the // message of the log call. The associated value is a string. MessageKey = "msg" // NameKey is the key used by the built-in handlers for the logger name. NameKey = "logger" // ErrKey is the key used by the built-in handlers for the error message. ErrKey = "err" )
Keys for "built-in" attributes.
Variables ¶
var ( // DefaultCaller is a Valuer that returns the file and line. DefaultCaller = Caller(7) // DefaultTimestamp is a Valuer that returns the current wallclock time. DefaultTimestamp = Timestamp(time.RFC3339) DefaultFields = []any{ "ts", DefaultTimestamp, "caller", DefaultCaller, } )
var Discard = writerWrapper{Writer: io.Discard}
var ( // ErrorHandler is called whenever fails to write an event on its // output. default an error is printed on the stderr. This handler must // be thread safe and non-blocking. ErrorHandler func(err error) = func(err error) { _, _ = fmt.Fprintf(os.Stderr, "log: write failed, %v\n", err) } )
Functions ¶
func FileWriter ¶
func MultiWriter ¶
MultiWriter creates a writer that duplicates its writes to all the provided writers, similar to the Unix tee(1) command.
Each write is written to each listed writer, one at a time. If a listed writer returns an error, that overall write operation stops and returns the error; it does not continue down the list.
func SetDefault ¶
func SetDefault(l *Logger)
SetDefault makes l the default Logger, which is used by the top-level functions Info, Debug and so on.
func TryMultiWriter ¶
func TryMultiWriter(strategy ByteCountStrategy, writers ...io.Writer) io.Writer
TryMultiWriter creates a writer that attempts to write to all provided io.Writers. The first argument specifies the byte count strategy, which determines how the returned byte count is calculated. It collects all errors and joins them with errors.Join.
Types ¶
type ByteCountStrategy ¶
type ByteCountStrategy int
ByteCountStrategy defines the strategy for determining the number of bytes returned by Write.
const ( // StrategyFirst returns the byte count from the first writer. StrategyFirst ByteCountStrategy = iota // StrategyMin returns the minimum byte count among writes. StrategyMin // StrategyMax returns the maximum byte count among writes. StrategyMax )
type Config ¶
type Config struct {
Format Format
Level Level
Output Output
File FileConfig
Replacer Replacer
}
type Field ¶
func Duration ¶
Duration returns an Attr for a time.Duration.
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.