logx

package
v1.5.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 4, 2023 License: MIT Imports: 26 Imported by: 1,937

README

logx

English | 简体中文

logx configurations

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 thougth 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.

Logging methods

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.

Integrating with third-party logging libs

For more libs, please implement and PR to https://github.com/zeromicro/zero-contrib

Write the logs to specific stores

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

Filtering sensitive fields

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

More examples

https://github.com/zeromicro/zero-examples/tree/main/logx

Give a Star! ⭐

If you like or are using this project to learn or start your solution, please give it a star. Thanks!

Documentation

Index

Constants

View Source 
const (
	// DebugLevel logs everything
	DebugLevel uint32 = iota
	// InfoLevel does not include debugs
	InfoLevel
	// ErrorLevel includes errors, slows, stacks
	ErrorLevel
	// SevereLevel only log severe messages
	SevereLevel
)

Variables

View Source 
var (
	// ErrLogPathNotSet is an error that indicates the log path is not set.
	ErrLogPathNotSet = errors.New("log path must be set")
	// ErrLogServiceNameNotSet is an error that indicates that the service name is not set.
	ErrLogServiceNameNotSet = errors.New("log service name must be set")
)
View Source 
var ErrLogFileClosed = errors.New("error: log file closed")

ErrLogFileClosed is an error that indicates the log file is already closed.

Functions

func AddGlobalFields added in v1.4.2 

func AddGlobalFields(fields ...LogField)

AddGlobalFields adds global fields.

func Alert 

func Alert(v string)

Alert alerts v in alert level, and the message is written to error log.

func Close 

func Close() error

Close closes the logging.

func CollectSysLog 

func CollectSysLog()

CollectSysLog redirects system log into logx info

func ContextWithFields added in v1.4.2 

func ContextWithFields(ctx context.Context, fields ...LogField) context.Context

ContextWithFields returns a new context with the given fields.

func Debug added in v1.4.2 

func Debug(v ...any)

Debug writes v into access log.

func Debugf added in v1.4.2 

func Debugf(format string, v ...any)

Debugf writes v with format into access log.

func Debugv added in v1.4.2 

func Debugv(v any)

Debugv writes v into access log with json content.

func Debugw added in v1.4.2 

func Debugw(msg string, fields ...LogField)

Debugw writes msg along with fields into access log.

func Disable 

func Disable()

Disable disables the logging.

func DisableStat 

func DisableStat()

DisableStat disables the stat logs.

func Error 

func Error(v ...any)

Error writes v into error log.

func ErrorStack 

func ErrorStack(v ...any)

ErrorStack writes v along with call stack into error log.

func ErrorStackf 

func ErrorStackf(format string, v ...any)

ErrorStackf writes v along with call stack in format into error log.

func Errorf 

func Errorf(format string, v ...any)

Errorf writes v with format into error log.

func Errorv 

func Errorv(v any)

Errorv writes v into error log with json content. No call stack attached, because not elegant to pack the messages.

func Errorw added in v1.3.4 

func Errorw(msg string, fields ...LogField)

Errorw writes msg along with fields into error log.

func Info 

func Info(v ...any)

Info writes v into access log.

func Infof 

func Infof(format string, v ...any)

Infof writes v with format into access log.

func Infov 

func Infov(v any)

Infov writes v into access log with json content.

func Infow added in v1.3.4 

func Infow(msg string, fields ...LogField)

Infow writes msg along with fields into access log.

func Must 

func Must(err error)

Must checks if err is nil, otherwise logs the error and exits.

func MustSetup 

func MustSetup(c LogConf)

MustSetup sets up logging with given config c. It exits on error.

func SetLevel 

func SetLevel(level uint32)

SetLevel sets the logging level. It can be used to suppress some logs.

func SetUp 

func SetUp(c LogConf) (err error)

SetUp sets up the logx. If already set up, just return nil. we allow SetUp to be called multiple times, because for example we need to allow different service frameworks to initialize logx respectively.

func SetWriter added in v1.3.4 

func SetWriter(w Writer)

SetWriter sets the logging writer. It can be used to customize the logging.

func Severe 

func Severe(v ...any)

Severe writes v into severe log.

func Severef 

func Severef(format string, v ...any)

Severef writes v with format into severe log.

func Slow 

func Slow(v ...any)

Slow writes v into slow log.

func Slowf 

func Slowf(format string, v ...any)

Slowf writes v with format into slow log.

func Slowv 

func Slowv(v any)

Slowv writes v into slow log with json content.

func Sloww added in v1.3.4 

func Sloww(msg string, fields ...LogField)

Sloww writes msg along with fields into slow log.

