logger

package
v1.0.11 Latest Latest
Warning

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

 Go to latest Published: Jun 28, 2026 License: MIT Imports: 29 Imported by: 0

README

logger configurations

type LogConf struct {
	ServiceName         string              
	Mode                string              
	Encoding            string              
	TimeFormat          string              
	Path                string              
	Level               string              
	Compress            bool                
	KeepDays            int                 
	StackCooldownMillis int                 
	MaxBackups          int                 
	MaxSize             int                 
	Rotation            string              
}
  • 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.

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.

Write the logs to specific stores

logger defined two interfaces to let you customize logger to write logs into any stores.

  • logger.NewWriter(w io.Writer)
  • logger.SetWriter(writer logx.Writer)

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 {
        logger.Writer
	}
)

func NewSensitiveLogger(writer logger.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 := logger.Reset()
	writer := NewSensitiveLogger(originalWriter)
    logger.SetWriter(writer)

    logger.Infov(Message{
		Name:     "foo",
		Password: "shouldNotAppear",
		Message:  "bar",
	})
  
	// more code
}

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
)
View Source 
const TAG = "[GORM]"

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")
	// ExitOnFatal defines whether to exit on fatal errors, defined here to make it easier to test
	ExitOnFatal = syncx.ForAtomicBool(true)
)
View Source 
var (
	// ErrLogFileClosed is an error that indicates the log file is already closed
	ErrLogFileClosed = errors.New("error: log file closed")
)

Functions

func AddGlobalFields 

func AddGlobalFields(fields ...LogField)

AddGlobalFields adds global fields

func AddWriter 

func AddWriter(w Writer)

AddWriter adds a new writer If there is already a writer, the new writer will be added to the writer chain For example, to write logs to both file and console, if there is already a file writer, ```go logx.AddWriter(logx.NewWriter(os.Stdout)) ```

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 

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

ContextWithFields returns a new context with the given fields

func Debug 

func Debug(v ...any)

Debug writes v into access log

func Debugf 

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

Debugf writes v with format into access log

func Debugv 

func Debugv(v any)

Debugv writes v into access log with json content

func Debugw 

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

Debugw writes msg along with fields into the 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 

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

Errorw writes msg along with fields into the 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 

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

Infow writes msg along with fields into the 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 ReadLastNLines 

func ReadLastNLines(path string, n int) ([]string, 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, 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 

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 

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 

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 

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 

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 GormLogger 

type GormLogger struct {
}

func (*GormLogger) Error 

func (l *GormLogger) Error(ctx context.Context, str string, args ...interface{})

func (*GormLogger) Info 

func (l *GormLogger) Info(ctx context.Context, str string, args ...interface{})

func (*GormLogger) LogMode 

func (l *GormLogger) LogMode(logger.LogLevel) logger.Interface

func (*GormLogger) Trace 

func (l *GormLogger) Trace(ctx context.Context, begin time.Time, fc func() (sql string, rowsAffected int64), err error)

func (*GormLogger) Warn 

func (l *GormLogger) Warn(ctx context.Context, str string, args ...interface{})

type LessLogger 

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

A LessLogger is a logger that controls 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 `yaml:"ServiceName" default:"NPanel"`
	// 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 `yaml:"Mode" default:"file"`
	// Encoding represents the encoding type, default is `json`
	// json: json encoding
	// plain: plain text encoding, typically used in development
	Encoding string `yaml:"Encoding" default:"json"`
	// TimeFormat represents the time format, default is `2006-01-02T15:04:05.000Z07:00`
	TimeFormat string `yaml:"TimeFormat" default:"2006-01-02 15:04:05.000"`
	// Path represents the log file path, default is `logs`
	Path string `yaml:"Path" default:"logs"`
	// Level represents the log level, default is `info`
	Level string `yaml:"Level" default:"info"`
	// MaxContentLength represents the max content bytes, default is no limit
	MaxContentLength uint32 `yaml:"MaxContentLength" default:"0"`
	// Compress represents whether to compress the log file, default is `false`
	Compress bool `yaml:"Compress" default:"false"`
	// Stat represents whether to log statistics, default is `true`
	Stat bool `yaml:"Stat" 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 `yaml:"KeepDays" default:"0"`
	// StackCooldownMillis represents the cooldown time for stack logging, default is 100ms
	StackCooldownMillis int `yaml:"StackCooldownMillis" 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 though `MaxBackups` sets 0, log files will still be removed
	// if the `KeepDays` limitation is reached
	MaxBackups int `yaml:"MaxBackups" 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 `yaml:"MaxSize" default:"0"`
	// Rotation represents the type of log rotation rule. Default is `daily`
	// daily: daily rotation
	// size: size limited rotation
	Rotation string `yaml:"Rotation" default:"daily"`
	// FileTimeFormat represents the time format for file name, default is `2006-01-02T15:04:05.000Z07:00`
	FileTimeFormat string `yaml:"FileTimeFormat" default:"2006-01-02T15:04:05.000Z07:00"`
}

A LogConf is a logging config

type LogField 

type LogField struct {
	Key   string
	Value any
}

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

func Field 

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 

func WithMaxBackups(count int) LogOption

WithMaxBackups customizes how many log files backups will be kept

func WithMaxSize 

func WithMaxSize(size int) LogOption

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

func WithRotation 

func WithRotation(r string) LogOption

WithRotation customizes which log rotation rule to use

type Logger 

type Logger interface {
	// Debug logs a message at debug level
	Debug(...any)
	// Debugf logs a message at debug level
	Debugf(string, ...any)
	// Debugv logs a message at debug level
	Debugv(any)
	// Debugw logs a message at debug 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 

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 

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

NewSizeLimitRotateRule returns the rotation rule with size limit

type SizeLimitRotateRule 

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 

func (r *SizeLimitRotateRule) BackupFileName() string

func (*SizeLimitRotateRule) MarkRotated 

func (r *SizeLimitRotateRule) MarkRotated()

func (*SizeLimitRotateRule) OutdatedFiles 

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

func (*SizeLimitRotateRule) ShallRotate 

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

type Writer 

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 

func NewWriter(w io.Writer) Writer

NewWriter creates a new Writer with the given io.Writer

func Reset 

func Reset() Writer

Reset clears the writer and resets the log level

Source Files

View all Source files

Directories

Path Synopsis

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.