log

package module
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 23, 2026 License: Apache-2.0 Imports: 11 Imported by: 0

README

log

A logging package for Go.

Installation

go get -u github.com/tfoertsch123/log

What is it?

Classical logging with log levels and messages. No structured logging.

The following log levels are defined:

  • NOTICE - printed always
  • PANIC - print + exit(1)
  • ERROR
  • WARN
  • INFO
  • DEBUG
  • DEBG2
  • DEBG3
  • DEBG4
  • DEBG5

The log target is an io.Writer, by default os.Stderr.

A logger can have a topic or subsystem.

Log messages look like so:

TIMESTAMP LEVEL [TOPIC] (CODE LOCATION) MESSAGE

Topic and code location are optional.

Examples:

2026-10-05 09:02:05.987654 INFO message without a topic
2026-10-05 09:02:05.987654 DEBUG (log/exmpl01_log_test.go:21) with code location
2026-10-05 09:02:05.987654 DEBUG [TPC] (log/exmpl01_log_test.go:27) with topic and location

The timestamp can be configured. Default precision is microseconds.

The code location is printed for a certain log level and above. The file name is printed with a specific number of directory components. This can also be configured.

The package allows you to construct a tree of loggers. Any configuration change with the exception of the topic propagates to all of its kids recursively.

That allows you for instance to set up static loggers with different topics and later modify the log level for all of them.

var base *log.Logger = log.NewR(log.WithOutput(...))
var tpc1 *log.Logger = base.New(log.WithTopic("TOPIC1"))
var tpc2 *log.Logger = base.New(log.WithTopic("TOPIC2"))

func subsys1() {
    tpc1.Info(`message`)
}

func subsys2() {
    tpc2.Info(`message`)
}

func main() {
    base.SetLevel(log.DEBUG)
    ...
}

Alternatively, you can rely on the default logger:

func subsys1() {
    log.NewC(log.WithTopic(`TOPIC1`))
    defer log.Close()

    log.Info(`message`)
}

func subsys2() {
    log.NewC(log.WithTopic(`TOPIC2`))
    defer log.Close()

    log.Info(`message`)
}

func main() {
    log.SetLevel(log.DEBUG)
    log.SetOutput(...)
}

Documentation

Overview

Package log implements a simple logging package with a hierarchical logger tree. Each logger can have children, and configuration changes propagate to descendants. The package is thread-safe; all exported methods are safe for concurrent use.

Each logger has an optional topic. The idea is that this is the main distinction between loggers. Think of the topic as subsystem or part of the code.

Please check out the provided examples to get a better understanding.

A log message consists of a timestamp, a log level, an optional topic, an optional code location and the actual message.

The package defines the following log levels: NOTICE (printed always), PANIC (print and exit 1), ERROR, WARN, INFO, DEBUG, DEBG2, DEBG3, DEBG4, DEBG5

The root logger comes with the folowing properties: log level = WARN (a message logged with a higher level will NOT be printed); no topic; the output is sent to os.Stderr; the timeformat is 2006-01-02 15:04:05.000000; code locations are included in DEBUG and above; the location contains the fully qualified file name and multiline mode is turned off.

At the beginning the only existing logger is the root logger. Derived loggers can be created using New(). Options passed to New() allow to configure the child logger.

Another concept is that of the current logger. It is created using the package level New() function or using the SetCurrent() function. The current logger is used by all package level functions.

All properties of a logger except the topic can be changed after creation. A property change is propagated to all derived loggers recursively. So, if you change the log level of the root logger, this change is inherited by all other loggers.

Example (Lazy) 
package main

import (
	"github.com/tfoertsch123/log"
	"math"
	"os"
	"time"
)

