logfmtr

README

logfmtr

An implementation of the logr minimal logging API that writes in logfmt style.

Getting Started

This is a no frills logging package that follows the logr minimal logging API and by default writes logs in logfmt format, a line of space delimited key/value pairs.

level=0 logger=MyName ts=2020-09-20T14:31:10.905267839Z msg=hello user=you val1=1 val2=map[k:1]
level=1 logger=MyName ts=2020-09-20T14:31:10.905279546Z msg="you should see this" user=you
level=0 logger=MyName ts=2020-09-20T14:31:10.905288008Z msg="uh oh" error=<nil> user=you trouble=true reasons="[0.1 0.11 3.14]"
level=0 logger=MyName ts=2020-09-20T14:31:10.905291479Z msg=goodbye error="an error occurred" user=you code=-1

A more human friendly output format is also provided which can be configured using the humanize option:

0 info  | 14:31:10.905297 | hello                          logger=MyName user=you val1=1 val2=map[k:1]
1 info  | 14:31:10.905302 | you should see this            logger=MyName user=you
0 error | 14:31:10.905307 | uh oh                          logger=MyName error=<nil> user=you trouble=true reasons="[0.1 0.11 3.14]"
0 error | 14:31:10.905311 | goodbye                        logger=MyName error="an error occurred" user=you code=-1

Loggers defer applying their configuration until they are used. The logger is instantiated when either Info, Error or Enabled is called. At that point the logger will read and use any options set from a prior call to UseOptions.

package main

import (
    "github.com/iand/logfmtr"
)

func main() {
    // Set options that all loggers will be based on
    opts := logfmtr.DefaultOptions()
    opts.Humanize = true
    opts.AddCaller = true
    logfmtr.UseOptions(opts)
}

Any new loggers will use the options set in main when they first start logging.

package worker

import (
    "github.com/iand/logfmtr"
)

// Create the logger
var logger = logfmtr.New().WithName("worker")


func doWork() }
    // Logger is instantiated with the options set earlier
    logger.Info("the sun is shining")
}

Loggers can be created with specific configuration by using NewWithOptions:

func otherWork() }
    opts := logfmtr.DefaultOptions()
    opts.Writer = os.Stderr

    logger := logfmtr.NewWithOptions(opts)
    logger.Info("important system information")
}

Several predefined keys are used when writing logs in logfmt style:

• msg - the log message
• error - error message passed to the Error method
• logger - the name of the logger writing the log entry
• level - the verbosity level of the logger writing the log entry
• caller - filename and line number of the origin of the log entry

Author

• Ian Davis - http://iandavis.com/

License

This is free and unencumbered software released into the public domain. Anyone is free to copy, modify, publish, use, compile, sell, or distribute this software, either in source code form or as a compiled binary, for any purpose, commercial or non-commercial, and by any means. For more information, see http://unlicense.org/ or the accompanying UNLICENSE file.

Documentation

Index

• func DisableLogger(name string)
• func EnableLogger(name string)
• func New() logr.Logger
• func NewNamed(name string) logr.Logger
• func NewWithOptions(opts Options) logr.Logger
• func SetVerbosity(v int) int
• func UseOptions(opts Options)
• type Options
  • func DefaultOptions() Options

Examples

• DisableLogger
• New
• NewNamed
• NewWithOptions

Functions

func DisableLogger

func DisableLogger(name string)

Example

package main

import (
	"github.com/iand/logfmtr"
)

func main() {
	// Create the logger with a name
	logger := logfmtr.NewNamed("europa")

	// It logs normally
	logger.Info("the sun is shining")

	// Disable the logger
	logfmtr.DisableLogger("europa")

	logger.Info("the sun not shining now")
}

func EnableLogger

func EnableLogger(name string)

func New

func New() logr.Logger

New returns a deferred logger that writes in logfmt using the default options. The logger defers configuring its options until it is instantiated with the first call to Info, Error or Enabled or the first call to those function on any child loggers created via V, WithName or WithValues.

Example

package main

import (
	"github.com/iand/logfmtr"
)

func main() {
	// Create the logger with deferred options
	logger := logfmtr.New()

	// Later on set options that all loggers will be based on
	opts := logfmtr.DefaultOptions()
	opts.Humanize = true
	logfmtr.UseOptions(opts)

	// Logger is instantiated with the options
	logger.Info("the sun is shining")
}

func NewNamed

func NewNamed(name string) logr.Logger

NewNamed returns a deferred logger with the given name that writes in logfmt using the default options.

Example

package main

import (
	"github.com/iand/logfmtr"
)

func main() {
	// Create the logger with a name
	logger := logfmtr.NewNamed("europa")

	logger.Info("the sun is shining")
}

func NewWithOptions

func NewWithOptions(opts Options) logr.Logger

NewWithOptions returns an instantiated logger that writes in logfmt using the supplied options. Panics if no writer is supplied in the options.

Example

package main

import (
	"github.com/iand/logfmtr"
)

func main() {
	opts := logfmtr.DefaultOptions()
	opts.Humanize = true
	logger := logfmtr.NewWithOptions(opts)
	logger.Info("the sun is shining")
}

func SetVerbosity

func SetVerbosity(v int) int

SetVerbosity sets the global log level. Only loggers with a V level less than or equal to this value will be enabled.

func UseOptions

func UseOptions(opts Options)

UseOptions sets options that new loggers will use when it they are instantiated.

Types

type Options

type Options struct {
	// Writer is where logs will be written to
	Writer io.Writer

	// Humanize changes the log output to a human friendly format
	Humanize bool

	// Colorize adds color to the log output. Only applies if Humanize is also true.
	Colorize bool

	// TimestampFormat sets the format for log timestamps. Set to empty to disable timestamping
	// of log messages. Humanize uses a fixed short timestamp format.
	TimestampFormat string

	// NameDelim is the delimiter character used when appending names of loggers.
	NameDelim string

	// AddCaller indicates that log messages should include the file and line number of the caller of the logger.
	AddCaller bool

	// CallerSkip adds frames to skip when determining the caller of the logger. Useful when the logger is wrapped
	// by another logger.
	CallerSkip int

	// Timezone indicates that timestamps use your local timezone instead of UTC
	Timezone bool
}

Options contains fields and flags for customizing logger behaviour

func DefaultOptions

func DefaultOptions() Options

DefaultOptions returns the default options used by New unless overridden by a call to UseOptions. Override the option field to customise behaviour and then pass to UseOptions or NewWithOptions.