package logg

import "github.com/bep/logg"

package logg implements a simple structured logging API.

package main

import (
	"bytes"
	"fmt"

	"github.com/bep/logg"
	"github.com/bep/logg/handlers/text"
)

func main() {
	var buff bytes.Buffer
	// Create a new logger.
	l := logg.New(
		logg.Options{
			Level:   logg.LevelInfo,
			Handler: text.New(&buff, text.Options{Separator: " "}),
		},
	)
	// Create a new log context.
	infoLogger := l.WithLevel(logg.LevelInfo)

	// Logg some user activity.
	userLogger := infoLogger.WithField("user", "foo").WithField("id", "123")
	userLogger.Log(logg.String("logged in"))
	userLogger.WithField("file", "jokes.txt").Log(logg.String("uploaded"))
	userLogger.WithField("file", "morejokes.txt").Log(logg.String("uploaded"))

	fmt.Print(buff.String())

}

INFO logged in user=foo id=123
INFO uploaded user=foo id=123 file=jokes.txt
INFO uploaded user=foo id=123 file=morejokes.txt

package main

import (
	"bytes"
	"fmt"
	"strings"
	"time"

	"github.com/bep/logg"
	"github.com/bep/logg/handlers/text"
)

func main() {
	var buff bytes.Buffer
	// Create a new logger.
	l := logg.New(
		logg.Options{
			Level:   logg.LevelError,
			Handler: text.New(&buff, text.Options{Separator: "|"}),
		},
	)

	errorLogger := l.WithLevel(logg.LevelError)

	// Info is below the logger's level, so
	// nothing will be printed.
	infoLogger := l.WithLevel(logg.LevelInfo)

	// Simulate a busy loop.
	for i := 0; i < 999; i++ {
		ctx := infoLogger.WithFields(
			logg.NewFieldsFunc(
				// This func will never be invoked with the current logger's level.
				func() logg.Fields {
					return logg.Fields{
						{"field", strings.Repeat("x", 9999)},
					}

				}),
		)
		ctx.Log(logg.StringFunc(
			// This func will never be invoked with the current logger's level.
			func() string {
				return "log message: " + strings.Repeat("x", 9999)
			},
		))

	}

	errorLogger.WithDuration(32 * time.Second).Log(logg.String("something took too long"))

	fmt.Print(buff.String())

}

ERROR|something took too long|duration=32000

Index ¶

• Variables
• type Clock
• type Entry
• func NewEntry(log *logger) *Entry
• func (e *Entry) Clone() *Entry
• func (e *Entry) Log(s fmt.Stringer)
• func (e *Entry) Logf(format string, a ...any)
• func (e *Entry) WithDuration(d time.Duration) *Entry
• func (e *Entry) WithError(err error) *Entry
• func (e *Entry) WithField(key string, value any) *Entry
• func (e *Entry) WithFields(fielder Fielder) *Entry
• func (e Entry) WithLevel(level Level) *Entry
• type Field
• type Fielder
• type Fields
• func (f Fields) Fields() Fields
• type FieldsFunc
• func NewFieldsFunc(fn func() Fields) FieldsFunc
• func (f FieldsFunc) Fields() Fields
• type Handler
• type HandlerFunc
• func (f HandlerFunc) HandleLog(e *Entry) error
• type Level
• func MustParseLevel(s string) Level
• func ParseLevel(s string) (Level, error)
• func (l Level) MarshalJSON() ([]byte, error)
• func (l Level) String() string
• func (l *Level) UnmarshalJSON(b []byte) error
• type LevelLogger
• type Logger
• func New(cfg Options) Logger
• type Options
• type String
• func (s String) String() string
• type StringFunc
• func (f StringFunc) String() string

Examples ¶

• package
• package (Lazy_evaluation)

Variables ¶

var ErrInvalidLevel = errors.New("invalid level")

ErrInvalidLevel is returned if the severity level is invalid.

var ErrStopLogEntry = fmt.Errorf("stop log entry")

ErrStopLogEntry is a sentinel error that can be returned from a handler to stop the entry from being passed to the next handler.

Types ¶

type Clock ¶

type Clock interface {
	Now() time.Time
}

Clock provides the current time.

type Entry ¶

type Entry struct {
	Level     Level     `json:"level"`
	Timestamp time.Time `json:"timestamp"`
	Fields    Fields    `json:"fields,omitempty"`
	Message   string    `json:"message"`
	// contains filtered or unexported fields
}

Entry represents a single log entry at a given log level.

func NewEntry ¶

func NewEntry(log *logger) *Entry

NewEntry returns a new entry for `log`.

func (*Entry) Clone ¶

func (e *Entry) Clone() *Entry

Clone returns a new Entry with the same fields.

func (*Entry) Log ¶

func (e *Entry) Log(s fmt.Stringer)

Log a message at the given level.

func (*Entry) Logf ¶

func (e *Entry) Logf(format string, a ...any)

Log a message at the given level.

func (*Entry) WithDuration ¶

func (e *Entry) WithDuration(d time.Duration) *Entry

func (*Entry) WithError ¶