func main() {
	// Use SetNow() to generate a fixed timestamp. This is only needed
	// to have this pass as a test so that go doc includes the example.
	defer func(orig func() time.Time) { log.SetNow(orig) }(log.SetNow(func() time.Time {
		return time.Date(2026, 10, 5, 9, 2, 5, 987654321, time.UTC)
	}))
	log.SetOutput(os.Stdout)
	defer log.Root().Close() // reset/close all loggers

	complex_work := func() string {
		time.Sleep(100 * time.Millisecond)
		return "done"
	}

	ms := time.Millisecond

	// The log level is WARN. So, nothing will be printed.
	// Yet it still takes time.
	now := time.Now()

	log.Infof("complex_work: %s", complex_work())

	log.Warnf("complex_work took %vms +/- 20ms",
		20*math.Round(float64(time.Now().Sub(now))/float64(20*ms)),
	)

	now = time.Now()

	// Now with lazy execution. This should take almost no time
	// since complex_work() is not executed.
	log.Infol("complex_work: %s", func() interface{} { return complex_work() })

	log.Warnf("complex_work with lazy execution took %vms +/- 20ms",
		20*math.Round(float64(time.Now().Sub(now))/float64(20*ms)),
	)

	// Now let's raise the log level and repeat the previous.
	// It should take ~100ms
	log.SetLevel(log.INFO)

	now = time.Now()

	log.Infol("complex_work: %s", func() interface{} { return complex_work() })

	log.Warnf("complex_work if actually done took %vms +/- 20ms",
		20*math.Round(float64(time.Now().Sub(now))/float64(20*ms)),
	)

}

Output:
2026-10-05 09:02:05.987654 WARN complex_work took 100ms +/- 20ms
2026-10-05 09:02:05.987654 WARN complex_work with lazy execution took 0ms +/- 20ms
2026-10-05 09:02:05.987654 NOTICE Setting log level from WARN to INFO
2026-10-05 09:02:05.987654 INFO complex_work: done
2026-10-05 09:02:05.987654 WARN complex_work if actually done took 100ms +/- 20ms
Example (Multiline) 
package main

import (
	"github.com/tfoertsch123/log"
	"os"
	"time"
)

func main() {
	// Use SetNow() to generate a fixed timestamp. This is only needed
	// to have this pass as a test so that go doc includes the example.
	defer func(orig func() time.Time) { log.SetNow(orig) }(log.SetNow(func() time.Time {
		return time.Date(2026, 10, 5, 9, 2, 5, 987654321, time.UTC)
	}))
	log.SetOutput(os.Stdout)
	defer log.Root().Close() // reset/close all loggers

	log.Notice("this\nis a\nmultiline\nmessage")

	log.NewC(log.WithMultiLine(true))

	log.Notice("this\nis a\nmultiline\nmessage")
}

Output:
2026-10-05 09:02 NOTICE this
is a
multiline
message
2026-10-05 09:02 NOTICE this
2026-10-05 09:02 NOTICE is a
2026-10-05 09:02 NOTICE multiline
2026-10-05 09:02 NOTICE message

Index

Examples

Constants

This section is empty.

Variables

View Source 
var ErrInvalidLevel error = errors.New(`invalid log level`)

ErrInvalidLevel is returned by ParseLevel when the input string does not match any known log level.

Functions

func Close 

func Close()

Close closes the current logger and all its descendants.

func Debg2 

func Debg2(m string)

Debg2 logs a debug message at level 2 using the current logger.

func Debg2f 

func Debg2f(f string, p ...interface{})

Debg2f logs a formatted debug message at level 2 using the current logger.

func Debg2l 

func Debg2l(f string, p ...interface{})

Debg2l logs a message with late evaluation at debug level 2 using the current logger.

func Debg3 

func Debg3(m string)

Debg3 logs a debug message at level 3 using the current logger.

func Debg3f 

func Debg3f(f string, p ...interface{})

Debg3f logs a formatted debug message at level 3 using the current logger.

func Debg3l 

func Debg3l(f string, p ...interface{})

Debg3l logs a message with late evaluation at debug level 3 using the current logger.

func Debg4 

func Debg4(m string)

Debg4 logs a debug message at level 4 using the current logger.

func Debg4f 

func Debg4f(f string, p ...interface{})

Debg4f logs a formatted debug message at level 4 using the current logger.

func Debg4l 

func Debg4l(f string, p ...interface{})

Debg4l logs a message with late evaluation at debug level 4 using the current logger.

