log

README

Log

Log is a library which provides utilities for logging messages

Getting started

To retrieve the library, simply run:

go get code.waarp.fr/lib/log

Then import it in your project

import "code.waarp.fr/lib/log"

Basic Usage

In order to create a logger, its backend must first be initialized. Logging backends can be initialized using the NewBackend function. This function requires the following arguments:

1. level- The minimum logging level. All messages bellow this level will be ignored.
2. logTo- The logs output.
3. facility- The logging facility (only used for syslog backends).
4. tag- The application's tag in the logging facility (only used for syslog backends).

Once the backend initialized, loggers can be created using the Backend.NewLogger method. This will return a new logger with the given name, and which writes to the target backend.

License

Log is licensed under the terms of the MIT License which are detailed in the LICENSE file.

Documentation

Overview

Package log provides utilities for logging messages to various outputs.

Index

• Constants
• Variables
• type Backend
  • func NewBackend(level Level, logTo, facility, tag string) (*Backend, error)
  • func (b *Backend) ChangeLevel(level Level)
  • func (b *Backend) NewLogger(name string) *Logger
  • func (b *Backend) SetOutput(w io.Writer)
• type BackendPool
  • func (b *BackendPool) AddBackend(back *Backend)
  • func (b *BackendPool) Enabled(ctx context.Context, level slog.Level) bool
  • func (b *BackendPool) Handle(ctx context.Context, record slog.Record) error
  • func (b *BackendPool) NewLogger(name string) *Logger
  • func (b *BackendPool) WithAttrs(attrs []slog.Attr) slog.Handler
  • func (b *BackendPool) WithGroup(name string) slog.Handler
• type Formatter
• type Level
  • func (l Level) Name() string
  • func (i Level) String() string
• type Logger
  • func (l *Logger) Alert(text string)
  • func (l *Logger) Alertf(text string, args ...any)
  • func (l *Logger) AsStdLogger(level Level) *log.Logger
  • func (l *Logger) Critical(text string)
  • func (l *Logger) Criticalf(text string, args ...any)
  • func (l *Logger) Debug(text string)
  • func (l *Logger) Debugf(text string, args ...any)
  • func (l *Logger) Error(text string)
  • func (l *Logger) Errorf(text string, args ...any)
  • func (l *Logger) Fatal(text string)
  • func (l *Logger) Fatalf(text string, args ...any)
  • func (l *Logger) Info(text string)
  • func (l *Logger) Infof(text string, args ...any)
  • func (l *Logger) Log(level Level, m string)
  • func (l *Logger) Notice(text string)
  • func (l *Logger) Noticef(text string, args ...any)
  • func (l *Logger) Slogger() *slog.Logger
  • func (l *Logger) Trace(text string)
  • func (l *Logger) Tracef(text string, args ...any)
  • func (l *Logger) Warning(text string)
  • func (l *Logger) Warningf(text string, args ...any)
• type Record

Constants

const (
	Stdout  = "stdout"
	Stderr  = "stderr"
	Discard = "discard"
	Syslog  = "syslog"
)

Variables

var ErrUnknownFacility = errors.New("unknown facility")

Types

type Backend

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

func NewBackend

func NewBackend(level Level, logTo, facility, tag string) (*Backend, error)

NewBackend initializes the logging backend according to the given configuration. If the backend cannot be accessed, an error is returned.

Level represents the minimum logging priority accepted by the backend. Any message with a lower priority will be discarded.

LogTo is the logging output. It can be either: - Stdout - Stderr - Discard - Syslog - a file name

Facility and Tag are only used with a Syslog output. They represent respectively the logging facility and the application's name (in the logging facility).

func (*Backend) ChangeLevel

func (b *Backend) ChangeLevel(level Level)

func (*Backend) NewLogger

func (b *Backend) NewLogger(name string) *Logger

NewLogger initiates and returns a new logger with the target Backend as output.

func (*Backend) SetOutput

func (b *Backend) SetOutput(w io.Writer)

type BackendPool

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

BackendPool represent a pool of backends. When instantiating a Logger from a pool of backend, any message written to this Logger will be written to all to backends from the pool. This can be useful if one wishes to send log messages to different outputs depending on the message's level.

func (*BackendPool) AddBackend

func (b *BackendPool) AddBackend(back *Backend)

AddBackend adds a backend to the pool.

func (*BackendPool) Enabled

func (b *BackendPool) Enabled(ctx context.Context, level slog.Level) bool

