log

README

Translations: English | 简体中文

Log

This module provides a simple logging interface which is easy to use and implement. It also provides a usable implementation based on the log package of the Go SDK.

The following logging frameworks are planned to be adapted:

• Uber Zap - adapt with a module named zap-log
• logrus - adapt with a module named logrus-log

Features

• Print message via the Print-like function family: Print,Printf,Println
• Support key/value pairs metadata.
• Support named loggers.
• Support level logging.
• Support dynamic runtime logging level control by logger names.
• Support context.Context and extracting value from it.

Architecture

Authors

• dowenliu-xyz hawkdowen@hotmail.com

License

Log is licensed under the MIT. See LICENSE for the full license text.

Documentation

Index

• Constants
• func NoLevelStore()
• func RegisterLevelName(level Level, name string)
• func ResetLevelNames()
• func UseLevelStore(store LevelStore)
• func UseProvider(provider LoggerProvider)
• func Value(ctx context.Context, v interface{}) interface{}
• type Field
• type Level
  • func (l Level) String() string
• type LevelStore
  • func GetLevelStore() LevelStore
  • func NewStdLevelStore(opts ...StdLevelStoreOption) LevelStore
• type Logger
  • func Get(name string) Logger
  • func NewNopLogger() Logger
  • func NewStdLogger(name string, output Output) Logger
• type LoggerProvider
  • func NewStdLoggerProvider(output Output) LoggerProvider
• type Output
  • func NewStdOutput(out *log.Logger) Output
• type Printer
  • func NewNopPrinter() Printer
• type StdLevelStoreOption
  • func LoggerLevel(name string, level Level) StdLevelStoreOption
  • func RootLevel(level Level) StdLevelStoreOption
• type Valuer

Constants

const (
	// LevelKey is field key for logging Level.
	LevelKey = "level"
	// LoggerKey is field key for logger name.
	LoggerKey = "logger"
)

Functions

func NoLevelStore

func NoLevelStore()

NoLevelStore clears registered LevelStore.

func RegisterLevelName

func RegisterLevelName(level Level, name string)

RegisterLevelName register the name of one level. If the level is already exists, the function will overwrite it. If the name given is empty, it register nothing, or it deregister a level name.

func ResetLevelNames

func ResetLevelNames()

ResetLevelNames reset level name to default.

func UseLevelStore

func UseLevelStore(store LevelStore)

UseLevelStore register a LevelStore for use by default. If this function is called more than once, the last call wins.

func UseProvider

func UseProvider(provider LoggerProvider)

UseProvider register a LoggerProvider for use by default. If this function is called more than once, the last call wins.

func Value

func Value(ctx context.Context, v interface{}) interface{}

Value calculate and return the value if v is a Valuer, or just return v.

Types

type Field

type Field struct {
	// Key is the key, string.
	Key string
	// Value is the value, may be a Valuer.
	Value interface{}
}

Field represent a key/value pair.

type Level

type Level int8

A Level is a logging priority. Higher levels are more important.

const (
	// DebugLevel logs are typically voluminous, and are usually disabled in
	// production.
	DebugLevel Level = iota - 1
	// InfoLevel is the default logging priority.
	InfoLevel
	// WarnLevel logs are more important than Info, but don't need individual
	// human review.
	WarnLevel
	// ErrorLevel logs are high-priority. If an application is running smoothly,
	// it shouldn't generate any error-level logs.
	ErrorLevel
	// ClosedLevel logs output nothing.
	ClosedLevel = math.MaxInt8
)

func (Level) String

func (l Level) String() string

String returns a lower-case ASCII representation of the log level.

type LevelStore

type LevelStore interface {
	// Get provide the lowest logging Level that a Logger can support by name.
	Get(name string) Level
	// Set update the lowest logging Level that a Logger can support by name.
	// If this method is called more than once, the last call wins.
	Set(name string, level Level)
	// UnSet clear the set lowest logging Level that a Logger can support by
	// name.
	UnSet(name string)
}