func Debg5 

func Debg5(m string)

Debg5 logs a debug message at level 5 using the current logger.

func Debg5f 

func Debg5f(f string, p ...interface{})

Debg5f logs a formatted debug message at level 5 using the current logger.

func Debg5l 

func Debg5l(f string, p ...interface{})

Debg5l logs a message with late evaluation at debug level 5 using the current logger.

func Debug 

func Debug(m string)

Debug logs a debug message using the current logger.

func Debugf 

func Debugf(f string, p ...interface{})

Debugf logs a formatted debug message using the current logger.

func Debugl 

func Debugl(f string, p ...interface{})

Debugl logs a message with late evaluation at debug level using the current logger.

func Error 

func Error(m string)

Error logs an error message using the current logger.

func Errorf 

func Errorf(f string, p ...interface{})

Errorf logs a formatted error message using the current logger.

func Errorl 

func Errorl(f string, p ...interface{})

Errorl logs a message with late evaluation at error level using the current logger.

func GetLocDirectories 

func GetLocDirectories() int

GetLocDirectories returns the current logger’s directory component count.

func GetMultiLine 

func GetMultiLine() bool

GetMultiLine returns true if multiline mode is on for the current logger.

func GetOutput 

func GetOutput() io.Writer

GetOutput returns the current logger’s output writer.

func GetTimeFmt 

func GetTimeFmt() string

GetTimeFmt returns the current logger’s time format string.

func Info 

func Info(m string)

Info logs an info message using the current logger.

func Infof 

func Infof(f string, p ...interface{})

Infof logs a formatted info message using the current logger.

func Infol 

func Infol(f string, p ...interface{})

Infol logs a message with late evaluation at info level using the current logger.

func Log 

func Log(lvl Level, m string)

Log outputs a message at the given level using the current logger. See Log above.

func Logf 

func Logf(lvl Level, f string, p ...interface{})

Logf outputs a formatted message at the given level using the current logger.

func Logl 

func Logl(lvl Level, f string, p ...interface{})

Logl outputs a formatted message with late evaluation using the current logger.

func Notice 

func Notice(m string)

Notice logs a notice message using the current logger.

func Noticef 

func Noticef(f string, p ...interface{})

Noticef logs a formatted notice message using the current logger.

func Noticel 

func Noticel(f string, p ...interface{})

Noticel logs a message with late evaluation at notice level using the current logger.

func Panic 

func Panic(m string)

Panic logs a panic message using the current logger and exits with code 1.

func Panicf 

func Panicf(f string, p ...interface{})

Panicf logs a formatted panic message using the current logger and exits with code 1.

func Panicl 

func Panicl(f string, p ...interface{})

Panicl logs a message with late evaluation at panic level using the current logger and exits with code 1.

func SetLevel 

func SetLevel(lvl Level)

SetLevel sets the minimum log level on the current logger and all its descendants.

func SetLocDirectories 

func SetLocDirectories(n int)

SetLocDirectories sets the directory component count on the current logger and its descendants.

func SetMinLocation 

func SetMinLocation(lvl Level)

SetMinLocation sets the minimum location level on the current logger and its descendants.

func SetMultiLine 

func SetMultiLine(ml bool)

SetMultiLine turns multiline mode on or off for the current logger and all its descendants.

func SetNow 

func SetNow(now_f func() time.Time) func() time.Time

SetNow allows to change this package's notion of now. It's intended to be used mainly for testing and debugging purposes. The default value is time.Now.

func SetOutput 

func SetOutput(out io.Writer)

SetOutput sets the output writer on the current logger and its descendants.

func SetTimeFmt 

func SetTimeFmt(f string)

SetTimeFmt sets the time format string on the current logger and its descendants.

func Warn 

func Warn(m string)

Warn logs a warning message using the current logger.

func Warnf 

func Warnf(f string, p ...interface{})

Warnf logs a formatted warning message using the current logger.

func Warnl 

func Warnl(f string, p ...interface{})

Warnl logs a message with late evaluation at warning level using the current logger.

Types

type Level 

type Level int8