func Stat 

func Stat(v ...any)

Stat writes v into stat log.

func Statf 

func Statf(format string, v ...any)

Statf writes v with format into stat log.

func WithColor added in v1.3.4 

func WithColor(text string, colour color.Color) string

WithColor is a helper function to add color to a string, only in plain encoding.

func WithColorPadding added in v1.3.4 

func WithColorPadding(text string, colour color.Color) string

WithColorPadding is a helper function to add color to a string with leading and trailing spaces, only in plain encoding.

func WithFields added in v1.4.0 

func WithFields(ctx context.Context, fields ...LogField) context.Context

WithFields returns a new logger with the given fields. deprecated: use ContextWithFields instead.

Types

type DailyRotateRule 

type DailyRotateRule struct {
	// contains filtered or unexported fields
}

A DailyRotateRule is a rule to daily rotate the log files.

func (*DailyRotateRule) BackupFileName 

func (r *DailyRotateRule) BackupFileName() string

BackupFileName returns the backup filename on rotating.

func (*DailyRotateRule) MarkRotated 

func (r *DailyRotateRule) MarkRotated()

MarkRotated marks the rotated time of r to be the current time.

func (*DailyRotateRule) OutdatedFiles 

func (r *DailyRotateRule) OutdatedFiles() []string

OutdatedFiles returns the files that exceeded the keeping days.

func (*DailyRotateRule) ShallRotate 

func (r *DailyRotateRule) ShallRotate(_ int64) bool

ShallRotate checks if the file should be rotated.

type LessLogger 

type LessLogger struct {
	// contains filtered or unexported fields
}

A LessLogger is a logger that control to log once during the given duration.

func NewLessLogger 

func NewLessLogger(milliseconds int) *LessLogger

NewLessLogger returns a LessLogger.

func (*LessLogger) Error 

func (logger *LessLogger) Error(v ...any)

Error logs v into error log or discard it if more than once in the given duration.

func (*LessLogger) Errorf 

func (logger *LessLogger) Errorf(format string, v ...any)

Errorf logs v with format into error log or discard it if more than once in the given duration.

type LogConf 

type LogConf struct {
	// ServiceName represents the service name.
	ServiceName string `json:",optional"`
	// Mode represents the logging mode, default is `console`.
	// console: log to console.
	// file: log to file.
	// volume: used in k8s, prepend the hostname to the log file name.
	Mode string `json:",default=console,options=[console,file,volume]"`
	// Encoding represents the encoding type, default is `json`.
	// json: json encoding.
	// plain: plain text encoding, typically used in development.
	Encoding string `json:",default=json,options=[json,plain]"`
	// TimeFormat represents the time format, default is `2006-01-02T15:04:05.000Z07:00`.
	TimeFormat string `json:",optional"`
	// Path represents the log file path, default is `logs`.
	Path string `json:",default=logs"`
	// Level represents the log level, default is `info`.
	Level string `json:",default=info,options=[debug,info,error,severe]"`
	// MaxContentLength represents the max content bytes, default is no limit.
	MaxContentLength uint32 `json:",optional"`
	// Compress represents whether to compress the log file, default is `false`.
	Compress bool `json:",optional"`
	// Stdout represents whether to log statistics, default is `true`.
	Stat bool `json:",default=true"`
	// KeepDays represents how many days the log files will be kept. Default to keep all files.
	// Only take effect when Mode is `file` or `volume`, both work when Rotation is `daily` or `size`.
	KeepDays int `json:",optional"`
	// StackCooldownMillis represents the cooldown time for stack logging, default is 100ms.
	StackCooldownMillis int `json:",default=100"`
	// MaxBackups represents how many backup log files will be kept. 0 means all files will be kept forever.
	// Only take effect when RotationRuleType is `size`.
	// Even thougth `MaxBackups` sets 0, log files will still be removed
	// if the `KeepDays` limitation is reached.
	MaxBackups int `json:",default=0"`
	// MaxSize represents how much space the writing log file takes up. 0 means no limit. The unit is `MB`.
	// Only take effect when RotationRuleType is `size`
	MaxSize int `json:",default=0"`
	// RotationRuleType represents the type of log rotation rule. Default is `daily`.
	// daily: daily rotation.
	// size: size limited rotation.
	Rotation string `json:",default=daily,options=[daily,size]"`
}

A LogConf is a logging config.

type LogField added in v1.3.4 

type LogField struct {
	Key   string
	Value any
}

LogField is a key-value pair that will be added to the log entry.

func Field added in v1.3.4 

func Field(key string, value any) LogField

Field returns a LogField for the given key and value.

