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

• type Fields
• type LogFactory
• type LogLevel
  • func (level LogLevel) String() string
• type LogWithLevel
• type Logger
• type PluginLogger
  • func ForPlugin(name string, factory LogFactory) PluginLogger
• type 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 LogFactory

type LogFactory interface {
	NewLogger(name string) Logger
}

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

type LogLevel

type LogLevel int

LogLevel represents severity of log record

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

func (LogLevel) String

func (level LogLevel) String() string

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

type LogWithLevel

type LogWithLevel interface {
	// Debug logs using Debug level
	Debug(args ...interface{})
	// Debugf prints formatted log using Debug level
	Debugf(format string, args ...interface{})
	// Info logs using Info level
	Info(args ...interface{})
	// Infof prints formatted log using Info level
	Infof(format string, args ...interface{})
	// Warning logs using Warning level
	Warn(args ...interface{})
	// Warnf prints formatted log using Warn level
	Warnf(format string, args ...interface{})
	// Error logs using Error level
	Error(args ...interface{})
	// Errorf prints formatted log using Error level
	Errorf(format string, args ...interface{})
	// Panic logs using Panic level and panics
	Panic(args ...interface{})
	// Panicf prints formatted log using Panic level and panic
	Panicf(format string, args ...interface{})
	// Fatal logs using Fatal level and calls os.Exit(1)
	Fatal(args ...interface{})
	// Fatalf prints formatted log using Fatal level and calls os.Exit(1)
	Fatalf(format string, args ...interface{})
	Fatalln(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 {
	LogWithLevel
	// SetLevel modifies the LogLevel
	SetLevel(level LogLevel)
	// GetLevel returns currently set logLevel
	GetLevel() LogLevel
	// WithField creates one structured field
	WithField(key string, value interface{}) LogWithLevel
	// WithFields creates multiple structured fields
	WithFields(fields map[string]interface{}) LogWithLevel

	// GetName return the logger name
	GetName() string
}

Logger provides logging capabilities

type PluginLogger

type PluginLogger interface {
	// Plugin has by default possibility to log
	// Logger name is initialized with plugin name
	Logger

	// LogFactory can be optionally used by large plugins
	// to create child loggers (their names are prefixed by plugin logger name)
	LogFactory
}

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, factory LogFactory) PluginLogger

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

Example usage:

   flavor.ETCD.Logger =
			ForPlugin(PluginNameOfFlavor(&flavor.ETCD, flavor), flavor.Logrus)

type Registry

type Registry interface {
	// LogFactory allow to create new loggers
	LogFactory
	// 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()
}

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