Level represents a log severity level. Lower values indicate higher severity. The zero value of Level is PANIC. Use ToLevel or ParseLevel to obtain a valid Level. 

const (
	// NOTICE is a special level that always prints, regardless of the
	// logger's threshold. It is the only level that can be lower than PANIC.
	NOTICE Level = iota - 1
	// PANIC is the highest severity. Logging at this level will also call
	// os.Exit(1).
	PANIC
	// ERROR indicates an error condition.
	ERROR
	// WARN indicates a warning condition.
	WARN
	// INFO indicates an informational message.
	INFO
	// DEBUG indicates a debug message.
	DEBUG
	// DEBG2 is a more verbose debug level.
	DEBG2
	// DEBG3 is an even more verbose debug level.
	DEBG3
	// DEBG4 is a highly verbose debug level.
	DEBG4
	// DEBG5 is the most verbose debug level.
	DEBG5
)

func GetLevel 

func GetLevel() Level

GetLevel returns the current logger’s minimum log level.

func GetMinLocation 

func GetMinLocation() Level

GetMinLocation returns the current logger’s minimum location level.

func ParseLevel 

func ParseLevel(s string) (Level, error)

ParseLevel parses a string into a Level. It accepts case-insensitive names: "notice", "panic", "error", "warn"/"warning", "info", "debug", "debug2"/"debg2", "debug3"/"debg3", "debug4"/"debg4", "debug5"/"debg5", or the numeric strings "0" through "8". Returns ErrInvalidLevel if the string does not match.

func ToLevel 

func ToLevel(i int) Level

ToLevel converts an integer to a Level, clamping it to the valid range. Values above DEBG5 are clamped to DEBG5; values below PANIC are clamped to PANIC.

func (Level) String 

func (l Level) String() string

String returns the human-readable name of the level. It returns one of: "NOTICE", "PANIC", "ERROR", "WARN", "INFO", "DEBUG", "DEBG2", "DEBG3", "DEBG4", "DEBG5".

type LogOpts 

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

LogOpts holds optional configuration for creating a new Logger via New.

type Logger 

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

Logger represents a node in a hierarchical logger tree.

func L 

func L() *Logger

L returns the current package-level logger. The current logger is used by all top-level logging functions (e.g. Log, Debug). It is protected by a global mutex; use this function to obtain a consistent snapshot.

func NewC 

func NewC(opts ...Opt) *Logger

New creates and returns a new logger as a child of the current logger and sets it as the new current logger. Shortcut for lg=log.L().New(); lg.SetCurrent()

func NewK 

func NewK(opts ...Opt) *Logger

New creates and returns a new logger as a child of the current logger without making it the current logger. Shortcut for log.L().New().

func NewR 

func NewR(opts ...Opt) *Logger

New creates and returns a new logger as a child of the root logger without making it the current logger. Shortcut for log.Root().New().

func Root 

func Root() *Logger

Root returns a pointer to the global root logger. The root logger cannot be closed and is always available.

func (*Logger) Close 

func (l *Logger) Close() *Logger

Close closes the logger and all its descendants. After closing, the logger and its subtree are marked as closed and cannot be used. The returned pointer is the previous parent (or nil for the root). Once a logger has been closed, it will not send any messages anymore. The root logger cannot be closed. If closed, it will be reinitialized with the default values.

func (*Logger) Debg2 

func (l *Logger) Debg2(m string)

Debg2 logs a debug message at level 2.

func (*Logger) Debg2f 

func (l *Logger) Debg2f(f string, p ...interface{})

Debg2f logs a formatted debug message at level 2.

func (*Logger) Debg2l 

func (l *Logger) Debg2l(f string, p ...interface{})

Debg2l logs a message with late evaluation at debug level 2.

func (*Logger) Debg3 

func (l *Logger) Debg3(m string)

Debg3 logs a debug message at level 3.

func (*Logger) Debg3f 

func (l *Logger) Debg3f(f string, p ...interface{})

Debg3f logs a formatted debug message at level 3.

func (*Logger) Debg3l 

func (l *Logger) Debg3l(f string, p ...interface{})

