alog

README

alog

"another logger!"

Alog is a logging package aiming to hit a sweet spot between API surface, flexibility, and structure.

Documentation

Overview

Package alog provides a simple logger that has minimal structuring passed via context.Context.

Example (Levels)

ctx := context.Background()
l := New(WithEmitter(EmitterFunc(func(ctx context.Context, e *Entry) {
	for _, p := range e.Tags {
		if p[0] != "level" {
			continue
		}
		switch p[1] {
		case "error":
			fmt.Println("ERROR", e.Tags, e.Msg)
			fallthrough
		case "info":
			fallthrough
		case "debug":
			return
		}
	}
})))
error := AddTags(ctx, "level", "error")
info := AddTags(ctx, "level", "info")
debug := AddTags(ctx, "level", "debug")

l.Print(debug, "test")
l.Print(info, "test")
l.Print(error, "test")

Output:

ERROR [[level error]] test

Index

• Variables
• func AddTags(ctx context.Context, pairs ...string) context.Context
• func Print(ctx context.Context, v ...interface{})
• func Printf(ctx context.Context, f string, v ...interface{})
• type Emitter
• type EmitterFunc
  • func (f EmitterFunc) Emit(c context.Context, e *Entry)
• type Entry
• type Logger
  • func New(opts ...Option) *Logger
  • func (l *Logger) Output(ctx context.Context, calldepth int, msg string)
  • func (l *Logger) Print(ctx context.Context, v ...interface{})
  • func (l *Logger) Printf(ctx context.Context, f string, v ...interface{})
  • func (l *Logger) StdLogger(ctx context.Context) *log.Logger
• type Option
  • func OverrideTimestamp(f func() time.Time) Option
  • func WithCaller() Option
  • func WithEmitter(e Emitter) Option

Examples

• Package (Levels)
• WithCaller
• WithEmitter

Variables

var Default = New(WithEmitter(defaultEmitter))

Default is the the Logger the package-level Print functions use.

Functions

func AddTags

func AddTags(ctx context.Context, pairs ...string) context.Context

AddTags adds paired strings to the set of tags in the Context.

Any unpaired strings are ignored.

func Print

func Print(ctx context.Context, v ...interface{})

Print uses the Default Logger to print the supplied string.

func Printf

func Printf(ctx context.Context, f string, v ...interface{})

Printf uses the Default Logger to format and then print the supplied string.

Types

type Emitter

type Emitter interface {
	Emit(context.Context, *Entry)
}

Emitter is the interface that wraps the Emit method.

Emit handles a log entry in a customized way.

type EmitterFunc

type EmitterFunc func(context.Context, *Entry)

EmitterFunc is an adapter to allow the use of an ordinary function as an Emitter.

func (EmitterFunc) Emit

func (f EmitterFunc) Emit(c context.Context, e *Entry)

Emit calls f(c, e).

type Entry

type Entry struct {
	Time time.Time
	Tags [][2]string
	File string
	Line int
	Msg  string
}

Entry is the struct passed to user-supplied formatters.

type Logger

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

Logger is a logging object that extracts tags from a context.Context and emits Entry structs.

A nil *Logger is valid to call methods on.

The default text format will have a newline appended if one is not present in the message.

func New

func New(opts ...Option) *Logger

New returns a configured *Logger, ready to use.

See the Option-returning functions in this package for configuration knobs.

func (*Logger) Output

func (l *Logger) Output(ctx context.Context, calldepth int, msg string)

Output emits the supplied string while capturing the caller information "calldepth" frames back in the call stack. The value 2 is almost always what a caller wants. See also: runtime.Caller

func (*Logger) Print

func (l *Logger) Print(ctx context.Context, v ...interface{})

Print calls l.Output to emit a log entry. Arguments are handled like fmt.Print.

func (*Logger) Printf

func (l *Logger) Printf(ctx context.Context, f string, v ...interface{})

Printf calls l.Output to emit a log entry. Arguments are handled like fmt.Printf.

func (*Logger) StdLogger

func (l *Logger) StdLogger(ctx context.Context) *log.Logger

StdLogger returns a standard log.Logger that sends log messages to this logger with the provided Context. The returned log.Logger should not be modified.

type Option

type Option func(*Logger)

Option sets an option on a Logger.

Options are applied in the order specified, meaning if both To and WithEmitter are supplied in a call to New, the last one wins.

func OverrideTimestamp

func OverrideTimestamp(f func() time.Time) Option

OverrideTimestamp sets the function that will be used to get the current time for each log entry.

This is primarily meant to be used for testing custom emitters. For example: OverrideTimestamp(func() time.Time { return time.Time{} })

func WithCaller

func WithCaller() Option

WithCaller configures the logger to include the caller information in each log entry.

Example

dumper := EmitterFunc(func(ctx context.Context, e *Entry) {
	fmt.Printf("%s:%d %s\n", filepath.Base(e.File), e.Line, e.Msg)
})
ctx := context.Background()
l := New(WithEmitter(dumper), WithCaller())

l.Print(ctx, "test")

Output:

alog_test.go:61 test

func WithEmitter

func WithEmitter(e Emitter) Option

WithEmitter configures the logger to call e.Emit() every time it needs to emit a log line.

Calls are not synchronized.

Example

dumper := EmitterFunc(func(ctx context.Context, e *Entry) {
	fmt.Printf("%v %s\n", e.Tags, e.Msg)
})
ctx := context.Background()
l := New(WithEmitter(dumper))

ctx = AddTags(ctx, "allthese", "tags")
l.Print(ctx, "test")

Output:

[[allthese tags]] test