type LogOption 

type LogOption func(options *logOptions)

LogOption defines the method to customize the logging.

func WithCooldownMillis 

func WithCooldownMillis(millis int) LogOption

WithCooldownMillis customizes logging on writing call stack interval.

func WithGzip 

func WithGzip() LogOption

WithGzip customizes logging to automatically gzip the log files.

func WithKeepDays 

func WithKeepDays(days int) LogOption

WithKeepDays customizes logging to keep logs with days.

func WithMaxBackups added in v1.4.0 

func WithMaxBackups(count int) LogOption

WithMaxBackups customizes how many log files backups will be kept.

func WithMaxSize added in v1.4.0 

func WithMaxSize(size int) LogOption

WithMaxSize customizes how much space the writing log file can take up.

func WithRotation added in v1.4.0 

func WithRotation(r string) LogOption

WithRotation customizes which log rotation rule to use.

type Logger 

type Logger interface {
	// Debug logs a message at info level.
	Debug(...any)
	// Debugf logs a message at info level.
	Debugf(string, ...any)
	// Debugv logs a message at info level.
	Debugv(any)
	// Debugw logs a message at info level.
	Debugw(string, ...LogField)
	// 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)
	// WithCallerSkip returns a new logger with the given caller skip.
	WithCallerSkip(skip int) Logger
	// WithContext returns a new logger with the given context.
	WithContext(ctx context.Context) Logger
	// WithDuration returns a new logger with the given duration.
	WithDuration(d time.Duration) Logger
	// WithFields returns a new logger with the given fields.
	WithFields(fields ...LogField) Logger
}

A Logger represents a logger.

func WithCallerSkip added in v1.4.2 

func WithCallerSkip(skip int) Logger

WithCallerSkip returns a Logger with given caller skip.

func WithContext 

func WithContext(ctx context.Context) Logger

WithContext sets ctx to log, for keeping tracing information.

func WithDuration 

func WithDuration(d time.Duration) Logger

WithDuration returns a Logger with given duration.

type RotateLogger 

type RotateLogger struct {
	// contains filtered or unexported fields
}

A RotateLogger is a Logger that can rotate log files with given rules.

func NewLogger 

func NewLogger(filename string, rule RotateRule, compress bool) (*RotateLogger, error)

NewLogger returns a RotateLogger with given filename and rule, etc.

func (*RotateLogger) Close 

func (l *RotateLogger) Close() error

Close closes l.

func (*RotateLogger) Write 

func (l *RotateLogger) Write(data []byte) (int, error)

type RotateRule 

type RotateRule interface {
	BackupFileName() string
	MarkRotated()
	OutdatedFiles() []string
	ShallRotate(size int64) bool
}

A RotateRule interface is used to define the log rotating rules.

func DefaultRotateRule 

func DefaultRotateRule(filename, delimiter string, days int, gzip bool) RotateRule

DefaultRotateRule is a default log rotating rule, currently DailyRotateRule.

func NewSizeLimitRotateRule added in v1.4.0 

func NewSizeLimitRotateRule(filename, delimiter string, days, maxSize, maxBackups int, gzip bool) RotateRule

NewSizeLimitRotateRule returns the rotation rule with size limit

type SizeLimitRotateRule added in v1.4.0 

type SizeLimitRotateRule struct {
	DailyRotateRule
	// contains filtered or unexported fields
}

SizeLimitRotateRule a rotation rule that make the log file rotated base on size

func (*SizeLimitRotateRule) BackupFileName added in v1.4.0 

func (r *SizeLimitRotateRule) BackupFileName() string

func (*SizeLimitRotateRule) MarkRotated added in v1.4.0 

func (r *SizeLimitRotateRule) MarkRotated()

func (*SizeLimitRotateRule) OutdatedFiles added in v1.4.0 

func (r *SizeLimitRotateRule) OutdatedFiles() []string

func (*SizeLimitRotateRule) ShallRotate added in v1.4.0 

func (r *SizeLimitRotateRule) ShallRotate(size int64) bool

type Writer added in v1.3.4 

type Writer interface {
	Alert(v any)
	Close() error
	Debug(v any, fields ...LogField)
	Error(v any, fields ...LogField)
	Info(v any, fields ...LogField)
	Severe(v any)
	Slow(v any, fields ...LogField)
	Stack(v any)
	Stat(v any, fields ...LogField)
}

func NewWriter added in v1.3.4 

func NewWriter(w io.Writer) Writer

NewWriter creates a new Writer with the given io.Writer.

func Reset added in v1.3.4 

func Reset() Writer

Reset clears the writer and resets the log level.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.