func (*BackendPool) Handle

func (b *BackendPool) Handle(ctx context.Context, record slog.Record) error

func (*BackendPool) NewLogger

func (b *BackendPool) NewLogger(name string) *Logger

NewLogger initiates and returns a new logger with all the pool's backends as output.

func (*BackendPool) WithAttrs

func (b *BackendPool) WithAttrs(attrs []slog.Attr) slog.Handler

func (*BackendPool) WithGroup

func (b *BackendPool) WithGroup(name string) slog.Handler

type Formatter

type Formatter func(*Record) string

Formatter is the types of the functions that can be used to format a log entry. They take a pointer to a record and return a formatted string.

type Level

type Level slog.Level

Level represents a logging level. Available levels are: - LevelDebug - LevelInfo - LevelNotice - LevelWarning - LevelError - LevelCritical - LevelAlert - LevelFatal.

const (
	LevelTrace    Level = -6
	LevelDebug    Level = Level(slog.LevelDebug) // -4
	LevelInfo     Level = Level(slog.LevelInfo)  // 0
	LevelNotice   Level = 2
	LevelWarning  Level = Level(slog.LevelWarn)  // 4
	LevelError    Level = Level(slog.LevelError) // 8
	LevelCritical Level = 10
	LevelAlert    Level = 12
	LevelFatal    Level = 14
)

func (Level) Name

func (l Level) Name() string

func (Level) String

func (i Level) String() string

type Logger

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

Logger is an internal abstraction of the underlying logging library.

func (*Logger) Alert

func (l *Logger) Alert(text string)

Alert logs a message with the Alert level.

func (*Logger) Alertf

func (l *Logger) Alertf(text string, args ...any)

Alertf formats the message with given args and logs the result with the. Alert level.

func (*Logger) AsStdLogger

func (l *Logger) AsStdLogger(level Level) *log.Logger

AsStdLogger returns an instance of the standard log.Logger. Any messages written to this standard logger will be written to the source logger with the given level.

func (*Logger) Critical

func (l *Logger) Critical(text string)

Critical logs a message with the Critical level.

func (*Logger) Criticalf

func (l *Logger) Criticalf(text string, args ...any)

Criticalf formats the message with given args and logs the result with the. Critical level.

func (*Logger) Debug

func (l *Logger) Debug(text string)

Debug logs a message with the Debug level.

func (*Logger) Debugf

func (l *Logger) Debugf(text string, args ...any)

Debugf formats the message with given args and logs the result with the Debug level.

func (*Logger) Error

func (l *Logger) Error(text string)

Error logs a message with the Error level.

func (*Logger) Errorf

func (l *Logger) Errorf(text string, args ...any)

Errorf formats the message with given args and logs the result with the Error level.

func (*Logger) Fatal

func (l *Logger) Fatal(text string)

Fatal logs a message with the Fatal level.

func (*Logger) Fatalf

func (l *Logger) Fatalf(text string, args ...any)

Fatalf formats the message with given args and logs the result with the Fatal level.

func (*Logger) Info

func (l *Logger) Info(text string)

Info logs a message with the Info level.

func (*Logger) Infof

func (l *Logger) Infof(text string, args ...any)

Infof formats the message with given args and logs the result with the Info level.

func (*Logger) Log

func (l *Logger) Log(level Level, m string)

Log sends a record containing the message `m` to the registered backends whose level is at least `level`.

func (*Logger) Notice

func (l *Logger) Notice(text string)

Notice logs a message with the Notice level.

func (*Logger) Noticef

func (l *Logger) Noticef(text string, args ...any)

Noticef formats the message with given args and logs the result with the Notice level.

func (*Logger) Slogger

func (l *Logger) Slogger() *slog.Logger

func (*Logger) Trace

func (l *Logger) Trace(text string)

Trace logs a message with the Trace level.

func (*Logger) Tracef

func (l *Logger) Tracef(text string, args ...any)

Tracef formats the message with given args and logs the result with the Trace level.

func (*Logger) Warning

func (l *Logger) Warning(text string)

Warning logs a message with the Warning level.

func (*Logger) Warningf

func (l *Logger) Warningf(text string, args ...any)

Warningf formats the message with given args and logs the result with the Warning level.

type Record

type Record struct {
	Logger    string
	Timestamp time.Time
	Level     Level
	Message   string
}

Record contains the data to be logged. It is passed to a formatter to generate the logged message.