log

README

log

Package log implements structured logging helpers.

Levels are supported with the following intended production semantics:

• DBG debug
• INF machine-actionable
• WRN human-observable
• ERR human-actionable

Handlers are used to format log entry output. The following functions return loggers with preconfigured handlers. Optionally write your own by implementing the log.Handler interface.

• NewLogger
• NewTextLogger
• NewShellLogger
• NewMinimalShellLogger
• NewDiscardLogger

Usage

package main

import (
	"os"

	"github.com/pnelson/log"
)

func main() {
	loggers := []*log.Logger{
		log.NewLogger(os.Stderr, false),
		log.NewTextLogger(os.Stderr),
		log.NewShellLogger(os.Stderr),
		log.NewMinimalShellLogger(os.Stderr),
		log.NewDiscardLogger(),
	}
	for _, l := range loggers {
		l.Log(log.ERR, log.M{"foo": "bar"}, "baz/%s", "qux")
	}
}

Documentation

Overview

Package log implements structured logging helpers.

Index

• Constants
• type Entry
• type Handler
• type Level
  • func (l Level) MarshalJSON() ([]byte, error)
  • func (l Level) String() string
  • func (l *Level) UnmarshalJSON(b []byte) error
• type Logger
  • func New(h Handler) *Logger
  • func NewDiscardLogger() *Logger
  • func NewLogger(w io.Writer, debug bool) *Logger
  • func NewMinimalShellLogger(w io.Writer) *Logger
  • func NewShellLogger(w io.Writer) *Logger
  • func NewTextLogger(w io.Writer) *Logger
  • func (l *Logger) Log(level Level, data M, format string, args ...interface{})
• type M
  • func (m M) Keys() []string

Constants

const (
	// DBG represents debug data.
	DBG Level = 30

	// INF represents machine-actionable data.
	INF = 34

	// WRN represents human-observable data.
	WRN = 33

	// ERR represents human-actionable data.
	ERR = 31
)

Level constants.

Types

type Entry

type Entry struct {
	Level   Level     `json:"level"`
	Message string    `json:"message"`
	Data    M         `json:"data,omitempty"`
	Time    time.Time `json:"time"`
}

Entry represents a log entry.

type Handler

type Handler interface {
	Log(e Entry) error
}

Handler represents a log formatting handler.

type Level

type Level int

Level represents a log level.

func (Level) MarshalJSON

func (l Level) MarshalJSON() ([]byte, error)

MarshalJSON impelements the json.Marshaler interface.

func (Level) String

func (l Level) String() string

String implements the fmt.Stringer interface.

func (*Level) UnmarshalJSON

func (l *Level) UnmarshalJSON(b []byte) error

UnmarshalJSON implements the json.Unmarshaler interface.

type Logger

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

Logger represents a logger.

func New

func New(h Handler) *Logger

New returns a new *Logger.

func NewDiscardLogger

func NewDiscardLogger() *Logger

NewDiscardLogger returns a *Logger that discards log entries.

func NewLogger

func NewLogger(w io.Writer, debug bool) *Logger

NewLogger returns a *Logger that writes JSON encoded logs.

This logger is recommended for production. Entries with log level INF are discarded as they are intended to be purely informational and machine-actionable events. Entries with log level DBG will be logged if debug is true.

func NewMinimalShellLogger

func NewMinimalShellLogger(w io.Writer) *Logger

NewMinimalShellLogger returns a *Logger that writes text formatted logs with decorative shell colors but without timestamps and text levels.

func NewShellLogger

func NewShellLogger(w io.Writer) *Logger

NewShellLogger returns a *Logger that writes POSIX shell formatted logs.

func NewTextLogger

func NewTextLogger(w io.Writer) *Logger

NewTextLogger returns a *Logger that writes text formatted logs.

func (*Logger) Log

func (l *Logger) Log(level Level, data M, format string, args ...interface{})

Log writes the formatted log entry.

type M

type M map[string]interface{}

M represents the logging data map.

func (M) Keys

func (m M) Keys() []string

Keys returns the sorted data keys.