logf

README

logf

appkit/logf is a tool for formatted, deterministic application logging.

• Formatted: logf provides extensible formatting tools, and supports structured (kvp, json) and non-structured (both standard syslog RFCs) out-of-the-box
• Deterministic: The same input properties always result in the same log message output

Installation

go get github.com/decentplatforms/appkit/logf

Usage

All examples below log messages using the RFC 3164 syslog format.

Create a logger using package loggers (arguments vary by format):

syslogTag := "application"
useTimeDetail := true
maxLevel := logf.Warning
defaultLevel := logf.Informational
output := os.Stdout
log := loggers.Syslog3164(syslogTag, useTimeDetail, maxLevel, defaultLevel, output)

or by using a custom configuration:

format := formats.Syslog3164Format(SyslogConfig{
    AppName: "app",
    Tag: "tag",
})
output := os.Stdout
conf := logf.Config{
    MaxLevel: logf.Warning,
    Format: format,
    Output: output,
}
log, err := logf.NewLogger(conf)
if err != nil {
    panic(err)
}

Log messages using Logger.Log:

// Log with only a message...
log.Log(logf.Informational, "test log message!")
// ...or with additional properties.
log.Log(logf.Informational, "test log message!", tracy.String("detail", "extra detail here"))

Treatment of additional properties depends on the format.

As Writer

Loggers are an io.Writer, so you can Logger.Write(msg []byte) to write the message with the logger's default level.

log.Write([]byte("test log message!"))

Contributing

See the root CONTRIBUTING.md file in github.com/decentplatforms/appkit.

Documentation

Index

• Constants
• Variables
• func GetBool[T ~bool](props *Props, name string, def T) T
• func GetFloat[T ~float64](props *Props, name string, def T) T
• func GetInt[T ~int | ~int64](props *Props, name string, def T) T
• func GetString[T ~string](props *Props, name string, def T) T
• func GetUInt[T ~uint | ~uint64](props *Props, name string, def T) T
• func Keywords_AllCaps()
• func Keywords_Syslog()
• func Log(level LogLevel, message string, props ...Prop) error
• func NormalizeWhitespace(msg string) string
• func Use(log Logger)
• type Config
• type Formatter
  • func (formatter Formatter) FormatAndNormalize(level LogLevel, msg string, props *Props) string
• type LogLevel
  • func (level LogLevel) SetKeyword(keyword string)
  • func (level LogLevel) String() string
• type Logger
  • func NewLogger(conf Config) (Logger, error)
• type Prop
  • func Bool[T ~bool](name string, value T) Prop
  • func Float[T ~float64](name string, value T) Prop
  • func Int[T ~int | ~int64](name string, value T) Prop
  • func String[T ~string](name string, value T) Prop
  • func Stringer[T fmt.Stringer](name string, value T) Prop
  • func UInt[T ~uint | ~uint64](name string, value T) Prop
• type Props
  • func NewProps(props ...Prop) *Props
  • func (props *Props) Delete(propnames ...string)
  • func (props *Props) Get(name string) any
  • func (props *Props) Map() map[string]any
  • func (props *Props) Return()
  • func (props *Props) Set(prop Prop)
  • func (props *Props) Slice() []Prop

Constants

const (
	Emergency = LogLevel(iota)
	Alert
	Critical
	Error
	Warning
	Notice
	Informational
	Debug
)

const LEAST_SEVERE = Debug

const MOST_SEVERE = Emergency

Variables

var MultiConfigError = errors.New("can't configure MultiLogger; configure subloggers instead")

var NilFormatError = errors.New("loggers must have a format")

var NilOutputError = errors.New("loggers must have a non-nil output")

var NoActiveLoggerError = errors.New("no active logger")

Functions

func GetBool

func GetBool[T ~bool](props *Props, name string, def T) T

GetBool gets a named bool prop with default value def.

func GetFloat

func GetFloat[T ~float64](props *Props, name string, def T) T

GetFloat gets a named float prop with default value def.

func GetInt

func GetInt[T ~int | ~int64](props *Props, name string, def T) T

GetInt gets a named int prop with default value def.

func GetString

func GetString[T ~string](props *Props, name string, def T) T

GetString gets a named string prop with default value def.

func GetUInt

func GetUInt[T ~uint | ~uint64](props *Props, name string, def T) T

