Documentation ¶
Overview ¶
Package xlog implements a sofisticated logging package.
### Quick Start
When importing xlog, logging is can be used right away:
package main import "github.com/geertjanvdk/xkit/xlog" func main() { xlog.Info("I am an informational.") }
It is possible to add fields as well as error or a scope:
package main import "github.com/geertjanvdk/xkit/xlog" func main() { if err := createUser(user); err != nil { xlog.WithError(err).Errorf("creating user for %s", appName) } else { xlog.WithScope("users").WithField("user", user.ID).Infof("user created") } }
### Setting Logging Levels
xlog does not support the classic way of setting the level of logging. Normally, when you set log level WARN, nothing informational is written, and only errors are reported.
In xlog levels are activated, so that the application can choose which are logged in a dynamic manner.
For example: an application is running and has the defaults set. This means that informational, warning, and error messages are logged, as well as fatal or terminating events. When, however, the developers need for a shor time to have debugging enabled (for example in staging environments), they can do so by activating the debug level.
xlog.ActivateLevel(xlog.DebugLevel)
How this is dynamically done is up to the application. It could be possible to have a process signal, an API call, or as simple as creating a file in a specific folder.
Deactivating is simply done using using the Deactivate method:
xlog.DeactivateLevel(xlog.DebugLevel)
### Custom Loggers
xlog comes with a logger. It is however more practical for applications to instantiate their own, and customize it.
package main import "github.com/geertjanvdk/xkit/xlog" func main() { logger := xlog.New() logger.DeactivateLevels(xlog.WarnLevel, xlog.InfoLevel) logger.Scope = "my-app" logger.Errorf("only errors are logged (and fatal events)") }
Index ¶
- Constants
- func ActivateLevels(levels ...Level)
- func DeactivateLevels(levels ...Level)
- func Debug(a ...interface{})
- func Debugf(format string, a ...interface{})
- func Error(a ...interface{})
- func Errorf(format string, a ...interface{})
- func GetOut() io.Writer
- func Info(a ...interface{})
- func Infof(format string, a ...interface{})
- func LevelsAsStrings() []string
- func Panic(a ...interface{})
- func Panicf(format string, a ...interface{})
- func SetFormatter(f Formatter)
- func SetOut(w io.Writer)
- func Warn(a ...interface{})
- func Warnf(format string, a ...interface{})
- type Entry
- func (e *Entry) Debug(a ...interface{})
- func (e *Entry) Debugf(format string, a ...interface{})
- func (e *Entry) Error(a ...interface{})
- func (e *Entry) Errorf(format string, a ...interface{})
- func (e *Entry) Fatal(a ...interface{})
- func (e *Entry) Fatalf(format string, a ...interface{})
- func (e *Entry) Info(a ...interface{})
- func (e *Entry) Infof(format string, a ...interface{})
- func (e *Entry) Panic(a ...interface{})
- func (e *Entry) Panicf(format string, a ...interface{})
- func (e *Entry) String() string
- func (e *Entry) UnmarshalJSON(data []byte) error
- func (e *Entry) Warn(a ...interface{})
- func (e *Entry) Warnf(format string, a ...interface{})
- func (e *Entry) WithError(err error) *Entry
- func (e *Entry) WithField(name string, value interface{}) *Entry
- func (e *Entry) WithFields(fields Fields) *Entry
- func (e *Entry) WithScope(scope string) *Entry
- type Fields
- type Formatter
- type JSONFormat
- type Level
- type Logger
- func (l *Logger) ActivateLevels(levels ...Level)
- func (l *Logger) DeactivateLevels(levels ...Level)
- func (l *Logger) Debug(a ...interface{})
- func (l *Logger) Debugf(format string, a ...interface{})
- func (l *Logger) Error(a ...interface{})
- func (l *Logger) Errorf(format string, a ...interface{})
- func (l *Logger) Fatal(a ...interface{})
- func (l *Logger) Fatalf(format string, a ...interface{})
- func (l *Logger) Info(a ...interface{})
- func (l *Logger) Infof(format string, a ...interface{})
- func (l *Logger) Levels() []Level
- func (l *Logger) LevelsAsStrings() []string
- func (l *Logger) Log(level Level, a ...interface{})
- func (l *Logger) Logf(level Level, format string, a ...interface{})
- func (l *Logger) NewEntry() *Entry
- func (l *Logger) Panic(a ...interface{})
- func (l *Logger) Panicf(format string, a ...interface{})
- func (l *Logger) Print(v ...interface{})
- func (l *Logger) Printf(format string, v ...interface{})
- func (l *Logger) SetFormatter(f Formatter)
- func (l *Logger) Warn(a ...interface{})
- func (l *Logger) Warnf(format string, a ...interface{})
- func (l *Logger) WithError(err error) *Entry
- func (l *Logger) WithField(name string, value interface{}) *Entry
- func (l *Logger) WithFields(fields Fields) *Entry
- type TextFormat
- type TextFormatType
Constants ¶
const ( FieldError = "err" FieldErrCode = "errCode" FieldTime = "time" FieldLevel = "level" FieldMsg = "msg" FieldScope = "scope" FieldFileLine = "fileInfo" FieldStack = "debugStack" )
Variables ¶
This section is empty.
Functions ¶
func ActivateLevels ¶
func ActivateLevels(levels ...Level)
ActivateLevels is used to activate particular levels of the default logger. For example, ActivateLevels(DebugLevel) can be used if the logger logs errors, but debug message are wanted, without info messages.
func DeactivateLevels ¶
func DeactivateLevels(levels ...Level)
DeactivateLevels is used to deactivate particular levels of the default logger. For example, DeactivateLevels(DebugLevel) can be used to deactivate all debugging messages.
func Debug ¶
func Debug(a ...interface{})
Debug logs a debug entry using the default logger formatting using provided operands.
func Debugf ¶
func Debugf(format string, a ...interface{})
Debugf logs a debug entry using the default logger formatting according to a format specifier and operands.
func Error ¶
func Error(a ...interface{})
Error logs an error entry using the default logger formatting using provided operands.
func Errorf ¶
func Errorf(format string, a ...interface{})
Errorf logs an error entry using the default logger formatting according to a format specifier and operands.
func Info ¶
func Info(a ...interface{})
Info logs a informational entry using the default logger formatting using provided operands.
func Infof ¶
func Infof(format string, a ...interface{})
Infof logs a informational entry using the default logger formatting according to a format specifier and operands.
func LevelsAsStrings ¶
func LevelsAsStrings() []string
LevelsAsStrings returns the active levels their names. The result is sorted.
func Panic ¶
func Panic(a ...interface{})
Panic simply panics and formats the message using provided operands.
func Panicf ¶
func Panicf(format string, a ...interface{})
Panicf simply panics and formats the message according to a format specifier and operands.
func SetFormatter ¶
func SetFormatter(f Formatter)
SetFormatter sets the formatter of the default logger.
Types ¶
type Entry ¶
type Entry struct { Fields Fields // contains filtered or unexported fields }
func WithError ¶
WithError returns an Entry for the default logger which has a field set with value of err. The name of the field is defined as xlog.FieldError.
func WithField ¶
WithField returns an Entry for the default logger which has field set using name and value.
func WithFields ¶
WithFields returns an Entry for the default logger which has all fields set.
func WithScope ¶
WithScope returns an Entry for the default logger which has a field set with value of scope. The name of the field is defined as xlog.FieldScope.
func (*Entry) String ¶
String returns the textual representation serialized by the logger's formatter.
func (*Entry) UnmarshalJSON ¶
func (*Entry) WithFields ¶
type Fields ¶
type Fields map[string]interface{}
Fields is used to add extra, custom fields to a log entry.
func (Fields) MarshalJSON ¶
type Formatter ¶
func GetFormatter ¶
func GetFormatter() Formatter
GetFormatter returns the formatter of the default logger.
type JSONFormat ¶
type JSONFormat struct { FormatType TextFormatType // contains filtered or unexported fields }
type Level ¶
type Level int
type Logger ¶
type Logger struct { Out io.Writer Formatter Formatter Scope string UseUTC bool // contains filtered or unexported fields }
func (*Logger) ActivateLevels ¶
ActivateLevels is used to activate particular levels of l. For example, ActivateLevels(DebugLevel) can be used if the logger logs errors, but debug message are wanted, without info messages.
func (*Logger) DeactivateLevels ¶
DeactivateLevels is used to deactivate particular levels of l. For example, DeactivateLevels(DebugLevel) can be used to deactivate all debugging messages.
func (*Logger) LevelsAsStrings ¶
LevelsAsStrings returns the active levels their names. The result is sorted.
func (*Logger) Logf ¶
Logf logs according to a format specifier, and optional arguments, for given level.
func (*Logger) SetFormatter ¶
SetFormatter sets f as formatter for l.
func (*Logger) WithError ¶
WithError returns an entry with value of field 'error' set to err. This is the same as calling Logger.WithField(FieldError, err).
func (*Logger) WithFields ¶
type TextFormat ¶
type TextFormat struct { FormatType TextFormatType TimeFormat string // defaults to (tf *TextFormat) }
type TextFormatType ¶
type TextFormatType int
const ( TextFullFields TextFormatType = iota + 1 TextCompat )