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 RegisterLevelName(level Level, name string)
• func ResetLevelNames()
• func UseManager(mng Manager)
• func Value(ctx context.Context, v interface{}) interface{}
• type Level
  • func (l Level) String() string
• type Logger
  • func Get(name string) Logger
• type Manager
  • func GetManager() (Manager, error)
  • func NewManager(out *log.Logger, opts ...Option) Manager
• type Option
  • func LoggerLevel(name string, level Level) Option
  • func RootLevel(level Level) Option
• type Printer
• type Valuer

Constants

const (
	LevelKey  = "level"
	LoggerKey = "logger"
)

Functions

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 UseManager

func UseManager(mng Manager)

UseManager register a Manager to use. If this function is called more than once, the last call wins. Note that, all got Loggers before UseManager call have no relation with the new registered Manager, you can not control their behaviors after you call this function.

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 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 Logger

type Logger interface {
	// LevelEnabled indicates whether the Logger can output line at the provided
	// level.
	LevelEnabled(level Level) bool
	// Printer get a Printer wrapping the provided context.Context.
	// The Level of Printer returned is InfoLevel.
	// If Logger does not enable InfoLevel, nothing will be print when calling
	// the Print functions of returned Printer.
	Printer(ctx ...context.Context) Printer
	// Name returns the name of the Logger.
	Name() string
	// 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 from registered Manager. If none Manager is registered, it return a new built logger, and note that, you can not control the returned new built logger's behaviors, so you'd better always call UseManager registering a valid Manager before call this function. Note that, this method will never refill the registered Manager if absent.

type Manager

type Manager interface {
	// Get returns a Logger of name from the Manager.
	// If no logger of the provided name is configured, a parent or default
	// Logger should be returned. Refer to the manual of implementations.
	Get(name string) Logger
	// Level set logging Level for logger of name.
	// If you call this function with same name more than once, the last call
	// wins.
	Level(name string, level Level)
}

Manager represents a Logger manager. It provides Logger by name.

func GetManager

func GetManager() (Manager, error)

GetManager returns the registered Manager to use. If none Manager is registered, it will return a none nil error.

func NewManager

func NewManager(out *log.Logger, opts ...Option) Manager

NewManager build and return a Manager.

type Option

type Option func(m *manager)

Option is options for NewManager.

func LoggerLevel

func LoggerLevel(name string, level Level) Option

LoggerLevel produce one Option which set Level of name.

func RootLevel

func RootLevel(level Level) Option

RootLevel produce one Option which set Level of root 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
	// WithContext set or override the context.Context carried by the Printer.
	WithContext(ctx context.Context) 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.

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.