fengaldar

Documentation

Overview

Fengaldar provides a logger, or, 'one who cuts trees'.

The result of NewLogger().Println("Some message") looks like:

INFO 2020-09-03T18:53:04-06:00 Some message

The result of NewJSONLogger().Println("Some message") looks like:

{"timestamp":"2020-09-03T18:53:04-06:00", "severity":"INFO", "message":"Some message"}

The result of NewJSONLogger().Notice("Some message", LogContext{"extra":"info"}) looks like:

{"timestamp": "2020-09-03T18:53:04-06:00", "severity": "INFO", "message": "Some message", "additionalContext": "{\"extra\":\"info\"}"}

Of course you'll likely store the result of NewLogger() in a var so your code might look more like this:

import ( fen "git.ondollo.com/fengaldar" )
...
l := fen.NewLogger()
...
l.Log("Something happened")
...
l.Notice("Something interesting happened")

You might also want to tweak the defaults with your own. That might look something like this:

import ( fen "git.ondollo.com/fengaldar" )
...
minSeverityToLog := fen.Warning
defaultLogSeverity := fen.Notice
customOptions := fen.Options{minSeverityToLog, defaultLogSeverity, time.RFC822, false, "more"}
l := fen.NewLoggerWithOptions(customOptions)
...
l.Log("Something happened") // This will be ignored due to having set 'minSeverityToLog' to a higher Severity than the default (which was provided in defaultLogSeverity)
...
l.Notice("Something interesting happened") // This will also be ignored due to having set 'minSeverityToLog' to a higher Severity than the default (which was provided in defaultLogSeverity)
...
l.Critical("Something caused a brief outage") // This will NOT be ignored

You might also want to add some context to the log entry, and that might look something like this:

import ( fen "git.ondollo.com/fengaldar" )
...
l := fen.NewLogger()
...
l.Log("Something happened", fen.LogContext{"somethingWasSetTo": "someValue"})

Index

• Constants
• Variables
• type ContextStyleOption
• type LogContext
  • func (lc LogContext) JSON() string
  • func (a LogContext) Merge(b LogContext)
  • func (lc LogContext) String() string
• type Logger
  • func NewJSONLogger() Logger
  • func NewJSONLoggerWithOptions(o Options) Logger
  • func NewLogger() Logger
  • func NewLoggerWithOptions(o Options) Logger
• type Options
• type Severity
  • func (s Severity) String() string

Examples

• NewJSONLogger
• NewJSONLoggerWithOptions
• NewLogger
• NewLoggerWithOptions

Constants

const DefaultContextKey = "additionalContext"

const DefaultTraceKey = "traceid"

Variables

var DefaultOptions = Options{
	Min:          Debug,
	Sev:          Info,
	TF:           time.RFC3339,
	ContextStyle: Flat,
	ContextKey:   DefaultContextKey,
	TraceKey:     DefaultTraceKey,
}

Types

type ContextStyleOption

type ContextStyleOption int

const (
	Flat ContextStyleOption = iota
	Nest
	Prefix
)

type LogContext

type LogContext map[string]string

LogContext provides a way to express additional context on a log entry.

func (LogContext) JSON

func (lc LogContext) JSON() string

LogContext.JSON will produce a JSON object, where each key and value remain keys and values and are converted with fmt.Sprintf("%q")

func (LogContext) Merge

func (a LogContext) Merge(b LogContext)

func (LogContext) String

func (lc LogContext) String() string

LogContext.String will produce a unicode box-drawing prefix-wrapped output where each key in the LogContext is on it's own line

type Logger

type Logger interface {
	Clone() Logger
	Trace(string) Logger             // Trace sets the given TraceKey to the given value and returns a func that resets the value on a defer
	Time() string                    // Time is the result of applying the time.Layout specified in Options.TF in a call to time.Now().Format
	Sev() Severity                   // Sev is the default severity used in Println and Log
	Println(...interface{})          // For NewLogger, each parameter will be on it's own line. For NewJSONLogger, they're combined with a strings.Join("\n").
	Log(string, ...LogContext)       // FOR ALL DECLARATIONS OF `...LogContext` ONLY THE FIRST LogContext WILL BE USED
	Debug(string, ...LogContext)     // Debug - debug or trace information.
	Info(string, ...LogContext)      // Info - routine information, such as ongoing status or performance.
	Notice(string, ...LogContext)    // Notice - normal but significant events, such as start up, shut down, or configuration.
	Warning(string, ...LogContext)   // Warning - events that might cause problems.
	Error(string, ...LogContext)     // Error - events that are likely to cause problems.
	Critical(string, ...LogContext)  // Critical - events that cause more severe problems or brief outages.
	Alert(string, ...LogContext)     // Alert - a person must take an action immediately.
	Emergency(string, ...LogContext) // Emergency - one or more systems are unusable.
	Panic(string, ...LogContext)     // Panic - one or more systems are unusable and this package will throw a panic.
	Fatal(string, ...LogContext)     // Fatal - one or more systems are unusable and this package will call os.Exit(1).
}

