rogu

README

rogu

ログ (rogu, jap. log) is yet another taggable, human readable, colorful, structured logging package with a builder-like API. This package is mainly created to be used within shinpuru and other projects of mine. Feel free to use it too, but beware that this package is not optimized for performance.

Warning
Just wanna let you know, the API of this package is not yet final and might change in coming updates.

This package is very much inspired by the colored output style of charmbracelet/log and the builder API style of rs/zerolog.

Levels

Log levels can be set to a Logger via the SetLevel method. Levels are defined in the sub-package level. Levels can be interpreted from a string using the function LevelFromString. Below, you can see available levels with their numeral values, names and aliases. The given names and aliases are valid values which can be passed to LevelFromString.

Level	Numeral Value	Name and aliases
Panic	1	"panic", "pnc", "p", "1"
Fatal	2	"fatal", "ftl", "f", "2"
Error	3	"error", "err", "e", "3"
Warn	4	"warn", "wrn", "w", "4"
Info	5	"info", "inf", "i", "5"
Debug	6	"debug", "dbg", "f", "6"
Trace	7	"trace", "trc", "t", "7"

slog Support

The rogu.Logger can be used as slog.Handler, so that rogu's pretty writer can be used to format slog records.

roguLogger := slog.New(rogu.NewLogger(rogu.NewPrettyWriter()))
slog.SetDefault(roguLogger)

slog.Info("Hello, world!")

See example/slog for a more complete example.

Because of the architecture of rogu, some implications of slog are not met. Keep those in mind when using rogu as your slog backend!

• In rogu loggers, the caller is recorded when an event has been sent (using e.Send() or e.Msg(...)). Slog on the other hand sets the caller to the function which has created the record/event.
• Also, rogu records the event time when the event has been sent. Slog, on the other hand, records the event time when the record/event has been created.

Documentation

Index

• func ErrorAttr(err error) slog.Attr
• type Closer
• type Event
  • func (t *Event) Caller() *Event
  • func (t *Event) Discard()
  • func (t *Event) Enabled(_ context.Context, lvl slog.Level) bool
  • func (t *Event) Err(err error) *Event
  • func (t *Event) Errf(err error, format string) *Event
  • func (t *Event) Field(key, value any) *Event
  • func (t *Event) Fields(kv ...any) *Event
  • func (t *Event) Handle(_ context.Context, rec slog.Record) error
  • func (t *Event) Msg(v string) error
  • func (t *Event) Msgf(format string, args ...any) error
  • func (t *Event) Reset()
  • func (t *Event) Send() error
  • func (t *Event) Tag(tag string) *Event
  • func (t *Event) WithAttrs(attrs []slog.Attr) slog.Handler
  • func (t *Event) WithGroup(name string) slog.Handler
• type Field
  • func (t *Field) Reset()
• type JsonWriter
  • func NewJsonWriter(outputs ...io.Writer) *JsonWriter
  • func (t *JsonWriter) Close() error
  • func (t *JsonWriter) Write(lvl level.Level, fields []*Field, tag string, lErr error, lErrFormat string, ...) (err error)
• type Logger
  • func NewLogger(writer ...Writer) Logger
• type MultiWriter
  • func (t MultiWriter) Close() error
  • func (t MultiWriter) Write(lvl level.Level, fields []*Field, tag string, lErr error, lErrFormat string, ...) (err error)
• type PrettyWriter
  • func NewPrettyWriter(outputs ...io.Writer) *PrettyWriter
  • func (t *PrettyWriter) Close() error
  • func (t *PrettyWriter) Write(lvl level.Level, fields []*Field, tag string, lErr error, lErrFormat string, ...) (err error)
• type Writer

Functions

func ErrorAttr

func ErrorAttr(err error) slog.Attr

Types

type Closer

type Closer interface {
	Close() error
}

Closer is used to close stuff. 🤯

type Event

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

Event is used to build and send log messages.

func (*Event) Caller

func (t *Event) Caller() *Event

Caller adds the current file and line to the event.

func (*Event) Discard

func (t *Event) Discard()

Discard simply throws away the event and gives back the used resources.

This should always be called when an event will not be commited.

func (*Event) Enabled

func (t *Event) Enabled(_ context.Context, lvl slog.Level) bool

func (*Event) Err

func (t *Event) Err(err error) *Event

Err sets an error value to the event.

func (*Event) Errf

func (t *Event) Errf(err error, format string) *Event

Errf sets an error value to the event formatted in the given format string.

func (*Event) Field

func (t *Event) Field(key, value any) *Event

Field adds a single key-value field.

func (*Event) Fields

func (t *Event) Fields(kv ...any) *Event

Fields adds passed value alternating as keys and values to the events fields.

When an odd number of values is passed, the last field's value will be nil.

Example:

rogu.Info().Fields(
    "name", "Bob",
    "age", 24,
    "hobbies", []stirng{"biking", "football", "gaming"},
)

func (*Event) Handle

func (t *Event) Handle(_ context.Context, rec slog.Record) error

func (*Event) Msg

