liblog

package module
v1.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Apr 6, 2022 License: Apache-2.0 Imports: 6 Imported by: 5

README

liblog

liblog is an interface/contract for logging backends. It should be used by public libraries and packages that want to give their user's control over structured and leveled logging output.

Go Reference

Advantages
  • 🟢 Users can provide their own logging stack and get detailed package-level logging
  • 🟢 liblog provides implementations for well-known logging backends (see /impl)
Getting started
  • go get github.com/harwoeck/liblog - provides the liblog interface, and an implementation that only relies on Go's standard library
  • Use liblog.NewStd(...StdOption) by default inside your package, but give users the option to specify their own logging implementation (liblog.Logger)
Usage
  • Extensively use all provided options, like Named(), With() and appropriate logging levels, to provide the best log results/experience.
  • Use field() (or liblog.NewField()) to generate structured elements for your logs (see Tips #1)
Tips
  1. Create a file logfield.go and add this fieldImpl. You can now use field() instead of the longer liblog.NewField() inside your package to create structured logging elements
    type fieldImpl struct {
        key   string
        value interface{}
    }
    
    func (f *fieldImpl) Key() string        { return f.key }
    func (f *fieldImpl) Value() interface{} { return f.value }
    
    func field(key string, value interface{}) contract.Field {
        return &fieldImpl{
            key:   key,
            value: value,
        }
    }
    

Documentation

Overview

Package liblog provides a common interface for logging backends

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func FormatToError

func FormatToError(name string, callerSkip int, msg string, fields ...Field) error

FormatToError is a public helper function that converts msg and fields info into a combined error. Intended for Logger.ErrorReturn

Types

type Field

type Field interface {
	// Key returns the fields key part
	Key() string
	// Value returns the fields value part
	Value() interface{}
}

A Field is a marshaling operation used to add a key-value pair to a logger's context

func NewField

func NewField(key string, value interface{}) Field

NewField provides a simple shortcut function to create a struct that satisfies the Field interface

type Level

type Level int8

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
	// DPanicLevel logs are particularly important errors. In development the
	// logger panics after writing the message.
	DPanicLevel
	// PanicLevel logs a message, then panics.
	PanicLevel
	// FatalLevel logs a message, then calls os.Exit(1).
	FatalLevel
)

func (Level) String

func (l Level) String() string

String returns a readable representation of Level

type Logger

type Logger interface {
	// Named adds a new path segment to the logger's name. Segments are joined by
	// periods. By default, Loggers are unnamed.
	Named(name string) Logger
	// With creates a child logger and adds structured context to it. Fields added
	// to the child don't affect the parent, and vice versa.
	With(fields ...Field) Logger
	// Sync flushes any buffered log entries and should be called by applications
	// before exiting
	Sync() error
	// Debug logs a message at DebugLevel. The message includes any fields passed
	// at the log site, as well as any fields accumulated on the logger.
	Debug(msg string, fields ...Field)
	// Info logs a message at InfoLevel. The message includes any fields passed
	// at the log site, as well as any fields accumulated on the logger.
	Info(msg string, fields ...Field)
	// Warn logs a message at WarnLevel. The message includes any fields passed
	// at the log site, as well as any fields accumulated on the logger.
	Warn(msg string, fields ...Field)
	// Error logs a message at ErrorLevel. The message includes any fields passed
	// at the log site, as well as any fields accumulated on the logger.
	Error(msg string, fields ...Field)
	// ErrorReturn logs a message at ErrorLevel exactly like the Error function, but
	// additionally returns an error object, containing the provided information.
	ErrorReturn(msg string, fields ...Field) error
	// DPanic logs a message at DPanicLevel. The message includes any fields
	// passed at the log site, as well as any fields accumulated on the logger.
	//
	// If the logger is in development mode, it then panics (DPanic means
	// "development panic"). This is useful for catching errors that are
	// recoverable, but shouldn't ever happen.
	DPanic(msg string, fields ...Field)
	// Panic logs a message at PanicLevel. The message includes any fields passed
	// at the log site, as well as any fields accumulated on the logger.
	//
	// The logger then panics, even if logging at PanicLevel is disabled.
	Panic(msg string, fields ...Field)
	// Fatal logs a message at FatalLevel. The message includes any fields passed
	// at the log site, as well as any fields accumulated on the logger.
	//
	// The logger then calls os.Exit(1), even if logging at FatalLevel is
	// disabled.
	Fatal(msg string, fields ...Field)
}

Logger provides leveled, structured logging. It is an abstract interface for different logging backends.

func MustNewStd

func MustNewStd(opts ...StdOption) Logger

MustNewStd is like NewStd, but panics if one of the StdOption cannot be applied.

func NewStd

func NewStd(opts ...StdOption) (Logger, error)

NewStd creates a new Logger using only Go's standard library. This can be useful for packages that want to include liblog, and provide logging output by default, but not overstuff their library with third-party dependencies.

type StdOption

type StdOption func(*logger) error

StdOption is an option function for NewStd and MustNewStd

func DisableLogWrites

func DisableLogWrites() StdOption

DisableLogWrites fully disables the logger instance. No message is written to the OutWriter and ErrWriter.

func ErrWriter

func ErrWriter(w io.Writer) StdOption

ErrWriter lets you set the destination for errors that happened inside the standard logger itself (which at the moment can only happen if the OutWriter returns an error on writing)

func IsInDevEnvironment

func IsInDevEnvironment(isInDevEnvironment bool) StdOption

IsInDevEnvironment influences whether DPanicLevel panics or not

func MinLevel

func MinLevel(minLevel Level) StdOption

MinLevel sets the minimum needed level for messages that get written to OutWriter. Messages below this level will get discarded

func OutWriter

func OutWriter(w io.Writer) StdOption

OutWriter lets you set the destination for the default logging output

Directories

Path Synopsis
contract module
impl
zapimpl Module
zerologimpl Module

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL