bit

README

bit - Golang log package

Features

• levels
• calldepth
• sub loggers
• structured text output

Benchmark

goos: linux
goarch: amd64
pkg: github.com/gregoryv/bit
cpu: Intel(R) Xeon(R) E-2288G CPU @ 3.70GHz
BenchmarkOutput
BenchmarkOutput/bit_Logger.Log-16          9313573     127.6 ns/op       0 B/op       0 allocs/op
BenchmarkOutput/log_Logger.Print-16        6967647     164.4 ns/op       0 B/op       0 allocs/op
BenchmarkOutput/bit_Logger.Log_fields-16    664618      1768 ns/op     208 B/op      10 allocs/op
BenchmarkOutput/slog_Logger.Info_fields-16  459718      2578 ns/op     248 B/op      10 allocs/op

Documentation

Overview

Example (UsingDefaultLogger)

package main

import (
	"os"

	"github.com/gregoryv/bit"
)

// remove studdering, bit.Log(bit.INFO, ...), with local levels
const (
	TRACE = bit.TRACE
	DEBUG = bit.DEBUG
	INFO  = bit.INFO
	ERROR = bit.ERROR
)

func main() {
	// configure
	bit.DefaultLogger.SetOutput(os.Stdout)
	bit.DefaultLogger.SetFlags(bit.LEVEL | bit.TIME | bit.DEBUG)

	// use
	bit.Log(INFO, "first")
	bit.Log(DEBUG, "second",
		"color", "red",
		"ok", true,
	)
	bit.Logf(ERROR, "%q", "third")

	// reconfigure showing parent directory and file
	bit.DefaultLogger.SetFlags(bit.LEVEL | bit.DIR | bit.FILE | bit.INFO)
	A()

	// format as text fields
	bit.DefaultLogger.SetFlags(
		bit.LEVEL | bit.FILE | bit.INFO | bit.FORMAT_TEXT_FIELDS,
	)
	bit.Log(INFO, "something", "year", 2023)

	// TRACE is always shown regardless of level, good for development
	bit.Log(TRACE, "wip...")
}

func A() {
	// first three bits are reserved for calldepth, ie. 1..8 levels
	bit.Log(INFO|1, "called by example")
}

Output:

15:04:05 INFO first
15:04:05 DEBUG second color=red ok=true
15:04:05 ERROR "third"
INFO bit/example_test.go:32 called by example
level="INFO" file="example_test.go:38" msg="something" year=2023
level="TRACE" file="example_test.go:41" msg="wip..."

Index

• Constants
• Variables
• func Log(bits Bit, msg string, fields ...any)
• func Logf(bits Bit, format string, args ...any)
• type Bit
• type Logger
  • func NewLogger() *Logger
  • func (l *Logger) Flags() Bit
  • func (l *Logger) Log(bits Bit, msg string, fields ...any)
  • func (l *Logger) Logf(bits Bit, format string, args ...any)
  • func (l *Logger) SetFlags(bits Bit)
  • func (l *Logger) SetOutput(v io.Writer)
  • func (l *Logger) SetPrefix(v string)
  • func (l *Logger) Sub(prefix string) *Logger

Examples

• Package (UsingDefaultLogger)
• Log
• Log (AsTextField)
• Log (Dir)
• Log (FieldArguments)
• Log (UsingPrefix)
• Log (UsingPrefixFields)
• Logf
• Logger.Sub

Constants

const STAMP = DATE | TIME | MILLISEC

Variables

var (
	KeyStamp   = "time"
	KeyLevel   = "level"
	KeyFile    = "file"
	KeyPrefix  = "prefix"
	KeyMessage = "msg"
)

var DefaultLogger = NewLogger()

Functions

func Log

func Log(bits Bit, msg string, fields ...any)

Log uses DefaultLogger.Log

Example

DefaultLogger.SetOutput(os.Stdout)
Log(DEBUG, "debug package") // should not show
Log(INFO, "package")

Output:

2006-01-02 15:04:05.123 package

Example (AsTextField)

DefaultLogger.SetOutput(os.Stdout)
DefaultLogger.SetFlags(LEVEL | INFO | STAMP | FORMAT_TEXT_FIELDS)
Log(INFO, "package",
	"num%.2f", 1.12345,
)

