core/logx/readme.md
English | 简体中文
type LogConf struct {
ServiceName string `json:",optional"`
Mode string `json:",default=console,options=[console,file,volume]"`
Encoding string `json:",default=json,options=[json,plain]"`
TimeFormat string `json:",optional"`
Path string `json:",default=logs"`
Level string `json:",default=info,options=[info,error,severe]"`
Compress bool `json:",optional"`
KeepDays int `json:",optional"`
StackCooldownMillis int `json:",default=100"`
MaxBackups int `json:",default=0"`
MaxSize int `json:",default=0"`
Rotation string `json:",default=daily,options=[daily,size]"`
}
ServiceName: set the service name, optional. on volume mode, the name is used to generate the log files. Within rest/zrpc services, the name will be set to the name of rest or zrpc automatically.Mode: the mode to output the logs, default is console.
console mode writes the logs to stdout/stderr.file mode writes the logs to the files specified by Path.volume mode is used in docker, to write logs into mounted volumes.Encoding: indicates how to encode the logs, default is json.
json mode writes the logs in json format.plain mode writes the logs with plain text, with terminal color enabled.TimeFormat: customize the time format, optional. Default is 2006-01-02T15:04:05.000Z07:00.Path: set the log path, default to logs.Level: the logging level to filter logs. Default is info.
info, all logs are written.error, info logs are suppressed.severe, info and error logs are suppressed, only severe logs are written.Compress: whether or not to compress log files, only works with file mode.KeepDays: how many days that the log files are kept, after the given days, the outdated files will be deleted automatically. It has no effect on console mode.StackCooldownMillis: how many milliseconds to rewrite stacktrace again. It’s used to avoid stacktrace flooding.MaxBackups: represents how many backup log files will be kept. 0 means all files will be kept forever. Only take effect when Rotation is size. NOTE: the level of option KeepDays will be higher. Even though MaxBackups sets 0, log files will still be removed if the KeepDays limitation is reached.MaxSize: represents how much space the writing log file takes up. 0 means no limit. The unit is MB. Only take effect when Rotation is size.Rotation: represents the type of log rotation rule. Default is daily.
daily rotate the logs by day.size rotate the logs by size of logs.type Logger interface {
// Error logs a message at error level.
Error(...any)
// Errorf logs a message at error level.
Errorf(string, ...any)
// Errorv logs a message at error level.
Errorv(any)
// Errorw logs a message at error level.
Errorw(string, ...LogField)
// Info logs a message at info level.
Info(...any)
// Infof logs a message at info level.
Infof(string, ...any)
// Infov logs a message at info level.
Infov(any)
// Infow logs a message at info level.
Infow(string, ...LogField)
// Slow logs a message at slow level.
Slow(...any)
// Slowf logs a message at slow level.
Slowf(string, ...any)
// Slowv logs a message at slow level.
Slowv(any)
// Sloww logs a message at slow level.
Sloww(string, ...LogField)
// WithContext returns a new logger with the given context.
WithContext(context.Context) Logger
// WithDuration returns a new logger with the given duration.
WithDuration(time.Duration) Logger
}
Error, Info, Slow: write any kind of messages into logs, with like fmt.Sprint(…).Errorf, Infof, Slowf: write messages with given format into logs.Errorv, Infov, Slowv: write any kind of messages into logs, with json marshalling to encode them.Errorw, Infow, Sloww: write the string message with given key:value fields.WithContext: inject the given ctx into the log messages, typically used to log trace-id and span-id.WithDuration: write elapsed duration into the log messages, with key duration.For more libs, please implement and PR to https://github.com/zeromicro/zero-contrib
logx defined two interfaces to let you customize logx to write logs into any stores.
logx.NewWriter(w io.Writer)logx.SetWriter(writer logx.Writer)For example, if we want to write the logs into kafka instead of console or files, we can do it like below:
type KafkaWriter struct {
Pusher *kq.Pusher
}
func NewKafkaWriter(pusher *kq.Pusher) *KafkaWriter {
return &KafkaWriter{
Pusher: pusher,
}
}
func (w *KafkaWriter) Write(p []byte) (n int, err error) {
// writing log with newlines, trim them.
if err := w.Pusher.Push(strings.TrimSpace(string(p))); err != nil {
return 0, err
}
return len(p), nil
}
func main() {
pusher := kq.NewPusher([]string{"localhost:9092"}, "go-zero")
defer pusher.Close()
writer := logx.NewWriter(NewKafkaWriter(pusher))
logx.SetWriter(writer)
// more code
}
Complete code: https://github.com/zeromicro/zero-examples/blob/main/logx/tokafka/main.go
If we need to prevent the password fields from logging, we can do it like below:
type (
Message struct {
Name string
Password string
Message string
}
SensitiveLogger struct {
logx.Writer
}
)
func NewSensitiveLogger(writer logx.Writer) *SensitiveLogger {
return &SensitiveLogger{
Writer: writer,
}
}
func (l *SensitiveLogger) Info(msg any, fields ...logx.LogField) {
if m, ok := msg.(Message); ok {
l.Writer.Info(Message{
Name: m.Name,
Password: "******",
Message: m.Message,
}, fields...)
} else {
l.Writer.Info(msg, fields...)
}
}
func main() {
// setup logx to make sure originalWriter not nil,
// the injected writer is only for filtering, like a middleware.
originalWriter := logx.Reset()
writer := NewSensitiveLogger(originalWriter)
logx.SetWriter(writer)
logx.Infov(Message{
Name: "foo",
Password: "shouldNotAppear",
Message: "bar",
})
// more code
}
Complete code: https://github.com/zeromicro/zero-examples/blob/main/logx/filterfields/main.go
https://github.com/zeromicro/zero-examples/tree/main/logx
If you like or are using this project to learn or start your solution, please give it a star. Thanks!