Documentation
¶
Overview ¶
Package log provides a minimalist logging API.
It leverages logr.Logger to encourage attaching structured information instead of unstructured format strings. See https://github.com/go-logr/logr.
Usage ¶
First, logger need to initialize at the beginning.
if err := log.Init(); err != nil {
// Handle error.
}
Then log info or error logs elsewhere:
log.FromContext(ctx).Info("setting target", "value", targetValue)
log.FromContext(ctx).Error(err, "failed to open the pod bay door", "user", user)
Sampler ¶
It supports sampling Info logs using sampler provided by WithSampler. By default, it records all Info logs without sampling. However, if there is an Error log happens, it records buffered Info logs even they are not sampled. It provides context to root cause analysis for the Error log. The default buffer size is 10, which can be changed by WithBufferSize.
Contexter ¶
It populates fields from Context if the logger provided by WithZapLogger implements Contexter. It only executes once on the first Context associated with the logger. A sample usage is collecting tracing context to link logs with trace spans.
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func FromContext ¶ added in v0.4.0
FromContext returns the logger associated with the context. If no logger is associated, the default logger is return.
func Init ¶
Init initializes the default logger.
The underlying implementation is the Zap Log. See https://go.uber.org/zap.
func NewContext ¶
NewContext returns a new Context, derived from ctx, which associates a logger derived with provided information from the logger associated with the ctx or default logger.
Example ¶
package main
import (
"context"
"go.uber.org/zap"
"github.com/ktong/nilgo/log"
)
func main() {
_ = log.Init(
log.WithZapLogger(zap.NewExample()),
)
ctx := log.NewContext(context.Background(), "context", "key", "value")
log.FromContext(ctx).Info("info log")
}
Output: {"level":"info","logger":"context","msg":"info log","key":"value"}
Types ¶
type Contexter ¶
Contexter is the interface that wraps the basic Context method.
Context fetches structured context to the Core.
Example ¶
package main
import (
"context"
"go.uber.org/zap"
"go.uber.org/zap/zapcore"
"github.com/ktong/nilgo/log"
)
func main() {
_ = log.Init(
log.WithZapLogger(
zap.NewExample(
zap.WrapCore(
func(z zapcore.Core) zapcore.Core {
return core{Core: z}
},
),
),
),
)
log.FromContext(context.Background()).Info("info log")
}
type core struct {
zapcore.Core
}
func (c core) Context(context.Context) zapcore.Core {
return c.With(
[]zap.Field{
zap.Any("context", true),
},
)
}
Output: {"level":"info","msg":"info log","context":true}
type Option ¶
type Option func(*options)
Option configures the logger.
func WithBufferSize ¶
WithBufferSize provides size of buffer for Info logs which write to output if Error log follows. It drops all Info logs if buffer size is 0.
The default buffer size is 10.
func WithSampler ¶
WithSampler provides a sampler which decides whether Info log should write to output.
The default is always sampled.
Example ¶
package main
import (
"context"
"errors"
"go.uber.org/zap"
"github.com/ktong/nilgo/log"
)
func main() {
_ = log.Init(
log.WithSampler(func(context.Context) bool {
return false
}),
log.WithBufferSize(2),
log.WithZapLogger(zap.NewExample()),
)
ctx := log.NewContext(context.Background(), "sampler")
log.FromContext(ctx).Info("info log")
log.FromContext(ctx).Info("another info log")
log.FromContext(ctx).WithValues("key", "value").Info("new info log")
log.FromContext(ctx).Error(errors.New("error"), "error log")
}
Output: {"level":"info","logger":"sampler","msg":"another info log"} {"level":"info","logger":"sampler","msg":"new info log","key":"value"} {"level":"error","logger":"sampler","msg":"error log","error":"error"}
func WithZapLogger ¶
WithZapLogger provides a customized zap logger.
The default is logger returns from zap.Production().
Source Files