func (t *Event) Msg(v string) error

Msg commits the event to the writer with the given message string returning an error when the log writing failed.

func (*Event) Msgf

func (t *Event) Msgf(format string, args ...any) error

Msgf is an alias for Msg with a format and given values.

func (*Event) Reset

func (t *Event) Reset()

func (*Event) Send

func (t *Event) Send() error

Send commits the event without any message.

func (*Event) Tag

func (t *Event) Tag(tag string) *Event

Tag sets the tag of the event.

This will overwtite the tag set by the logger.

func (*Event) WithAttrs

func (t *Event) WithAttrs(attrs []slog.Attr) slog.Handler

func (*Event) WithGroup

func (t *Event) WithGroup(name string) slog.Handler

type Field

type Field struct {
	Key any
	Val any
	// contains filtered or unexported fields
}

Field hols a hey-value pair of any type.

func (*Field) Reset

func (t *Field) Reset()

type JsonWriter

type JsonWriter struct {
	Output     io.Writer
	TimeFormat string
	// contains filtered or unexported fields
}

JsonWriter implements Writer for JSON formatted entry output.

func NewJsonWriter

func NewJsonWriter(outputs ...io.Writer) *JsonWriter

NewJsonWriter returns a new JsonWriter with the passed target output writers.

func (*JsonWriter) Close

func (t *JsonWriter) Close() error

func (*JsonWriter) Write

func (t *JsonWriter) Write(
	lvl level.Level,
	fields []*Field,
	tag string,
	lErr error,
	lErrFormat string,
	callerFile string,
	callerLine int,
	msg string,
) (err error)

type Logger

type Logger interface {
	Closer

	slog.Handler

	AddWriter(w Writer) Logger
	Copy() *logger
	Debug() *Event
	Error() *Event
	Fatal() *Event
	Info() *Event
	Panic() *Event
	SetCaller(enable bool) Logger
	SetLevel(lvl level.Level) Logger
	SetWriter(w Writer) Logger
	Tagged(tag string) Logger
	Trace() *Event
	Warn() *Event
	WithLevel(lvl level.Level) *Event
}

Logger is used to create log events and to specify writers which are used to write commited events.

func NewLogger

func NewLogger(writer ...Writer) Logger

NewLogger returns a new instance of Logger with the passed writers.

If no writer is specified or set via `SetWriter`, the logger will never output anything.

type MultiWriter

type MultiWriter []Writer

MultiWriter writes events to multiple registered writers.

func (MultiWriter) Close

func (t MultiWriter) Close() error

Close closes the set writers or all writers that are added to the logger and which are closable.

func (MultiWriter) Write

func (t MultiWriter) Write(
	lvl level.Level,
	fields []*Field,
	tag string,
	lErr error,
	lErrFormat string,
	callerFile string,
	callerLine int,
	msg string,
) (err error)

type PrettyWriter

type PrettyWriter struct {
	Output io.Writer

	NoColor    bool
	TimeFormat string

	StyleTimestamp          lipgloss.Style
	StyleLevelPanic         lipgloss.Style
	StyleLevelFatal         lipgloss.Style
	StyleLevelError         lipgloss.Style
	StyleLevelWarn          lipgloss.Style
	StyleLevelInfo          lipgloss.Style
	StyleLevelDebug         lipgloss.Style
	StyleLevelTrace         lipgloss.Style
	StyleCaller             lipgloss.Style
	StyleTag                lipgloss.Style
	StyleFieldKey           lipgloss.Style
	StyleFieldValue         lipgloss.Style
	StyleFieldMultipleKey   lipgloss.Style
	StyleFieldMultipleIndex lipgloss.Style
	StyleFieldMultipleValue lipgloss.Style
	StyleFieldErrorKey      lipgloss.Style
	StyleFieldErrorValue    lipgloss.Style
	StyleMessage            lipgloss.Style
	// contains filtered or unexported fields
}

PrettyWriter implements Writer for human readable, colorful, structured console output.

You can set NoColor to true to supress colorful formatting.

With setting TimeFormat you specify the format of the timestamp and time.Time field values. When TimeFormat is set to an empty string, no timestamp will be printed.

If you want to alter the style of the output, feel free to set custom definitions for the defined styles.

func NewPrettyWriter

func NewPrettyWriter(outputs ...io.Writer) *PrettyWriter

NewPrettyWriter returns a new instance of PrettyWriter with the given output writers. When no writers are specified, os.Stdout will be used.

func (*PrettyWriter) Close

func (t *PrettyWriter) Close() error

func (*PrettyWriter) Write

func (t *PrettyWriter) Write(
	lvl level.Level,
	fields []*Field,
	tag string,
	lErr error,
	lErrFormat string,
	callerFile string,
	callerLine int,
	msg string,
) (err error)

type Writer

type Writer interface {
	Write(
		lvl level.Level,
		fields []*Field,
		tag string,
		err error,
		errFormat string,
		callerFile string,
		callerLine int,
		msg string,
	) error
}

Writer takes log entry components and writes them somewhere.