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.
type Handler ¶
type Handler interface {
WithFields(ctx context.Context, fields ...Field) Handler
// Handle handles the Log with Context, Writer, Level , Message and the arguments.
Handle(ctx context.Context, w io.Writer, level Level, msg string, kvs ...any) error
}
func Json ¶
func Json(opts ...*HandlerOptions) Handler
func Text ¶
func Text(opts ...*HandlerOptions) Handler
type HandlerOptions ¶
type Logger ¶
type Logger struct {
// contains filtered or unexported fields
}
func (*Logger) SetHandler ¶
SetHandler set the current Handler Note: This is not concurrency-safe.
func (*Logger) SetLevel ¶
SetLevel set the current minimum severity level for logging output. Note: This is not concurrency-safe.
func (*Logger) WithFields ¶
type Manager ¶
type Manager struct {
// contains filtered or unexported fields
}
func InitManager ¶
InitManager init global manager
func NewManager ¶
func (*Manager) AddWithSuffix ¶
type Readonly ¶
type Readonly struct {
// contains filtered or unexported fields
}
Readonly is a logger wrapper that restricts modifications to the underlying logger. It prevents changes to log configuration, such as altering the log level or output, and excludes the Fatal level to avoid program termination. All methods delegate to the wrapped Logger, providing only logging output functionality.
func NewReadonly ¶
NewReadonly creates a new Readonly logger, wrapping the provided Logger. If log is nil, it uses a default Logger from Default().
type Source ¶
type Source struct {
// Function is the package path-qualified function name containing the
// source line. If non-empty, this string uniquely identifies a single
// function in the program. This may be the empty string if not known.
Function string `json:"function"`
// File and Line are the file name and line number (1-based) of the source
// line. These may be the empty string and zero, respectively, if not known.
File string `json:"file"`
Line int `json:"line"`
}
type Value ¶
type Value struct {
// contains filtered or unexported fields
}
A Value can represent any Go value, but unlike type any, it can represent most small values without an allocation. The zero Value corresponds to nil.
func AnyValue ¶
AnyValue returns a Value for the supplied value.
If the supplied value is of type Value, it is returned unmodified.
Given a value of one of Go's predeclared string, bool, or (non-complex) numeric types, AnyValue returns a Value of kind KindString, KindBool, KindUint64, KindInt64, or KindFloat64. The width of the original numeric type is not preserved.
Given a time.Time or time.Duration value, AnyValue returns a Value of kind KindTime or KindDuration. The monotonic time is not preserved.
For nil, or values of all other types, including named types whose underlying type is numeric, AnyValue returns a value of kind KindAny.
func DurationValue ¶
DurationValue returns a Value for a time.Duration.
func Float64Value ¶
Float64Value returns a Value for a floating-point number.
func GroupValue ¶
GroupValue returns a new Value for a list of Attrs. The caller must not subsequently mutate the argument slice.
func StringValue ¶
StringValue returns a new Value for a string.
func ValuerValue ¶
ValuerValue return the function value on Valuer.
func (Value) Duration ¶
Duration returns v's value as a time.Duration. It panics if v is not a time.Duration.
func (Value) Resolve ¶
Resolve repeatedly calls Valuer on v while it implements Valuer, and returns the result. If v resolves to a group, the group's attributes' values are not recursively resolved. If the number of Valuer calls exceeds a threshold, a Value containing an error is returned. Resolve's return value is guaranteed not to be of Kind KindValuer.
func (Value) String ¶
String returns Value's value as a string, formatted like fmt.Sprint. Unlike the methods Int64, Float64, and so on, which panic if v is of the wrong kind, String never panics.
Source Files
Directories