llog

Documentation

Overview

Package llog provides logging utilities for library packages.

This allows libraries to log if desired, while still allowing the library functions to have no side effects and not use global loggers, which may be different than the application's primary log library.

This also allows users of the library to decide their logging level for this particular library. For example, an application may wish to generally log at the debug level, but not log debug messages for some particular library.

Or, a user may wish to log warning messages from a library as errors. Setting two log levels to the same io.Writer is permissible.

This is not itself a logging library. Rather, it allows applications using any log library to interface with libraries using llog, by constructing a Loggers object from their own logger.

Index

• type Log
  • func LibInit(lg Log) Log
  • func New(err io.Writer, warn io.Writer, info io.Writer, debug io.Writer) Log
  • func Nop() Log
• type WriterFunc
  • func (wf WriterFunc) Write(p []byte) (n int, err error)

Types

type Log

type Log interface {
	Errorf(format string, v ...interface{})
	Errorln(v ...interface{})
	Warnf(format string, v ...interface{})
	Warnln(v ...interface{})
	Infof(format string, v ...interface{})
	Infoln(v ...interface{})
	Debugf(format string, v ...interface{})
	Debugln(v ...interface{})
}

Log is an interface which library functions may accept in order to log without side effects, if the caller desires.

Applications using a library which uses Log may use NewLog, or may themselves implement the interface.

Library functions should immediately call DefaultIfNil to allow callers to pass a nil Log. Importantly, this allows applications using the library to avoid importing llog, if they don't want the library to log.

func LibInit

func LibInit(lg Log) Log

LibInit initializes the Log for libraries.

All public functions in Libraries using llog should immediately call LibInit. The return value should be assigned, like `log = llog.LibInit(log)`

Applications creating a Log to pass to a library func should never call LibInit.

This creates a Nop Log if the passed lg is nil, which allows applications to pass a nil Log.

It may do other things in the future.

func New

func New(err io.Writer, warn io.Writer, info io.Writer, debug io.Writer) Log

New creates a new Log.

Applications can use New to create a Log from their own internal log libraries and writers, to pass to libraries using liblog.

Standard log example:

errLog := log.New(os.Stdout, "ERROR: ", log.Ldate|log.Ltime|log.Lshortfile)
mylib.MyFunc(liblog.New(errLog, nil, nil, nil), myArg)

github.com/apache/trafficcontrol/v8/lib/go-log example:

import("github.com/apache/trafficcontrol/v8/lib/go-log")

log.Init(nil, os.Stderr, os.Stderr, nil, nil)

lLog := log.LLog() // lib/go-tc has a built-in llog helper

// alternatively, what the lib/go-log helper is doing internally:
ltow := func(lg *log.Logger) io.Writer {
  return llog.WriterFunc(func(p []byte) (n int, err error) {
  Logln(lg, string(p))
})
lLog = llog.New(ltow(Error), ltow(Warning), ltow(Info), ltow(Debug))

mylib.MyFunc(lLog, myArg)

zap example:

import("go.uber.org/zap")

func main() {
  logger, _ := zap.NewProduction()
  sugar := logger.Sugar()
  zapErrLog := liblog.WriterFunc(func(p []byte) (n int, err error){
    logger.Sugar().Error(string(p))
  })
  mylib.MyFunc(liblog.New(zapErrLog, nil, nil, nil), myArg)
}

func Nop

func Nop() Log

Nop returns a Log that never logs. Applications which don't want a library to log can pass Nop to libraries that take a Log.

type WriterFunc

type WriterFunc func(p []byte) (n int, err error)

WriterFunc is an adapter to allow the use of ordinary functions as io.Writers. This behaves similar to http.HandlerFunc for http.Handler.

func (WriterFunc) Write

func (wf WriterFunc) Write(p []byte) (n int, err error)

Write implements io.Writer.