logging

README

Logging

The package defines the logging API used in CN-Infra. The default logger implementation is based on the Logrus library.

Documentation

Overview

Package logging defines the logging API. It used by all plugins, and supports multiple log levels (severities) and various log message formats.

Index

• Variables
• type Fields
• type LogLevel
  • func ParseLogLevel(level string) LogLevel
  • func (level LogLevel) String() string
• type LogWithLevel
• type Logger
• type LoggerFactory
• type ParentLogger
  • func NewParentLogger(name string, factory LoggerFactory) *ParentLogger
  • func (p *ParentLogger) NewLogger(name string) Logger
• type PluginLogger
  • func ForPlugin(name string) PluginLogger
• type Registry

Variables

var (
	// DefaultLogger is the default logger
	DefaultLogger Logger

	// DefaultRegistry is the default logging registry
	DefaultRegistry Registry
)

Types

type Fields

type Fields map[string]interface{}

Fields is a type accepted by WithFields method. It can be used to instantiate map using shorter notation.

type LogLevel

type LogLevel uint32

LogLevel represents severity of log record

const (
	// PanicLevel - highest level of severity. Logs and then calls panic with the message passed in.
	PanicLevel LogLevel = iota
	// FatalLevel - logs and then calls `os.Exit(1)`.
	FatalLevel
	// ErrorLevel - used for errors that should definitely be noted.
	ErrorLevel
	// WarnLevel - non-critical entries that deserve eyes.
	WarnLevel
	// InfoLevel - general operational entries about what's going on inside the application.
	InfoLevel
	// DebugLevel - enabled for debugging, very verbose logging.
	DebugLevel
)

func ParseLogLevel

func ParseLogLevel(level string) LogLevel

ParseLogLevel parses string representation of LogLevel.

func (LogLevel) String

func (level LogLevel) String() string

String converts the LogLevel to a string. E.g. PanicLevel becomes "panic".

type LogWithLevel

type LogWithLevel interface {
	Debug(args ...interface{})
	Debugf(format string, args ...interface{})
	Info(args ...interface{})
	Infof(format string, args ...interface{})
	Warn(args ...interface{})
	Warnf(format string, args ...interface{})
	Error(args ...interface{})
	Errorf(format string, args ...interface{})
	Fatal(args ...interface{})
	Fatalf(format string, args ...interface{})
	Fatalln(args ...interface{})
	Panic(args ...interface{})
	Panicf(format string, args ...interface{})

	Print(v ...interface{})
	Printf(format string, v ...interface{})
	Println(v ...interface{})
}

LogWithLevel allows to log with different log levels

type Logger

type Logger interface {
	// GetName returns the logger name
	GetName() string
	// SetLevel modifies the log level
	SetLevel(level LogLevel)
	// GetLevel returns currently set log level
	GetLevel() LogLevel
	// WithField creates one structured field
	WithField(key string, value interface{}) LogWithLevel
	// WithFields creates multiple structured fields
	WithFields(fields Fields) LogWithLevel
	// Add hook to send log to external address
	AddHook(hook logrus.Hook)
	// SetOutput sets output writer
	SetOutput(out io.Writer)
	// SetFormatter sets custom formatter
	SetFormatter(formatter logrus.Formatter)

	LogWithLevel
}

Logger provides logging capabilities

type LoggerFactory

type LoggerFactory interface {
	NewLogger(name string) Logger
}

LoggerFactory is API for the plugins that want to create their own loggers.

type ParentLogger

type ParentLogger struct {
	Logger
	Prefix  string
	Factory LoggerFactory
}

ParentLogger provides logger with logger factory that creates loggers with prefix.

func NewParentLogger

func NewParentLogger(name string, factory LoggerFactory) *ParentLogger

NewParentLogger creates new parent logger with given LoggerFactory and name as prefix.

func (*ParentLogger) NewLogger

func (p *ParentLogger) NewLogger(name string) Logger

NewLogger returns logger using name prefixed with prefix defined in parent logger. If Factory is nil, DefaultRegistry is used.

type PluginLogger

type PluginLogger interface {
	// Plugin has by default possibility to log
	// Logger name is initialized with plugin name
	Logger
	// LoggerFactory can be optionally used by large plugins
	// to create child loggers (their names are prefixed by plugin logger name)
	LoggerFactory
}

PluginLogger is intended for: 1. small plugins (that just need one logger; name corresponds to plugin name) 2. large plugins that need multiple loggers (all loggers share same name prefix)

func ForPlugin

func ForPlugin(name string) PluginLogger

ForPlugin is used to initialize plugin logger by name and optionally created children (their name prefixed by plugin logger name)

type Registry

type Registry interface {
	// LoggerFactory allow to create new loggers
	LoggerFactory
	// List Loggers returns a map (loggerName => log level)
	ListLoggers() map[string]string
	// SetLevel modifies log level of selected logger in the registry
	SetLevel(logger, level string) error
	// GetLevel returns the currently set log level of the logger from registry
	GetLevel(logger string) (string, error)
	// Lookup returns a logger instance identified by name from registry
	Lookup(loggerName string) (logger Logger, found bool)
	// ClearRegistry removes all loggers except the default one from registry
	ClearRegistry()
	// HookConfigs stores hooks from log manager to be used for new loggers
	AddHook(hook logrus.Hook)
}

Registry groups multiple Logger instances and allows to mange their log levels.