GetUInt gets a named uint prop with default value def.

func Keywords_AllCaps

func Keywords_AllCaps()

func Keywords_Syslog

func Keywords_Syslog()

func Log

func Log(level LogLevel, message string, props ...Prop) error

func NormalizeWhitespace

func NormalizeWhitespace(msg string) string

func Use

func Use(log Logger)

Types

type Config

type Config struct {
	MaxLevel     LogLevel
	DefaultLevel LogLevel
	Format       Formatter
	Output       io.Writer
}

type Formatter

type Formatter func(level LogLevel, msg string, props *Props) string

Formatter defines how Logger.Log and logger.Write output messages. When using Logger.Log, the included props will be passed through, but they are not included when using Logger as an io.Writer.

Do not call formatters directly. Use Formatter.FormatAndNormalize; it normalizes whitespace/newlines for you so you don't have to worry about it in your formatter.

By default, log uses the RFC5424 syslog format.

func (Formatter) FormatAndNormalize

func (formatter Formatter) FormatAndNormalize(level LogLevel, msg string, props *Props) string

type LogLevel

type LogLevel int8

LogLevels denote log severity, with lower values being more severe The native set of LogLevels follows syslog severity, from EMERGENCY/0 to DEBUG/7. You can define extra constants using const LEVEL = LogLevel(<value>) but most logging systems use a subset of what's provided here. Suggested usage:

• Error: Something failed, and there's no way to automatically recover.
• Warning: Something failed, but the program can recover/continue.
• Informational: Messages that should be seen during normal, successful runs.
• Debug: Messages that should only be seen when debugging the application.

Emergency, Alert, and Critical are usually reserved for OS errors, and Notice isn't used frequently.

LogLevel implements fmt.Stringer, which by default maps LogLevels to their respective syslog keywords. You can call SetKeyword with a LogLevel (including self-defined levels) to set or change its string representation:

log.Error.SetKeyword("ERROR")
fmt.Println(log.Error) // ERROR

Some presets are provided through log.Keywords_X() functions.

func (LogLevel) SetKeyword

func (level LogLevel) SetKeyword(keyword string)

func (LogLevel) String

func (level LogLevel) String() string

type Logger

type Logger interface {
	io.Writer
	Configure(conf Config) error
	Log(level LogLevel, msg string, props ...Prop) error
}

func NewLogger

func NewLogger(conf Config) (Logger, error)

type Prop

type Prop struct {
	Name  string
	Value any
}

func Bool

func Bool[T ~bool](name string, value T) Prop

Bool returns a prop whose value is a bool. T may be any type that has an underlying type of bool.

func Float

func Float[T ~float64](name string, value T) Prop

Float returns a prop whose value is a float. T may be any type that has an underlying type of float64.

func Int

func Int[T ~int | ~int64](name string, value T) Prop

Int returns a prop whose value is an int. T may be any type that has an underlying type of int, int64, uint, or uint64. This converts the value to an int64.

func String

func String[T ~string](name string, value T) Prop

String returns a prop whose value is a string. T may be any type that has an underlying type of string.

If you need to use a fmt.Stringer, use logf.Stringer.

func Stringer

func Stringer[T fmt.Stringer](name string, value T) Prop

Stringer returns a prop whose value is a string. T may be any type that implements fmt.Stringer.

func UInt

func UInt[T ~uint | ~uint64](name string, value T) Prop

UInt returns a prop whose value is an unsigned int. T may be any type that has an underlying type of uint, or uint64. This converts the value to a uint64.

type Props

type Props struct {
	// contains filtered or unexported fields
}

Props are an ordered collection of log properties.

func NewProps

func NewProps(props ...Prop) *Props

*Props returns *Props with all provided Prop objects.

func (*Props) Delete

func (props *Props) Delete(propnames ...string)

Delete removes the specified keys from props. This doesn't clear the data from memory, but removes its hash value so that it cannot be accessed through Get/Map.

func (*Props) Get

func (props *Props) Get(name string) any

Get returns a named log property in the calling props. If there's no matching property, returns nil instead.

func (*Props) Map

func (props *Props) Map() map[string]any

Map returns a map of key-value pairs.

func (*Props) Return

func (props *Props) Return()

func (*Props) Set

func (props *Props) Set(prop Prop)

func (*Props) Slice

func (props *Props) Slice() []Prop