Output:

time="2006-01-02 15:04:05.123" level="INFO" msg="package" num=1.12

Example (Dir)

l := NewLogger()
l.SetFlags(ERROR | LEVEL | DIR | FILE)
l.SetOutput(os.Stdout)
l.Log(ALERT, "something")

Output:

ALERT bit/logger_test.go:22 something

Example (FieldArguments)

DefaultLogger.SetOutput(os.Stdout)
DefaultLogger.SetFlags(LEVEL | INFO | STAMP)
type Account struct {
	Name string
	Age  int
}
acc := Account{"John", 4}
Log(INFO, "package",
	"open", true,
	// if key contains a %, it's used as a format for the value
	"account%+v", acc,
)

Output:

2006-01-02 15:04:05.123 INFO package open=true account={Name:John Age:4}

Example (UsingPrefix)

DefaultLogger.SetOutput(os.Stdout)
DefaultLogger.SetFlags(LEVEL | INFO)
DefaultLogger.SetPrefix("candy")
Log(INFO, "hello")

Output:

INFO candy hello

Example (UsingPrefixFields)

DefaultLogger.SetOutput(os.Stdout)
DefaultLogger.SetFlags(LEVEL | INFO | FORMAT_TEXT_FIELDS)
DefaultLogger.SetPrefix("candy")
Log(INFO, "hello")

Output:

level="INFO" prefix="candy" msg="hello"

func Logf

func Logf(bits Bit, format string, args ...any)

Logf uses DefaultLogger.Logf

Example

DefaultLogger.SetOutput(os.Stdout)
Logf(DEBUG, "%s", "debug package")
Logf(INFO, "%s", "package")

Output:

2006-01-02 15:04:05.123 package

Types

type Bit

type Bit int

const (
	// Three first bits are used for the calldepth.
	Calldepth_   Bit = 1 << iota // calldepth
	Calldepth__                  // calldepth
	Calldepth___                 // calldepth

	// What information to include.
	// timestamp related
	DATE
	TIME
	MILLISEC

	LEVEL // include level text in capital letters

	FILE // include file and line number
	PATH // include full path to file
	DIR  // include parent directory of file only

	// Format
	FORMAT_TEXT_FIELDS // output format text fields

	// levels
	TRACE     // development print tracing.
	DEBUG     // messages helpful for debugging.
	INFO      // informational messages.
	NOTICE    // normal but significant conditions.
	WARN      // warning conditions.
	ERROR     // error conditions.
	CRITICAL  // critical conditions.
	ALERT     // immediate action required.
	EMERGENCY // system is unusable.
)

type Logger

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

func NewLogger

func NewLogger() *Logger

NewLogger returns a logger that outputs to os.Stderr using level INFO and including a timestamp.

func (*Logger) Flags

func (l *Logger) Flags() Bit

Flags returns current flags.

func (*Logger) Log

func (l *Logger) Log(bits Bit, msg string, fields ...any)

Log outputs the given message and fields using bit levels, e.g. INFO or DEBUG|2 for calldepth 2.

func (*Logger) Logf

func (l *Logger) Logf(bits Bit, format string, args ...any)

Logf formats the given message using bit flags, e.g. INFO or DEBUG|2 for calldepth 2.

func (*Logger) SetFlags

func (l *Logger) SetFlags(bits Bit)

SetFlags overrides current flags.

func (*Logger) SetOutput

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

SetOutput sets the destination writer for this logger.

func (*Logger) SetPrefix

func (l *Logger) SetPrefix(v string)

SetPrefix sets the prefix to include, empty to skip.

func (*Logger) Sub

func (l *Logger) Sub(prefix string) *Logger

Sub creates a sub logger with a new prefix. Changing parent settings, after sub logger createion, are not reflected in sub loggers. Sub loggers use the parent writer unless an explicit one has been set.

Example

DefaultLogger.SetOutput(os.Stdout)
DefaultLogger.SetFlags(LEVEL | INFO)
s := DefaultLogger.Sub("car")
s.Log(INFO, "brm brm")

Output:

INFO car brm brm