log

README

log

import "acln.ro/log"

Highly opinionated logging experiment. This package is a work in progress and will likely change once I begin using it in various places.

Objectives

• structured, leveled logging, with few but obvious log levels
• component-, task- and region- based scoping
• much smaller API surface than logrus, zap, or other similar efforts
• extensibility and composability

Non-objectives

• "speed": nanosecond times, zero allocation etc. etc.
• standard library compatibility
• metrics

Documentation

Index

• Constants
• type Event
  • func (ev Event) KV() KV
• type JSONSink
  • func (js *JSONSink) Drain(kv KV) error
• type KV
  • func (kv KV) KV() KV
  • func (kv KV) SortedKeys() []string
  • func (kv KV) String() string
• type KVer
• type Level
  • func (lv Level) MarshalJSON() ([]byte, error)
  • func (lv *Level) Set(s string) error
  • func (lv Level) String() string
• type Logger
  • func New(sink Sink, lv Level) *Logger
  • func (l *Logger) Debug(kvers ...KVer) error
  • func (l *Logger) Error(err error, kvers ...KVer) error
  • func (l *Logger) ForComponent(component string) *Logger
  • func (l *Logger) ForRegion(region string) *Logger
  • func (l *Logger) ForTask(task string) *Logger
  • func (l *Logger) Info(kvers ...KVer) error
  • func (l *Logger) SetLevel(lv Level)
  • func (l *Logger) WithKV(kver ...KVer) *Logger
• type Op
  • func (op Op) KV() KV
• type Sink
• type Tee
  • func (t Tee) Drain(kv KV) error
• type TextSink
  • func (ts *TextSink) Drain(kv KV) error

Constants

const (
	LevelKey     = "level"
	TimestampKey = "ts"
	ComponentKey = "component"
	TaskKey      = "task"
	RegionKey    = "region"
	ErrorKey     = "error"
)

Reserved built-in keys

Types

type Event

type Event string

Event represents an event. It occupies the "event" key in a KV.

func (Event) KV

func (ev Event) KV() KV

KV returns a KV with the event name under the key "event".

type JSONSink

type JSONSink struct {
	Output io.Writer
	// contains filtered or unexported fields
}

JSONSink emits JSON objects to an output stream. JSONSink values must not be copied.

func (*JSONSink) Drain

func (js *JSONSink) Drain(kv KV) error

Drain encodes the specified key-value pairs to JSON, then writes them out to the underyling io.Writer.

When using JSONSink, callers must ensure that all values in the KV map can be JSON-encoded, otherwise the resulting object may be malformed, or encoding might fail.

Drain makes a single Write call to the underlying io.Writer.

type KV

type KV map[string]interface{}

KV is a collection of key-value pairs.

func (KV) KV

func (kv KV) KV() KV

KV returns kv.

func (KV) SortedKeys

func (kv KV) SortedKeys() []string

SortedKeys returns all keys in the map, sorted in the order prescribed by this package. Built-in keys go first, in the order "level", "ts", "component", "task", "region", "error", followed by user-defined keys, sorted lexicographically.

func (KV) String

func (kv KV) String() string

String returns a textual representation of the key-value pairs.

type KVer

type KVer interface {
	KV() KV
}

KVer is any type which can represent itself as a key-value pair.

type Level

type Level uint32

Level represents a log level.

const (
	Quiet Level = 1 + iota
	Error
	Info
	Debug
)

Supported log levels.

func (Level) MarshalJSON

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

MarshalJSON marshals lv as a JSON string.

func (*Level) Set

func (lv *Level) Set(s string) error

Set implements the flag.Value.Set method.

func (Level) String

func (lv Level) String() string

String returns a textual representation of the log level. The strings are "quiet", "error", "info", and "debug". If lv is not a supported log level, String returns the empty string.

type Logger

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

Logger is a structured, leveled logger.

func New

func New(sink Sink, lv Level) *Logger

New creates a new Logger which forwards logs at or below the specified level to the specified Sink.

func (*Logger) Debug

func (l *Logger) Debug(kvers ...KVer) error

Debug emits a log message at the Debug level.

func (*Logger) Error

func (l *Logger) Error(err error, kvers ...KVer) error

Error emits a log message at the Error level.

func (*Logger) ForComponent

func (l *Logger) ForComponent(component string) *Logger

ForComponent returns a Logger for the specified component. If a component key exists in one of the parent loggers, the specified component name is appended to it in the returned logger, per acln.ro/hiername.

func (*Logger) ForRegion

func (l *Logger) ForRegion(region string) *Logger

ForRegion returns a Logger for the specified region. ForRegion is intended to be used in conjunction with a *runtime/trace.Region. By convention, the region names should match. If a region key exists in one of the parent loggers, the specified region name is appended to it in the returned logger, per acln.ro/hiername.

func (*Logger) ForTask

func (l *Logger) ForTask(task string) *Logger

ForTask returns a Logger for the specified task. ForTask is intended to be used in conjunction with a *runtime/trace.Task. By convention, the task names should match. If a task key exists in one of the parent loggers, the specified task name is appended to it in the returned logger, per acln.ro/hiername.

func (*Logger) Info

func (l *Logger) Info(kvers ...KVer) error

Info emits a log message at the Info level.

func (*Logger) SetLevel

func (l *Logger) SetLevel(lv Level)

SetLevel sets the log level to lv.

func (*Logger) WithKV

func (l *Logger) WithKV(kver ...KVer) *Logger

WithKV returns a new Logger which logs messages with the specified key-value pairs. The keys "level", "ts", "component", "task", "region", "error", and "msg" are reserved.

type Op

type Op string

Op represents an operation. It occupies the "op" key in a KV.

func (Op) KV

func (op Op) KV() KV

KV returns a KV with the operation name under the key "op".

type Sink

type Sink interface {
	Drain(KV) error
}

A Sink encodes key-value pairs and produces a log message. Implementations of Sink must be safe for concurrent use.

Implementations of Sink which produce output where the order of key-value pairs is significant should use KV.SortedKeys to determine the order prescribed by this package.

Implementations of Sink must not modify KV maps.

type Tee

type Tee []Sink

Tee is a Sink which sends KVs to all sinks it contains.

func (Tee) Drain

func (t Tee) Drain(kv KV) error

Drain sends kv to all sinks contained in t. If Sink.Drain returns an error for any Sink, Drain records the first such error and returns it.

type TextSink

type TextSink struct {
	Output io.Writer
	// contains filtered or unexported fields
}

TextSink emits textual log messages to an output stream. TextSink values must not be copied.

func (*TextSink) Drain

func (ts *TextSink) Drain(kv KV) error

Drain encodes the specified key-value pairs to text, then writes them to the underlying io.Writer, followed by a newline.

Values are formatted using fmt.Sprint. If the textual representation of values contains whitespace or unprintable characters (in accordance with unicode.IsSpace and unicode.IsPrint), the values are quoted.

Drain makes a single Write call to the underlying io.Writer.