LevelStore stores and provides the lowest logging Level limit of a Logger by name.

func GetLevelStore

func GetLevelStore() LevelStore

GetLevelStore returns the registered LevelStore for use by default. Nil may be returned, if no LevelStore is registered or the registered LevelStore has be cleared.

func NewStdLevelStore

func NewStdLevelStore(opts ...StdLevelStoreOption) LevelStore

NewStdLevelStore create a LevelStore.

type Logger

type Logger interface {
	// AtLevel get a Printer wrapping the provided context.Context at specified
	// logging Level. If the Level is not enabled to the Logger, nothing will be
	// print when calling the Print functions of returned Printer.
	AtLevel(level Level, ctx context.Context) Printer
}

Logger represents a logger that can provide Printers. A Logger has a name, and there may be a lower limit of logging Level the Logger supported.

func Get

func Get(name string) Logger

Get return a Logger by name.

func NewNopLogger

func NewNopLogger() Logger

NewNopLogger returns a Logger who's AtLevel method always return a Nop Printer.

func NewStdLogger

func NewStdLogger(name string, output Output) Logger

NewStdLogger create a Logger by name. The Logger returned will use the provided Output to print logging messages.

type LoggerProvider

type LoggerProvider func(name string) Logger

LoggerProvider is provider function that provide a non-nil Logger by name.

func NewStdLoggerProvider

func NewStdLoggerProvider(output Output) LoggerProvider

NewStdLoggerProvider make a LoggerProvider which produce Logger via NewStdLogger function.

type Output

type Output interface {
	// Output output msg, fields at a specific level to the underlying
	// logging / printing infrastructures.
	Output(ctx context.Context, level Level, msg string, fields []Field, addCallerSkip int)
}

Output is the real final output of builtin standard Logger and Printer. It calls the underlying logging / printing infrastructures.

func NewStdOutput

func NewStdOutput(out *log.Logger) Output

NewStdOutput create a Output based on Go SDK log.Logger. It output to the provided log.Logger.

type Printer

type Printer interface {
	// Print formats using the default formats for its operands and writes
	// result as message value.
	// Spaces are added between operands when neither is a string.
	// The message value and other key/value carried by the Printer will be
	// passed to the implementing logging layer together.
	Print(v ...interface{})
	// Printf formats according to a format specifier and writes result as
	// message value.
	// The message value and other key/value carried by the Printer will be
	// passed to the implementing logging layer together.
	Printf(format string, v ...interface{})
	// Println formats using the default formats for its operands and writes
	// result as message value.
	// Spaces are always added between operands.
	// The message value and other key/value carried by the Printer will be
	// passed to the implementing logging layer together.
	Println(v ...interface{})
	// With add key/value pair to the Printer. If the key is already exist,
	// the existing value will be override by the given value. So users should
	// not use these internally used keys: logger, level, and so on.
	// Depending on the implementation, the key `caller` (and some other keys,
	// please refer the manual of the implementation) may should be avoid, since
	// the caller key/value pair may be added by the implementation.
	With(key string, value interface{}) Printer
}

Printer represents a stateful printer that is at specific level, carrying fields including logger name. It also usually carry a context.Context for the Value calculation. Users are expected NEVER new a Printer instance by hand. It's usually got from a Logger and left/throw away after doing print. NEVER share a Printer between methods and goroutines.

func NewNopPrinter

func NewNopPrinter() Printer

NewNopPrinter returns a Printer which print nothing.

type StdLevelStoreOption

type StdLevelStoreOption func(ls *stdLevelStore)

StdLevelStoreOption is option for NewStdLevelStore constructor function.

func LoggerLevel

func LoggerLevel(name string, level Level) StdLevelStoreOption

LoggerLevel is a option which define Level for name.

func RootLevel

func RootLevel(level Level) StdLevelStoreOption

RootLevel is a option which define the root Level.

type Valuer

type Valuer func(ctx context.Context) interface{}

Valuer is function that calculating real value at call time. Note that the ctx may be nil.