penlog

README

PENLog

PENLog provides a specification, library, and tooling for simple machine readable logging.

How does it work?

Log entries look like this:

$ cat log.json
{"timestamp": "2020-04-02T12:48:08.906523", "component": "scanner", "type": "msg", "data": "Starting tshark", "host": "kronos"}
{"timestamp": "2020-04-02T12:48:09.583521", "component": "moncay", "type": "msg", "data": "Doing stuff", "host": "kronos"}

They can be converted with the included hr tool into this:

$ hr log.json
Apr  2 12:48:08.906 {scanner } [msg   ]: Starting tshark with
Apr  2 12:48:09.583 {moncay  } [msg   ]: Doing stuff

Why?

Long test runs generate tons of data. This logging format enables powerful postprocessing and is nice to look at in the terminal as well.

But JSON has so much overhead!!??

Just use the tooling like e.g. hr -f file.log.zst. Much of the overhead is compressed away. More examples are in the documentation.

Where is the Specification?

The manpages are in man/ in this repository. They are written in the asciidoc markup language.

How do I use it?

The converter is in bin/hr and can be build using:

$ make hr

For additional information, see the mapage hr(1) in the man directory.

The philosophy is: Let your program log everything at any time to stderr, pipe it into hr and let the tool do the filtering and archiving. A Go and Python library for emitting log messages is included in this repository as well. Usage is easy, e.g. in Go:

logger = penlog.NewLogger("myProgram", os.Stderr)
logger.LogMessage("my log message")

Documentation

Overview

Package penlog implements the penlog(7) specification.

Index

• type Logger
  • func NewLogger(component string, w io.Writer) *Logger
  • func (l *Logger) Log(msg map[string]interface{})
  • func (l *Logger) LogMessage(v ...interface{})
  • func (l *Logger) LogMessagef(format string, v ...interface{})
  • func (l *Logger) LogPreamble(v ...interface{})
  • func (l *Logger) LogPreamblef(format string, v ...interface{})
  • func (l *Logger) LogRead(handle string, v ...interface{})
  • func (l *Logger) LogReadf(handle, format string, v ...interface{})
  • func (l *Logger) LogWrite(handle string, v ...interface{})
  • func (l *Logger) LogWritef(handle, format string, v ...interface{})

Types

type Logger

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

func NewLogger

func NewLogger(component string, w io.Writer) *Logger

func (*Logger) Log

func (l *Logger) Log(msg map[string]interface{})

func (*Logger) LogMessage

func (l *Logger) LogMessage(v ...interface{})

func (*Logger) LogMessagef

func (l *Logger) LogMessagef(format string, v ...interface{})

func (*Logger) LogPreamble

func (l *Logger) LogPreamble(v ...interface{})

func (*Logger) LogPreamblef

func (l *Logger) LogPreamblef(format string, v ...interface{})

func (*Logger) LogRead

func (l *Logger) LogRead(handle string, v ...interface{})

func (*Logger) LogReadf

func (l *Logger) LogReadf(handle, format string, v ...interface{})

func (*Logger) LogWrite

func (l *Logger) LogWrite(handle string, v ...interface{})

func (*Logger) LogWritef

func (l *Logger) LogWritef(handle, format string, v ...interface{})