FOR ALL DECLARATIONS OF `...LogContext` ONLY THE FIRST LogContext WILL BE USED. This allows the LogContext to be optional.

You might notice that Printf is not provided.

In cases where you would use Printf you should explore constructing a LogContext to convey the additional data, or use fmt.Sprintf.

func NewJSONLogger

func NewJSONLogger() Logger

Example

package main

import (
	fen "git.ondollo.com/fengaldar"
)

func main() {
	// import ( fen "git.ondollo.com/fengaldar")
	l := fen.NewJSONLogger()
	l.Debug("Debug Log")
	l.Info("Info Log")
	l.Log("Log with context", fen.LogContext{"a": "b", "c": "d"})
}

func NewJSONLoggerWithOptions

func NewJSONLoggerWithOptions(o Options) Logger

Example

package main

import (
	fen "git.ondollo.com/fengaldar"
)

func main() {
	// import ( fen "git.ondollo.com/fengaldar")
	l := fen.NewJSONLoggerWithOptions(fen.Options{fen.Debug, fen.Debug, "15:04:05.000"})
	l.Debug("Debug Log")
	l.Log("Log with context", fen.LogContext{"a": "b", "c": "d"})

}

func NewLogger

func NewLogger() Logger

Example

package main

import (
	fen "git.ondollo.com/fengaldar"
)

func main() {
	// import ( fen "git.ondollo.com/fengaldar")
	l := fen.NewLogger()
	l.Println("Println")
	l.Log("Log")
	l.Debug("Debug Log")
	l.Log("Log with context", fen.LogContext{"a": "b", "c": "d"})
}

func NewLoggerWithOptions

func NewLoggerWithOptions(o Options) Logger

Example

package main

import (
	fen "git.ondollo.com/fengaldar"
)

func main() {
	// import ( fen "git.ondollo.com/fengaldar")
	l := fen.NewLoggerWithOptions(fen.Options{fen.Debug, fen.Debug, "15:04:05.000"})
	l.Debug("Debug Log")
	l.Info("Info Log")
	l.Log("Log with context", fen.LogContext{"a": "b", "c": "d"})
}

type Options

type Options struct {
	Min Severity // The minimum severity to actually produce output. Any log entry with an associated severity *below* this will be ignored.
	Sev Severity
	// TF is the TimeFormat that will be used when producing log entries.
	// This follows the time.Layout format seen here: https://pkg.go.dev/time#pkg-constants
	TF string
	// ContextStyle sets the use of the ContextKey as either a prefix to each LogContext key or
	// as the key to a nested object of LogContext keys and values or, finally, as a flattened set of keys
	// that are added to the root of the JSON log entry without prefix. This only matters for the JSON logger
	ContextStyle ContextStyleOption
	ContextKey   string // ContextKey is used to namespace the LogContext
	TraceKey     string // TraceKey is the key that the traceid, if any, will be placed under for the JSON logger
}

Options allow you to specify different defaults for loggers

type Severity

type Severity int

Severity represents the severity of the related log entry. Naming, ordering, and guidlines are based on severity consts found at https://pkg.go.dev/cloud.google.com/go/logging#pkg-constants

const (
	Debug     Severity = iota // Debug - debug or trace information.
	Info                      // Info - routine information, such as ongoing status or performance.
	Notice                    // Notice - normal but significant events, such as start up, shut down, or configuration.
	Warning                   // Warning - events that might cause problems.
	Error                     // Error - events that are likely to cause problems.
	Critical                  // Critical - events that cause more severe problems or brief outages.
	Alert                     // Alert - a person must take an action immediately.
	Emergency                 // Emergency - one or more systems are unusable.
	Panic                     // Panic - one or more systems are unusable and this package will throw a panic.
	Fatal                     // Fatal - one or more systems are unusable and this package will call os.Exit(1).
)

func (Severity) String

func (s Severity) String() string