log

Documentation

Index

• func InitLogger(cfg *Config, _ string) error
• func IsContextCanceledError(err error) bool
• func Level() zapcore.Level
• func NewContext(ctx context.Context, logger Logger) context.Context
• func SetAppLogger(l *zap.Logger)
• func SetLevel(level zapcore.Level) zapcore.Level
• func ShortError(err error) zap.Field
• type Config
  • func (cfg *Config) Adjust()
• type FilterCore
  • func NewFilterCore(core zapcore.Core, allowPackages ...string) *FilterCore
  • func (f *FilterCore) Check(entry zapcore.Entry, ce *zapcore.CheckedEntry) *zapcore.CheckedEntry
  • func (f *FilterCore) With(fields []zapcore.Field) zapcore.Core
  • func (f *FilterCore) Write(entry zapcore.Entry, fields []zapcore.Field) error
• type Logger
  • func FromContext(ctx context.Context) Logger
  • func L() Logger
  • func MakeTestLogger(opts ...zap.Option) (Logger, *zaptest.Buffer)
  • func With(fields ...zap.Field) Logger
  • func (logger Logger) Begin(level zapcore.Level, name string) *Task
  • func (logger Logger) Named(name string) Logger
  • func (logger Logger) With(fields ...zap.Field) Logger
• type Task
  • func (task *Task) End(level zapcore.Level, err error, extraFields ...zap.Field) time.Duration

Functions

func InitLogger

func InitLogger(cfg *Config, _ string) error

InitLogger initializes Lightning's and also the TiDB library's loggers.

func IsContextCanceledError

func IsContextCanceledError(err error) bool

IsContextCanceledError returns whether the error is caused by context cancellation.

func Level

func Level() zapcore.Level

Level returns the current global log level.

func NewContext

func NewContext(ctx context.Context, logger Logger) context.Context

NewContext returns a new context with the provided logger.

func SetAppLogger

func SetAppLogger(l *zap.Logger)

SetAppLogger replaces the default logger in this package to given one

func SetLevel

func SetLevel(level zapcore.Level) zapcore.Level

SetLevel modifies the log level of the global logger. Returns the previous level.

func ShortError

func ShortError(err error) zap.Field

ShortError contructs a field which only records the error message without the verbose text (i.e. excludes the stack trace).

In Lightning, all errors are almost always propagated back to `main()` where the error stack is written. Including the stack in the middle thus usually just repeats known information. You should almost always use `ShortError` instead of `zap.Error`, unless the error is no longer propagated upwards.

Types

type Config

type Config struct {
	// Log level.
	Level string `toml:"level" json:"level"`
	// Log filename, leave empty to disable file log.
	File string `toml:"file" json:"file"`
	// Max size for a single file, in MB.
	FileMaxSize int `toml:"max-size" json:"max-size"`
	// Max log keep days, default is never deleting.
	FileMaxDays int `toml:"max-days" json:"max-days"`
	// Maximum number of old log files to retain.
	FileMaxBackups int `toml:"max-backups" json:"max-backups"`
}

Config serializes log related config in toml/json.

func (*Config) Adjust

func (cfg *Config) Adjust()

Adjust adjusts some fields in the config to a proper value.

type FilterCore

type FilterCore struct {
	zapcore.Core
	// contains filtered or unexported fields
}

FilterCore is a zapcore.Core implementation, it filters log by path-qualified package name.

func NewFilterCore

func NewFilterCore(core zapcore.Core, allowPackages ...string) *FilterCore

NewFilterCore returns a FilterCore, only logs under allowPackages will be written.

Example, only write br's log and ignore any other, `NewFilterCore(core, "github.com/pingcap/tidb/br/")`. Note, must set AddCaller() to the logger.

func (*FilterCore) Check

func (f *FilterCore) Check(entry zapcore.Entry, ce *zapcore.CheckedEntry) *zapcore.CheckedEntry

Check overrides wrapper core.Check and adds itself to zapcore.CheckedEntry.

func (*FilterCore) With

func (f *FilterCore) With(fields []zapcore.Field) zapcore.Core

With adds structured context to the Core.

func (*FilterCore) Write

func (f *FilterCore) Write(entry zapcore.Entry, fields []zapcore.Field) error

Write filters entry by checking if entry's Caller.Function matches filtered package path.

type Logger

type Logger struct {
	*zap.Logger
}

Logger is a simple wrapper around *zap.Logger which provides some extra methods to simplify Lightning's log usage.

func FromContext

func FromContext(ctx context.Context) Logger

FromContext returns the logger stored in the context.

func L

func L() Logger

L returns the current logger for Lightning.

func MakeTestLogger

func MakeTestLogger(opts ...zap.Option) (Logger, *zaptest.Buffer)

MakeTestLogger creates a Logger instance which produces JSON logs.

func With

func With(fields ...zap.Field) Logger

With creates a child logger from the global logger and adds structured context to it.

func (Logger) Begin

func (logger Logger) Begin(level zapcore.Level, name string) *Task

Begin marks the beginning of a task.

func (Logger) Named

func (logger Logger) Named(name string) Logger

Named adds a new path segment to the logger's name.

func (Logger) With

func (logger Logger) With(fields ...zap.Field) Logger

With creates a child logger and adds structured context to it.

type Task

type Task struct {
	Logger
	// contains filtered or unexported fields
}

Task is a logger for a task spanning a period of time. This structure records when the task is started, so the time elapsed for the whole task can be logged without book-keeping.

func (*Task) End

func (task *Task) End(level zapcore.Level, err error, extraFields ...zap.Field) time.Duration

End marks the end of a task.

The `level` is the log level if the task *failed* (i.e. `err != nil`). If the task *succeeded* (i.e. `err == nil`), the level from `Begin()` is used instead.

The `extraFields` are included in the log only when the task succeeded.