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
- type LogLevel
- type Logger
- 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
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 Keywords_AllCaps ¶
func Keywords_AllCaps()
func Keywords_Syslog ¶
func Keywords_Syslog()
func NormalizeWhitespace ¶
Types ¶
type Formatter ¶
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.
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 ¶
type Logger ¶
type Prop ¶
func Bool ¶
Bool returns a prop whose value is a bool. T may be any type that has an underlying type of bool.
func Float ¶
Float returns a prop whose value is a float. T may be any type that has an underlying type of float64.
func Int ¶
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 ¶
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.
type Props ¶
type Props struct {
// contains filtered or unexported fields
}
Props are an ordered collection of log properties.
func (*Props) Delete ¶
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.
Source Files
Directories