Debg3l logs a message with late evaluation at debug level 3.

func (*Logger) Debg4 

func (l *Logger) Debg4(m string)

Debg4 logs a debug message at level 4.

func (*Logger) Debg4f 

func (l *Logger) Debg4f(f string, p ...interface{})

Debg4f logs a formatted debug message at level 4.

func (*Logger) Debg4l 

func (l *Logger) Debg4l(f string, p ...interface{})

Debg4l logs a message with late evaluation at debug level 4.

func (*Logger) Debg5 

func (l *Logger) Debg5(m string)

Debg5 logs a debug message at level 5.

func (*Logger) Debg5f 

func (l *Logger) Debg5f(f string, p ...interface{})

Debg5f logs a formatted debug message at level 5.

func (*Logger) Debg5l 

func (l *Logger) Debg5l(f string, p ...interface{})

Debg5l logs a message with late evaluation at debug level 5.

func (*Logger) Debug 

func (l *Logger) Debug(m string)

Debug logs a debug message.

func (*Logger) Debugf 

func (l *Logger) Debugf(f string, p ...interface{})

Debugf logs a formatted debug message.

func (*Logger) Debugl 

func (l *Logger) Debugl(f string, p ...interface{})

Debugl logs a message with late evaluation at debug level.

func (*Logger) Error 

func (l *Logger) Error(m string)

Error logs an error message.

func (*Logger) Errorf 

func (l *Logger) Errorf(f string, p ...interface{})

Errorf logs a formatted error message.

func (*Logger) Errorl 

func (l *Logger) Errorl(f string, p ...interface{})

Errorl logs a message with late evaluation at error level.

func (*Logger) GetLevel 

func (l *Logger) GetLevel() Level

GetLevel returns the logger’s current minimum log level.

func (*Logger) GetLocDirectories 

func (l *Logger) GetLocDirectories() int

GetLocDirectories returns the number of directory components shown in source locations.

func (*Logger) GetMinLocation 

func (l *Logger) GetMinLocation() Level

GetMinLocation returns the logger’s current minimum location level.

func (*Logger) GetMultiLine 

func (l *Logger) GetMultiLine() bool

GetMultiLine returns true if multiline mode is on for this logger.

func (*Logger) GetOutput 

func (l *Logger) GetOutput() io.Writer

GetOutput returns the logger’s output writer.

func (*Logger) GetTimeFmt 

func (l *Logger) GetTimeFmt() string

GetTimeFmt returns the logger’s time format string.

func (*Logger) Info 

func (l *Logger) Info(m string)

Info logs an info message.

func (*Logger) Infof 

func (l *Logger) Infof(f string, p ...interface{})

Infof logs a formatted info message.

func (*Logger) Infol 

func (l *Logger) Infol(f string, p ...interface{})

Infol logs a message with late evaluation at info level.

func (*Logger) IsClosed 

func (l *Logger) IsClosed() bool

IsClosed reports whether the logger has been closed.

func (*Logger) IsCurrent 

func (l *Logger) IsCurrent() bool

IsCurrent reports whether the logger is the current package-level logger.

func (*Logger) IsRoot 

func (l *Logger) IsRoot() bool

IsRoot reports whether the logger is the root logger.

func (*Logger) Kids 

func (l *Logger) Kids(recursive bool) []*Logger

Kids returns a list of this logger’s direct children. If recursive is true, it also includes all descendants (depth-first).

func (*Logger) Log 

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

Log outputs a message at the given level if it meets the logger’s threshold. The output includes a timestamp, level, optional topic, optional source location, and message. In multiline mode, the message is split into lines and each line is prefixed as if it was a log message on its own.

func (*Logger) Logf 

func (l *Logger) Logf(lvl Level, f string, p ...interface{})

Logf outputs a formatted message at the given level.

func (*Logger) Logl 

func (l *Logger) Logl(lvl Level, f string, p ...interface{})

Logl outputs a formatted message similar to [Fogf] with late evaluation of arguments. Arguments that are functions of type func() interface{} are called to obtain their value.

func (*Logger) New 

func (l *Logger) New(_opts ...Opt) *Logger