func (e *Entry) WithError(err error) *Entry

WithError returns a new entry with the "error" set to `err`.

The given error may implement .Fielder, if it does the method will add all its `.Fields()` into the returned entry.

func (*Entry) WithField ¶

func (e *Entry) WithField(key string, value any) *Entry

func (*Entry) WithFields ¶

func (e *Entry) WithFields(fielder Fielder) *Entry

func (Entry) WithLevel ¶

func (e Entry) WithLevel(level Level) *Entry

type Field ¶

type Field struct {
	Name  string `json:"name"`
	Value any    `json:"value"`
}

Field holds a named value.

type Fielder ¶

type Fielder interface {
	Fields() Fields
}

Fielder is an interface for providing fields to custom types.

type Fields ¶

type Fields []Field

Fields represents a slice of entry level data used for structured logging.

func (Fields) Fields ¶

func (f Fields) Fields() Fields

Fields implements Fielder.

type FieldsFunc ¶

type FieldsFunc func() Fields

func NewFieldsFunc ¶

func NewFieldsFunc(fn func() Fields) FieldsFunc

func (FieldsFunc) Fields ¶

func (f FieldsFunc) Fields() Fields

type Handler ¶

type Handler interface {
	// HandleLog is invoked for each log event.
	// Note that if the Entry is going to be used after the call to HandleLog
	// in the handler chain returns, it must be cloned with Clone(). See
	// the memory.Handler implementation for an example.
	//
	// The Entry can be modified if needed, e.g. when passed down via
	// a multi.Handler (e.g. to sanitize the data).
	HandleLog(e *Entry) error
}

Handler is used to handle log events, outputting them to stdio or sending them to remote services. See the "handlers" directory for implementations.

It is left up to Handlers to implement thread-safety.

type HandlerFunc ¶

type HandlerFunc func(*Entry) error

The HandlerFunc type is an adapter to allow the use of ordinary functions as log handlers. If f is a function with the appropriate signature, HandlerFunc(f) is a Handler object that calls f.

func (HandlerFunc) HandleLog ¶

func (f HandlerFunc) HandleLog(e *Entry) error

HandleLog calls f(e).

type Level ¶

type Level int

Level of severity.

const (
	LevelInvalid Level = iota
	LevelTrace
	LevelDebug
	LevelInfo
	LevelWarn
	LevelError
)

Log levels.

func MustParseLevel ¶

func MustParseLevel(s string) Level

MustParseLevel parses level string or panics.

func ParseLevel ¶

func ParseLevel(s string) (Level, error)

ParseLevel parses level string.

func (Level) MarshalJSON ¶

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

MarshalJSON implementation.

func (Level) String ¶

func (l Level) String() string

String implementation.

func (*Level) UnmarshalJSON ¶

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

UnmarshalJSON implementation.

type LevelLogger ¶

type LevelLogger interface {
	// Log logs a message at the given level using the string from calling s.String().
	// Note that s.String() will not be called if the level is not enabled.
	Log(s fmt.Stringer)

	// Logf logs a message at the given level using the format and args from calling fmt.Sprintf().
	// Note that fmt.Sprintf() will not be called if the level is not enabled.
	Logf(format string, a ...any)

	// WithLevel returns a new entry with `level` set.
	WithLevel(Level) *Entry

	// WithFields returns a new entry with the`fields` in fields set.
	// This is a noop if LevelLogger's level is less than Logger's.
	WithFields(fields Fielder) *Entry

	// WithLevel returns a new entry with the field f set with value v
	// This is a noop if LevelLogger's level is less than Logger's.
	WithField(f string, v any) *Entry

	// WithDuration returns a new entry with the "duration" field set
	// to the given duration in milliseconds.
	// This is a noop if LevelLogger's level is less than Logger's.
	WithDuration(time.Duration) *Entry

	// WithError returns a new entry with the "error" set to `err`.
	// This is a noop if err is nil or  LevelLogger's level is less than Logger's.
	WithError(error) *Entry
}

LevelLogger is the logger at a given level.

type Logger ¶

type Logger interface {
	// WithLevel returns a new entry with `level` set.
	WithLevel(Level) *Entry
}

Logger is the main interface for the logger.

func New ¶

func New(cfg Options) Logger

New returns a new logger.

type Options ¶

type Options struct {
	// Level is the minimum level to log at.
	// If not set, defaults to InfoLevel.
	Level Level

	// Handler is the log handler to use.
	Handler Handler

	// Clock is the clock to use for timestamps.
	// If not set, the system clock is used.
	Clock Clock
}

Options is the set of options used to configure a logger.

type String ¶

type String string

String implements fmt.Stringer and can be used directly in the log methods.

func (String) String ¶

func (s String) String() string

type StringFunc ¶

type StringFunc func() string

StringFunc is a function that returns a string. It also implements the fmt.Stringer interface and can therefore be used as argument to the log methods.

func (StringFunc) String ¶

func (f StringFunc) String() string

Source Files ¶

doc.go entry.go handler.go interfaces.go levels.go logger.go objectpools.go stack.go

Directories ¶