plog

Documentation

Overview

Package for logging and sending logs to a log server, where they'll be aggregated into log objects and kept safe even if the client program exists or crashes.

Index

• Constants
• Variables
• func Setup(appname, lvl string)
• func Shutdown()
• type Level
  • func LogLevel(lvl string, def Level) Level
  • func (l Level) Code() string
  • func (l Level) Fatal(v ...interface{})
  • func (l Level) Fatalf(format string, v ...interface{})
  • func (l Level) Lower() string
  • func (l Level) Print(v ...interface{})
  • func (l Level) Printf(format string, v ...interface{})
  • func (l Level) String() string
  • func (l Level) Write(w []byte) (n int, err error)
• type Plog
  • func IfEnabled(lvl Level) *Plog
  • func NewPlogCount(appname string, path ...string) *Plog
  • func NewPlogLog(appname string) *Plog
  • func NewPlogState(appname string) *Plog
  • func (ctx *Plog) Close() error
  • func (ctx *Plog) Log(key string, value interface{}) error
  • func (ctx *Plog) LogAsString(key string, value []byte)
  • func (ctx *Plog) LogDict(key string, kvs ...interface{}) error
  • func (ctx *Plog) LogJSON(key string, value []byte)
  • func (pctx *Plog) OpenDict(key string) *Plog
  • func (pctx *Plog) OpenList(key string) *Plog

Constants

const Crit = Critical

Variables

var FallbackWriter io.Writer = os.Stderr

Where logs go if we can't connect to plogd. Defaults to stderr. Logs will be written prefixed with key and suffixed with a newline. All output is json encoded.

var LevelByName = map[string]Level{
	"Emergency": Emergency,
	"EMERG":     Emergency,
	"emerg":     Emergency,
	"emergency": Emergency,
	"Alert":     Alert,
	"ALERT":     Alert,
	"alert":     Alert,
	"Critical":  Critical,
	"CRIT":      Critical,
	"crit":      Critical,
	"critical":  Critical,
	"Error":     Error,
	"ERR":       Error,
	"err":       Error,
	"error":     Error,
	"Warning":   Warning,
	"WARNING":   Warning,
	"warning":   Warning,
	"Notice":    Notice,
	"NOTICE":    Notice,
	"notice":    Notice,
	"Info":      Info,
	"INFO":      Info,
	"info":      Info,
	"Debug":     Debug,
	"DEBUG":     Debug,
	"debug":     Debug,
}

var LevelNames = map[Level]struct {
	Name, Code, Lower string
}{
	Emergency: {"Emergency", "EMERG", "emerg"},
	Alert:     {"Alert", "ALERT", "alert"},
	Critical:  {"Critical", "CRIT", "crit"},
	Error:     {"Error", "ERR", "err"},
	Warning:   {"Warning", "WARNING", "warning"},
	Notice:    {"Notice", "NOTICE", "notice"},
	Info:      {"Info", "INFO", "info"},
	Debug:     {"Debug", "DEBUG", "debug"},
}

var SetupLevel = Info

Threshold for logging, only this and higher prio levels will log.

Functions

func Setup

func Setup(appname, lvl string)

Initializes the default plog context and changes SetupLevel based on a string. Also calls log.SetOutput(plog.Info) to redirect log.Printf output to this package.

func Shutdown

func Shutdown()

Closes Default, disconnecting from the logging server.

Types

type Level

type Level int

const (
	Emergency Level = iota
	Alert
	Critical
	Error
	Warning
	Notice
	Info
	Debug
)

func LogLevel

func LogLevel(lvl string, def Level) Level

Returns the Level mathcing lvl, if it's valid, otherwise returns def. Commonly used with the lower case codes, either shortened or full.

func (Level) Code

func (l Level) Code() string

Upper-case code for level, matching logs. Levels Emergency to Error are shortened, while Warning to Debug are full name upper-case.

func (Level) Fatal

func (l Level) Fatal(v ...interface{})

Calls l.Write followed by os.Exit(1)

func (Level) Fatalf

func (l Level) Fatalf(format string, v ...interface{})

Calls log_printf followed by os.Exit(1)

func (Level) Lower

func (l Level) Lower() string

Lower-case code for level. Levels Emergency to Error are shortened, while Warning to Debug are full name lower-case.

func (Level) Print

func (l Level) Print(v ...interface{})

Calls l.Write via fmt.Fprint. Checks l against the SetupLevel first and thus is slightly more efficient than calling fmt.Fprint directly.

func (Level) Printf

func (l Level) Printf(format string, v ...interface{})

Calls l.Write via fmt.Fprintf. Checks l against the SetupLevel first and thus is slightly more efficient than calling fmt.Fprintf directly.

func (Level) String

func (l Level) String() string

Human-readable name of level.

func (Level) Write

func (l Level) Write(w []byte) (n int, err error)

Writes to Default if l <= SetupLevel, or to FallbackWriter if Default is nil. Can be used with log.SetOutput, log.New or fmt.Fprint*. Example: log.SetOutput(plog.Info)

type Plog

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

A plog context is an object opened in the log server. The server will keep track of it and all its contents until it's closed (and beyond, in case of state contexts). If a program crashes/exits without closing the context the server will detect this and log an "@interrupted" key for easier debugging.

var Default *Plog

Default plog context, opened by Setup.

func IfEnabled

func IfEnabled(lvl Level) *Plog

Returns the default context if the level is enabled by the threshold given to setup, otherwise nil. It's safe to call functions on nil contexts.

func NewPlogCount

func NewPlogCount(appname string, path ...string) *Plog

Open a new root count plog context. When integers are logged in this context, it's applied as a delta to the state. When the context is closed the integer values added are removed. Can be used to keep statistics such as number of open fds and aggregate them between multiple processes with the same name.

func NewPlogLog

func NewPlogLog(appname string) *Plog

Open a new root logging plog context. If you called Setup, then you should probably use Default instead of this.

func NewPlogState

func NewPlogState(appname string) *Plog

Open a new root state plog context. State is kept in plogd and only logged with a "state" key once all state contexts for the appname are closed. You can also query it over HTTP from plogd.

func (*Plog) Close

func (ctx *Plog) Close() error

Close the context, marking it as properly closed in the server. For subcontext, this is what triggers it being sent to the parent context.

func (*Plog) Log

func (ctx *Plog) Log(key string, value interface{}) error

Encode value as JSON and log it. Might return errors from json.Marshal, but that should only happen in very rare cases. For strings, ints and other basic types you can ignore the return value.

func (*Plog) LogAsString

func (ctx *Plog) LogAsString(key string, value []byte)

Log value as if it was a string.

func (*Plog) LogDict

func (ctx *Plog) LogDict(key string, kvs ...interface{}) error

Log a JSON dictionary from the variadic arguments, alternating keys and values, key first. Note that the first argument is not part of the dictionary, it's the message key. Might return errors from json.Marshal.

func (*Plog) LogJSON

func (ctx *Plog) LogJSON(key string, value []byte)

Log raw JSON encoded data in value. You must make sure the JSON is valid, or the context will be aborted.

func (*Plog) OpenDict

func (pctx *Plog) OpenDict(key string) *Plog

Opens a sub-context dictionary. Once this and any sub-contexts to it are closed, a dictionary object will be logged in the parent plog.

func (*Plog) OpenList

func (pctx *Plog) OpenList(key string) *Plog

Opens a sub-context list. Once this and any sub-contexts to it are closed, a list will be logged in the parent plog.