New creates a new child logger by copying the current logger’s configuration and applying the given options. The new logger is added to this logger’s children set.

func (*Logger) Notice 

func (l *Logger) Notice(m string)

Notice logs a notice message. Notice messages are always printed.

func (*Logger) Noticef 

func (l *Logger) Noticef(f string, p ...interface{})

Noticef logs a formatted notice message.

func (*Logger) Noticel 

func (l *Logger) Noticel(f string, p ...interface{})

Noticel logs a message with late evaluation at notice level.

func (*Logger) Panic 

func (l *Logger) Panic(m string)

Panic logs a panic message and exits with code 1.

func (*Logger) Panicf 

func (l *Logger) Panicf(f string, p ...interface{})

Panicf logs a formatted panic message and exits with code 1.

func (*Logger) Panicl 

func (l *Logger) Panicl(f string, p ...interface{})

Panicl logs a message with late evaluation at panic level and exits with code 1.

func (*Logger) SetCurrent 

func (l *Logger) SetCurrent()

SetCurrent makes this logger the current package-level logger. If l is nil, the root logger becomes current.

func (*Logger) SetLevel 

func (l *Logger) SetLevel(lvl Level)

SetLevel sets the minimum log level on the current logger and all its descendants.

func (*Logger) SetLocDirectories 

func (l *Logger) SetLocDirectories(n int)

SetLocDirectories sets the number of directory components shown in source locations for this logger and all its descendants.

func (*Logger) SetMinLocation 

func (l *Logger) SetMinLocation(lvl Level)

SetMinLocation sets the minimum log level for printing the caller’s source location on this logger and all its descendants. Levels outside the valid range disable location printing.

func (*Logger) SetMultiLine 

func (l *Logger) SetMultiLine(ml bool)

SetMultiLine turns multiline mode on or off for this logger and all its descendants.

func (*Logger) SetOutput 

func (l *Logger) SetOutput(out io.Writer)

SetOutput sets the output writer for this logger and all its descendants.

func (*Logger) SetTimeFmt 

func (l *Logger) SetTimeFmt(f string)

SetTimeFmt sets the time format string for this logger and all its descendants.

func (*Logger) String 

func (l *Logger) String() string

String satisfies the Stringer interface.

func (*Logger) Warn 

func (l *Logger) Warn(m string)

Warn logs a warning message.

func (*Logger) Warnf 

func (l *Logger) Warnf(f string, p ...interface{})

Warnf logs a formatted warning message.

func (*Logger) Warnl 

func (l *Logger) Warnl(f string, p ...interface{})

Warnl logs a message with late evaluation at warning level.

type Opt 

type Opt func(*LogOpts)

Opt is a function type used to apply optional settings to a LogOpts.

func WithLevel 

func WithLevel(lv Level) Opt

WithLevel returns an Opt that sets the minimum log level for output.

func WithLocDirectories 

func WithLocDirectories(n int) Opt

WithLocDirectories returns an Opt that sets the number of directory components to include in the printed source location. Negative values print the full path.

func WithMinLocation 

func WithMinLocation(lv Level) Opt

WithMinLocation returns an Opt that sets the minimum log level for printing the caller’s source location. Levels outside [NOTICE+1, DEBG5] disable location printing.

func WithMultiLine 

func WithMultiLine(x bool) Opt

WithTimeFmt returns an Opt that turns on/off multiline mode. In multiline mode, line breaks in the log message are detected and each line is prefixed with the normal line prefix.

func WithOutput 

func WithOutput(out io.Writer) Opt

WithOutput returns an Opt that sets the output writer.

func WithTimeFmt 

func WithTimeFmt(f string) Opt

WithTimeFmt returns an Opt that sets the time format string. The string is passed to time.Format in order to format the time stamp.

func WithTopic 

func WithTopic(tp string) Opt

WithTopic returns an Opt that sets the log topic string. The topic is prepended in square brackets (e.g. " [mytopic]"). An empty topic disables the topic prefix.

Source Files

View all Source files

Directories

Path Synopsis
examples
ex1 command
ex2 command

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.