log

README

phuslog - Fastest structured logging

Features

• Dependency Free
• Clean API
• Comprehensive Writers
  • IOWriter, io.Writer wrapper
  • ConsoleWriter, colorful & formatting
  • FileWriter, rotating & effective
  • AsyncWriter, asynchronously & performant
  • MultiLevelWriter, multiple level dispatch
  • SyslogWriter, memory efficient syslog
  • JournalWriter, linux journal logging
  • EventlogWriter, windows eventlog logging
• Stdlib Interoperability
  • Logger.Std, transform to std log instances
  • Logger.Slog, transform to slog instances
  • SlogNewJSONHandler, drop-in replacement of slog.NewJSONHandler
• Utility Functions
  • Goid(), the goroutine id matches stack trace
  • NewXID(), create a tracing id
  • Fastrandn(n uint32), fast pseudorandom uint32 in [0,n)
  • IsTerminal(fd uintptr), isatty for golang
  • Printf(fmt string, a ...any), printf logging
• Extreme Performance
  • Significantly faster than all other json loggers.

Interfaces

Logger

// Logger represents an active logging object that generates lines of JSON output to an io.Writer.
type Logger struct {
	// Level defines log levels.
	Level Level

	// Caller determines if adds the file:line of the "caller" key.
	// If Caller is negative, adds the full /path/to/file:line of the "caller" key.
	Caller int

	// TimeField defines the time field name in output.  It uses "time" in if empty.
	TimeField string

	// TimeFormat specifies the time format in output. Uses RFC3339 with millisecond if empty.
	// Strongly recommended to leave TimeFormat empty for optimal built-in log formatting performance.
	// If set to `TimeFormatUnix/TimeFormatUnixMs`, timestamps will be formatted.
	TimeFormat string

	// TimeLocation specifices that the location of TimeFormat used. Uses time.Local if empty.
	TimeLocation *time.Location

	// Writer specifies the writer of output. It uses a wrapped os.Stderr Writer in if empty.
	Writer log.Writer
}

// DefaultLogger is the global logger.
var DefaultLogger = Logger{
	Level:      DebugLevel,
	Caller:     0,
	TimeField:  "",
	TimeFormat: "",
	Writer:     &log.IOWriter{os.Stderr},
}

ConsoleWriter

// ConsoleWriter parses the JSON input and writes it in a colorized, human-friendly format to Writer.
// IMPORTANT: Don't use ConsoleWriter on critical path of a high concurrency and low latency application.
//
// Default output format:
//     {Time} {Level} {Goid} {Caller} > {Message} {Key}={Value} {Key}={Value}
type ConsoleWriter struct {
	// ColorOutput determines if used colorized output.
	ColorOutput bool

	// QuoteString determines if quoting string values.
	QuoteString bool

	// EndWithMessage determines if output message in the end of line.
	EndWithMessage bool

	// Writer is the output destination. using os.Stderr if empty.
	Writer io.Writer

	// Formatter specifies an optional text formatter for creating a customized output,
	// If it is set, ColorOutput, QuoteString and EndWithMessage will be ignored.
	Formatter func(w io.Writer, args *FormatterArgs) (n int, err error)
}

// FormatterArgs is a parsed sturct from json input
type FormatterArgs struct {
	Time      string // "2019-07-10T05:35:54.277Z"
	Message   string // "a structure message"
	Level     string // "info"
	Caller    string // "main.go:123"
	Goid      string // "1"
	Stack     string // "<stack string>"
	KeyValues []struct {
		Key       string // "foo"
		Value     string // "bar"
	}
}

FileWriter

// FileWriter is an Writer that writes to the specified filename.
type FileWriter struct {
	// Filename is the file to write logs to.  Backup log files will be retained
	// in the same directory.
	Filename string

	// FileMode represents the file's mode and permission bits.  The default
	// mode is 0644
	FileMode os.FileMode

	// MaxSize is the maximum size in bytes of the log file before it gets rotated.
	MaxSize int64

	// MaxBackups is the maximum number of old log files to retain.  The default
	// is to retain all old log files
	MaxBackups int

	// TimeFormat specifies the time format of filename, uses `2006-01-02T15-04-05` as default format.
	// If set with `TimeFormatUnix`, `TimeFormatUnixMs`, times are formated as UNIX timestamp.
	TimeFormat string

	// LocalTime determines if the time used for formatting the timestamps in
	// log files is the computer's local time.  The default is to use UTC time.
	LocalTime bool

	// HostName determines if the hostname used for formatting in log files.
	HostName bool

	// ProcessID determines if the pid used for formatting in log files.
	ProcessID bool

	// EnsureFolder ensures the file directory creation before writing.
	EnsureFolder bool

	// Header specifies an optional header function of log file after rotation,
	Header func(fileinfo os.FileInfo) []byte

	// Cleaner specifies an optional cleanup function of log backups after rotation,
	// if not set, the default behavior is to delete more than MaxBackups log files.
	Cleaner func(filename string, maxBackups int, matches []os.FileInfo)
}

Highlights:

• FileWriter uses a symlink to point to the current log file with a timestamp, instead of renaming for rotation. On Windows, this may require administrator privileges.
• FileWriter .Rotate() method does not rotate logs based on broad TimeFormat values (e.g., daily or monthly) until the file reaches its MaxSize.
• FileWriter combined with AsyncWriter can maximize performance and throughput on Linux, see AsyncWriter section.

Getting Started

Simple Logging Example

An out of box example.

package main

import (
	"github.com/phuslu/log"
)

func main() {
	log.Info().Str("foo", "bar").Int("number", 42).Msg("hi, phuslog")
	log.Info().Msgf("foo=%s number=%d error=%+v", "bar", 42, "an error")
}

// Output:
//   {"time":"2020-03-22T09:58:41.828Z","level":"info","foo":"bar","number":42,"message":"hi, phuslog"}
//   {"time":"2020-03-22T09:58:41.828Z","level":"info","message":"foo=bar number=42 error=an error"}

Note: By default log writes to os.Stderr

Customize the logger fields:

To customize logger filed name and format.

package main

import (
	"github.com/phuslu/log"
)

func main() {
	log.DefaultLogger = log.Logger{
		Level:      log.InfoLevel,
		Caller:     1,
		TimeField:  "date",
		TimeFormat: "2006-01-02",
		Writer:     &log.IOWriter{os.Stdout},
	}

	log.Info().Str("foo", "bar").Msgf("hello %s", "world")

	logger := log.Logger{
		Level:      log.InfoLevel,
		TimeField:  "ts",
		TimeFormat: log.TimeFormatUnixMs,
	}

	logger.Log().Str("foo", "bar").Msg("")
}

// Output:
//    {"date":"2019-07-04","level":"info","caller":"prog.go:16","foo":"bar","message":"hello world"}
//    {"ts":1257894000000,"foo":"bar"}

Customize the log writer

To allow the use of ordinary functions as log writers, use WriterFunc.

logger := log.Logger{
	Writer: log.WriterFunc(func(e *log.Entry) (int, error) {
		if e.Level >= log.ErrorLevel {
			return os.Stderr.Write(e.Value())
		} else {
			return os.Stdout.Write(e.Value())
		}
	}),
}

logger.Info().Msg("a stdout entry")
logger.Error().Msg("a stderr entry")

Pretty Console Writer

To log a human-friendly, colorized output, use ConsoleWriter.

if log.IsTerminal(os.Stderr.Fd()) {
	log.DefaultLogger = log.Logger{
		TimeFormat: "15:04:05",
		Caller:     1,
		Writer: &log.ConsoleWriter{
			ColorOutput:    true,
			QuoteString:    true,
			EndWithMessage: true,
		},
	}
}

log.Debug().Int("everything", 42).Str("foo", "bar").Msg("hello world")
log.Info().Int("everything", 42).Str("foo", "bar").Msg("hello world")
log.Warn().Int("everything", 42).Str("foo", "bar").Msg("hello world")
log.Error().Err(errors.New("an error")).Msg("hello world")

Note: pretty logging also works on windows console

Formatting Console Writer

To log with user-defined format(e.g. glog), using ConsoleWriter.Formatter.

package main

import (
	"fmt"
	"io"

	"github.com/phuslu/log"
)

type Glog struct {
	Logger log.Logger
}

func (l *Glog) Infof(fmt string, a ...any) { l.Logger.Info().Msgf(fmt, a...) }

func (l *Glog) Warnf(fmt string, a ...any) { l.Logger.Warn().Msgf(fmt, a...) }

func (l *Glog) Errorf(fmt string, a ...any) { l.Logger.Error().Msgf(fmt, a...) }

var glog = &Glog{log.Logger{
	Level:      log.InfoLevel,
	Caller:     2,
	TimeFormat: "0102 15:04:05.999999",
	Writer: &log.ConsoleWriter{Formatter: func(w io.Writer, a *log.FormatterArgs) (int, error) {
		return fmt.Fprintf(w, "%c%s %s %s] %s\n%s", a.Level[0]-32, a.Time, a.Goid, a.Caller, a.Message, a.Stack)
	}},
}}

func main() {
	glog.Infof("hello glog %s", "Info")
	glog.Warnf("hello glog %s", "Warn")
	glog.Errorf("hello glog %s", "Error")
}

// Output:
// I0725 09:59:57.503246 19 console_test.go:183] hello glog Info
// W0725 09:59:57.504247 19 console_test.go:184] hello glog Warn
// E0725 09:59:57.504247 19 console_test.go:185] hello glog Error

Formatting Logfmt output

To log with logfmt format, also using ConsoleWriter.Formatter.

package main

import (
	"io"
	"os"

	"github.com/phuslu/log"
)

func main() {
	log.DefaultLogger = log.Logger{
		Level:      log.InfoLevel,
		Caller:     1,
		TimeField:  "ts",
		TimeFormat: log.TimeFormatUnixWithMs,
		Writer: &log.ConsoleWriter{
			Formatter: log.LogfmtFormatter{"ts"}.Formatter,
			Writer:    io.MultiWriter(os.Stdout, os.Stderr),
		},
	}

	log.Info().Str("foo", "bar").Int("no", 42).Msgf("a logfmt %s", "info")
}

// Output:
// ts=1257894000.000 level=info goid=1 caller="prog.go:20" foo="bar" no=42 "a logfmt info"
// ts=1257894000.000 level=info goid=1 caller="prog.go:20" foo="bar" no=42 "a logfmt info"

Rotating File Writer

To log to a daily-rotating file, use FileWriter.

package main

import (
	"os"
	"path/filepath"
	"time"

	"github.com/phuslu/log"
	"github.com/robfig/cron/v3"
)

func main() {
	logger := log.Logger{
		Level: log.ParseLevel("info"),
		Writer: &log.FileWriter{
			Filename:     "logs/main.log",
			FileMode:     0600,
			MaxSize:      100 * 1024 * 1024,
			MaxBackups:   7,
			EnsureFolder: true,
			LocalTime:    true,
		},
	}

	runner := cron.New(cron.WithLocation(time.Local))
	runner.AddFunc("0 0 * * *", func() { logger.Writer.(*log.FileWriter).Rotate() })
	go runner.Run()

	for {
		time.Sleep(time.Second)
		logger.Info().Msg("hello world")
	}
}

Rotating File Writer within a total size

To rotating log file hourly and keep in a total size, use FileWriter.Cleaner.

package main

import (
	"os"
	"path/filepath"
	"time"

	"github.com/phuslu/log"
	"github.com/robfig/cron/v3"
)

func main() {
	logger := log.Logger{
		Level: log.ParseLevel("info"),
		Writer: &log.FileWriter{
			Filename: "main.log",
			MaxSize:  500 * 1024 * 1024,
			Cleaner:  func(filename string, maxBackups int, matches []os.FileInfo) {
				var dir = filepath.Dir(filename)
				var total int64
				for i := len(matches) - 1; i >= 0; i-- {
					total += matches[i].Size()
					if total > 5*1024*1024*1024 {
						os.Remove(filepath.Join(dir, matches[i].Name()))
					}
				}
			},
		},
	}

	runner := cron.New(cron.WithLocation(time.UTC))
	runner.AddFunc("0 * * * *", func() { logger.Writer.(*log.FileWriter).Rotate() })
	go runner.Run()

	for {
		time.Sleep(time.Second)
		logger.Info().Msg("hello world")
	}
}

Rotating File Writer with compression

To rotating log file hourly and compressing after rotation, use FileWriter.Cleaner.

package main

import (
	"os"
	"os/exec"
	"path/filepath"
	"time"

	"github.com/phuslu/log"
	"github.com/robfig/cron/v3"
)

func main() {
	logger := log.Logger{
		Level: log.ParseLevel("info"),
		Writer: &log.FileWriter{
			Filename: "main.log",
			MaxSize:  500 * 1024 * 1024,
			Cleaner:  func(filename string, maxBackups int, matches []os.FileInfo) {
				var dir = filepath.Dir(filename)
				for i, fi := range matches {
					filename := filepath.Join(dir, fi.Name())
					switch {
					case i > maxBackups:
						os.Remove(filename)
					case !strings.HasSuffix(filename, ".gz"):
						go exec.Command("nice", "gzip", filename).Run()
					}
				}
			},
		},
	}

	runner := cron.New(cron.WithLocation(time.UTC))
	runner.AddFunc("0 * * * *", func() { logger.Writer.(*log.FileWriter).Rotate() })
	go runner.Run()

	for {
		time.Sleep(time.Second)
		logger.Info().Msg("hello world")
	}
}

Async File Writer

For maximum write performance with asynchronous file logging, use AsyncWriter.

logger := log.Logger{
	Level: log.InfoLevel,
	Writer: &log.AsyncWriter{
		ChannelSize:   4096,
		Writer:        &log.FileWriter{
			Filename:   "main.log",
			FileMode:   0600,
			MaxSize:    50 * 1024 * 1024,
			MaxBackups: 7,
			LocalTime:  false,
		},
	},
}

logger.Info().Int("number", 42).Str("foo", "bar").Msg("a async info log")
logger.Warn().Int("number", 42).Str("foo", "bar").Msg("a async warn log")
logger.Writer.(io.Closer).Close()

Highlights:

• To flush data and shut down safely, explicitly call the .Close() method.
• The automatic writev enabling can boost write performance by up to 10x under high load.

Random Sample Logger:

To logging only 5% logs, use below idiom.

if log.Fastrandn(100) < 5 {
	log.Log().Msg("hello world")
}

Multiple Dispatching Writer

To log to different writers by different levels, use MultiLevelWriter.

log.DefaultLogger.Writer = &log.MultiLevelWriter{
	InfoWriter:    &log.FileWriter{Filename: "main.INFO", MaxSize: 100<<20},
	WarnWriter:    &log.FileWriter{Filename: "main.WARNING", MaxSize: 100<<20},
	ErrorWriter:   &log.FileWriter{Filename: "main.ERROR", MaxSize: 100<<20},
	ConsoleWriter: &log.ConsoleWriter{ColorOutput: true},
	ConsoleLevel:  log.ErrorLevel,
}

log.Info().Int("number", 42).Str("foo", "bar").Msg("a info log")
log.Warn().Int("number", 42).Str("foo", "bar").Msg("a warn log")
log.Error().Int("number", 42).Str("foo", "bar").Msg("a error log")

Multiple Entry Writer

To log to different writers, use MultiEntryWriter.

log.DefaultLogger.Writer = &log.MultiEntryWriter{
	&log.ConsoleWriter{ColorOutput: true},
	&log.FileWriter{Filename: "main.log", MaxSize: 100<<20},
	&log.EventlogWriter{Source: ".NET Runtime", ID: 1000},
}

log.Info().Int("number", 42).Str("foo", "bar").Msg("a info log")

Multiple IO Writer

To log to multiple io writers like io.MultiWriter, use below idiom.

log.DefaultLogger.Writer = &log.MultiIOWriter{
	os.Stdout,
	&log.FileWriter{Filename: "main.log", MaxSize: 100<<20},
}

log.Info().Int("number", 42).Str("foo", "bar").Msg("a info log")

Multiple Combined Logger:

To logging to different logger as you want, use below idiom.

package main

import (
	"github.com/phuslu/log"
)

var logger = struct {
	Console log.Logger
	Access  log.Logger
	Data    log.Logger
}{
	Console: log.Logger{
		TimeFormat: "15:04:05",
		Caller:     1,
		Writer: &log.ConsoleWriter{
			ColorOutput:    true,
			EndWithMessage: true,
		},
	},
	Access: log.Logger{
		Level: log.InfoLevel,
		Writer: &log.FileWriter{
			Filename:   "access.log",
			MaxSize:    50 * 1024 * 1024,
			MaxBackups: 7,
			LocalTime:  false,
		},
	},
	Data: log.Logger{
		Level: log.InfoLevel,
		Writer: &log.FileWriter{
			Filename:   "data.log",
			MaxSize:    50 * 1024 * 1024,
			MaxBackups: 7,
			LocalTime:  false,
		},
	},
}

func main() {
	logger.Console.Info().Msgf("hello world")
	logger.Access.Log().Msgf("handle request")
	logger.Data.Log().Msgf("some data")
}

SyslogWriter

SyslogWriter is a memory-efficient, cross-platform, dependency-free syslog writer, outperforms all other structured logging libraries.

package main

import (
	"net"
	"time"

	"github.com/phuslu/log"
)

func main() {
	go func() {
		ln, _ := net.Listen("tcp", "127.0.0.1:1601")
		for {
			conn, _ := ln.Accept()
			go func(c net.Conn) {
				b := make([]byte, 8192)
				n, _ := conn.Read(b)
				println(string(b[:n]))
			}(conn)
		}
	}()

	syslog := log.Logger{
		Level:      log.InfoLevel,
		TimeField:  "ts",
		TimeFormat: log.TimeFormatUnixMs,
		Writer: &log.SyslogWriter{
			Network: "tcp",            // "unixgram",
			Address: "127.0.0.1:1601", // "/run/systemd/journal/syslog",
			Tag:     "",
			Marker:  "@cee:",
			Dial:    net.Dial,
		},
	}

	syslog.Info().Str("foo", "bar").Int("an", 42).Msg("a syslog info")
	syslog.Warn().Str("foo", "bar").Int("an", 42).Msg("a syslog warn")
	time.Sleep(2)
}

// Output:
// <6>2022-07-24T18:48:15+08:00 127.0.0.1:59277 [11516]: @cee:{"ts":1658659695428,"level":"info","foo":"bar","an":42,"message":"a syslog info"}
// <4>2022-07-24T18:48:15+08:00 127.0.0.1:59277 [11516]: @cee:{"ts":1658659695429,"level":"warn","foo":"bar","an":42,"message":"a syslog warn"}

JournalWriter

To log to linux systemd journald, using JournalWriter.

log.DefaultLogger.Writer = &log.JournalWriter{
	JournalSocket: "/run/systemd/journal/socket",
}

log.Info().Int("number", 42).Str("foo", "bar").Msg("hello world")

EventlogWriter

To log to windows system event, using EventlogWriter.

log.DefaultLogger.Writer = &log.EventlogWriter{
	Source: ".NET Runtime",
	ID:     1000,
}

log.Info().Int("number", 42).Str("foo", "bar").Msg("hello world")

Stdlib Log Adapter

Using wrapped loggers for stdlog.

package main

import (
	stdlog "log"
	"os"

	"github.com/phuslu/log"
)

func main() {
	var logger *stdlog.Logger = (&log.Logger{
		Level:      log.InfoLevel,
		TimeField:  "date",
		TimeFormat: "2006-01-02",
		Caller:     1,
		Context:    log.NewContext(nil).Str("logger", "mystdlog").Int("myid", 42).Value(),
		Writer:     &log.IOWriter{os.Stdout},
	}).Std("", 0)

	logger.Print("hello from stdlog Print")
	logger.Println("hello from stdlog Println")
	logger.Printf("hello from stdlog %s", "Printf")
}

slog Adapter

Using wrapped loggers for slog.

package main

import (
	"log/slog"

	"github.com/phuslu/log"
)

func main() {
	var logger *slog.Logger = (&log.Logger{
		Level:      log.InfoLevel,
		TimeField:  "date",
		TimeFormat: "2006-01-02",
		Caller:     1,
	}).Slog()

	logger = logger.With("logger", "a_test_slog").With("everything", 42)

	logger.Info("hello from slog Info")
	logger.Warn("hello from slog Warn")
	logger.Error("hello from slog Error")
}

slog.JSONHandler replacement

Using as a high performance version of slog.JSONHandler.

package main

import (
	"log/slog"
	"os"

	phuslog "github.com/phuslu/log"
)

func main() {
	slog.SetDefault(slog.New(phuslog.SlogNewJSONHandler(os.Stderr, &slog.HandlerOptions{AddSource: true})))

	slog.Info("hello from phuslog", "a", 1, "b", 2)
}

User-defined Data Structure

To log with user-defined struct effectively, implements MarshalObject.

package main

import (
	"github.com/phuslu/log"
)

type User struct {
	ID   int
	Name string
	Pass string
}

func (u *User) MarshalObject(e *log.Entry) {
	e.Int("id", u.ID).Str("name", u.Name).Str("password", "***")
}

func main() {
	log.Info().Object("user", &User{1, "neo", "123456"}).Msg("")
	log.Info().EmbedObject(&User{2, "john", "abc"}).Msg("")
}

// Output:
//   {"time":"2020-07-12T05:03:43.949Z","level":"info","user":{"id":1,"name":"neo","password":"***"}}
//   {"time":"2020-07-12T05:03:43.949Z","level":"info","id":2,"name":"john","password":"***"}

Contextual Fields

To add preserved key:value pairs to each entry, use NewContext.

logger := log.Logger{
	Level:   log.InfoLevel,
	Context: log.NewContext(nil).Str("ctx", "some_ctx").Value(),
}

logger.Debug().Int("no0", 0).Msg("zero")
logger.Info().Int("no1", 1).Msg("first")
logger.Info().Int("no2", 2).Msg("second")

// Output:
//   {"time":"2020-07-12T05:03:43.949Z","level":"info","ctx":"some_ctx","no1":1,"message":"first"}
//   {"time":"2020-07-12T05:03:43.949Z","level":"info","ctx":"some_ctx","no2":2,"message":"second"}

You can make a copy of log and add contextual fields.

package main

import (
	"github.com/phuslu/log"
)

func main() {
	sublogger := log.DefaultLogger
	sublogger.Level = log.InfoLevel
	sublogger.Context = log.NewContext(nil).Str("ctx", "some_ctx").Value()

	sublogger.Debug().Int("no0", 0).Msg("zero")
	sublogger.Info().Int("no1", 1).Msg("first")
	sublogger.Info().Int("no2", 2).Msg("second")
	log.Debug().Int("no3", 3).Msg("no context")
}

// Output:
//   {"time":"2021-06-14T06:36:42.904+02:00","level":"info","ctx":"some_ctx","no1":1,"message":"first"}
//   {"time":"2021-06-14T06:36:42.905+02:00","level":"info","ctx":"some_ctx","no2":2,"message":"second"}
//   {"time":"2021-06-14T06:36:42.906+02:00","level":"debug","no3":3,"message":"no context"}

Third-party Logger Interceptor

Logger	Interceptor
logr	https://github.com/phuslu/log-contrib/tree/master/logr
gin	https://github.com/phuslu/log-contrib/tree/master/gin
fiber	https://github.com/phuslu/log-contrib/tree/master/fiber
gorm	https://github.com/phuslu/log-contrib/tree/master/gorm
grpc	https://github.com/phuslu/log-contrib/tree/master/grpc
grpcgateway	https://github.com/phuslu/log-contrib/tree/master/grpcgateway

High Performance

The most common benchmarks(disabled/simple/caller/printf/any) against slog/zap/zerolog

// go test -v -cpu=4 -run=none -bench=. -benchtime=10s -benchmem bench_test.go
package main

import (
	"io"
	"log"
	"log/slog"
	"testing"

	phuslog "github.com/phuslu/log"
	"github.com/rs/zerolog"
	"go.uber.org/zap"
	"go.uber.org/zap/zapcore"
)

const msg = "The quick brown fox jumps over the lazy dog"
var obj = struct {Rate string; Low int; High float32}{"15", 16, 123.2}

func BenchmarkSlogDisabled(b *testing.B) {
	logger := slog.New(slog.NewJSONHandler(io.Discard, nil))
	for i := 0; i < b.N; i++ {
		logger.Debug(msg, "rate", "15", "low", 16, "high", 123.2)
	}
}

func BenchmarkSlogSimple(b *testing.B) {
	logger := slog.New(slog.NewJSONHandler(io.Discard, nil))
	for i := 0; i < b.N; i++ {
		logger.Info(msg, "rate", "15", "low", 16, "high", 123.2)
	}
}

func BenchmarkSlogPrintf(b *testing.B) {
	slog.SetDefault(slog.New(slog.NewJSONHandler(io.Discard, nil)))
	for i := 0; i < b.N; i++ {
		log.Printf("rate=%s low=%d high=%f msg=%s", "15", 16, 123.2, msg)
	}
}

func BenchmarkSlogCaller(b *testing.B) {
	logger := slog.New(slog.NewJSONHandler(io.Discard, &slog.HandlerOptions{AddSource: true}))
	for i := 0; i < b.N; i++ {
		logger.Info(msg, "rate", "15", "low", 16, "high", 123.2)
	}
}

func BenchmarkSlogAny(b *testing.B) {
	logger := slog.New(slog.NewJSONHandler(io.Discard, nil))
	for i := 0; i < b.N; i++ {
		logger.Info(msg, "rate", "15", "low", 16, "object", &obj)
	}
}

func BenchmarkSlogPhusDisabled(b *testing.B) {
	logger := slog.New(phuslog.SlogNewJSONHandler(io.Discard, nil))
	for i := 0; i < b.N; i++ {
		logger.Debug(msg, "rate", "15", "low", 16, "high", 123.2)
	}
}

func BenchmarkSlogPhusSimple(b *testing.B) {
	logger := slog.New(phuslog.SlogNewJSONHandler(io.Discard, nil))
	for i := 0; i < b.N; i++ {
		logger.Info(msg, "rate", "15", "low", 16, "high", 123.2)
	}
}

func BenchmarkSlogPhusPrintf(b *testing.B) {
	slog.SetDefault(slog.New(phuslog.SlogNewJSONHandler(io.Discard, nil)))
	for i := 0; i < b.N; i++ {
		log.Printf("rate=%s low=%d high=%f msg=%s", "15", 16, 123.2, msg)
	}
}

func BenchmarkSlogPhusCaller(b *testing.B) {
	logger := slog.New(phuslog.SlogNewJSONHandler(io.Discard, &slog.HandlerOptions{AddSource: true}))
	for i := 0; i < b.N; i++ {
		logger.Info(msg, "rate", "15", "low", 16, "high", 123.2)
	}
}

func BenchmarkSlogPhusAny(b *testing.B) {
	logger := slog.New(phuslog.SlogNewJSONHandler(io.Discard, nil))
	for i := 0; i < b.N; i++ {
		logger.Info(msg, "rate", "15", "low", 16, "object", &obj)
	}
}

func BenchmarkZapDisabled(b *testing.B) {
	logger := zap.New(zapcore.NewCore(
		zapcore.NewJSONEncoder(zap.NewProductionEncoderConfig()),
		zapcore.AddSync(io.Discard),
		zapcore.InfoLevel,
	)).Sugar()
	for i := 0; i < b.N; i++ {
		logger.Debugw(msg, "rate", "15", "low", 16, "high", 123.2)
	}
}

func BenchmarkZapSimple(b *testing.B) {
	logger := zap.New(zapcore.NewCore(
		zapcore.NewJSONEncoder(zap.NewProductionEncoderConfig()),
		zapcore.AddSync(io.Discard),
		zapcore.InfoLevel,
	)).Sugar()
	for i := 0; i < b.N; i++ {
		logger.Infow(msg, "rate", "15", "low", 16, "high", 123.2)
	}
}

func BenchmarkZapPrintf(b *testing.B) {
	logger := zap.New(zapcore.NewCore(
		zapcore.NewJSONEncoder(zap.NewProductionEncoderConfig()),
		zapcore.AddSync(io.Discard),
		zapcore.InfoLevel,
	)).Sugar()
	for i := 0; i < b.N; i++ {
		logger.Infof("rate=%s low=%d high=%f msg=%s", "15", 16, 123.2, msg)
	}
}

func BenchmarkZapCaller(b *testing.B) {
	logger := zap.New(zapcore.NewCore(
		zapcore.NewJSONEncoder(zap.NewProductionEncoderConfig()),
		zapcore.AddSync(io.Discard),
		zapcore.InfoLevel),
		zap.AddCaller(),
	).Sugar()
	for i := 0; i < b.N; i++ {
		logger.Infow(msg, "rate", "15", "low", 16, "high", 123.2)
	}
}

func BenchmarkZapAny(b *testing.B) {
	logger := zap.New(zapcore.NewCore(
		zapcore.NewJSONEncoder(zap.NewProductionEncoderConfig()),
		zapcore.AddSync(io.Discard),
		zapcore.InfoLevel,
	)).Sugar()
	for i := 0; i < b.N; i++ {
		logger.Infow(msg, "rate", "15", "low", 16, "object", &obj)
	}
}

func BenchmarkZeroLogDisabled(b *testing.B) {
	zerolog.SetGlobalLevel(zerolog.InfoLevel)
	logger := zerolog.New(io.Discard).With().Timestamp().Logger()
	for i := 0; i < b.N; i++ {
		logger.Debug().Str("rate", "15").Int("low", 16).Float32("high", 123.2).Msg(msg)
	}
}

func BenchmarkZeroLogSimple(b *testing.B) {
	logger := zerolog.New(io.Discard).With().Timestamp().Logger()
	for i := 0; i < b.N; i++ {
		logger.Info().Str("rate", "15").Int("low", 16).Float32("high", 123.2).Msg(msg)
	}
}

func BenchmarkZeroLogPrintf(b *testing.B) {
	logger := zerolog.New(io.Discard).With().Timestamp().Logger()
	for i := 0; i < b.N; i++ {
		logger.Info().Msgf("rate=%s low=%d high=%f msg=%s", "15", 16, 123.2, msg)
	}
}

func BenchmarkZeroLogCaller(b *testing.B) {
	logger := zerolog.New(io.Discard).With().Caller().Timestamp().Logger()
	for i := 0; i < b.N; i++ {
		logger.Info().Str("rate", "15").Int("low", 16).Float32("high", 123.2).Msg(msg)
	}
}

func BenchmarkZeroLogAny(b *testing.B) {
	logger := zerolog.New(io.Discard).With().Timestamp().Logger()
	for i := 0; i < b.N; i++ {
		logger.Info().Any("rate", "15").Any("low", 16).Any("object", &obj).Msg(msg)
	}
}

func BenchmarkPhusLogDisabled(b *testing.B) {
	logger := phuslog.Logger{Level: phuslog.InfoLevel, Writer: phuslog.IOWriter{io.Discard}}
	for i := 0; i < b.N; i++ {
		logger.Debug().Str("rate", "15").Int("low", 16).Float32("high", 123.2).Msg(msg)
	}
}

func BenchmarkPhusLogSimple(b *testing.B) {
	logger := phuslog.Logger{Writer: phuslog.IOWriter{io.Discard}}
	for i := 0; i < b.N; i++ {
		logger.Info().Str("rate", "15").Int("low", 16).Float32("high", 123.2).Msg(msg)
	}
}

func BenchmarkPhusLogPrintf(b *testing.B) {
	logger := phuslog.Logger{Writer: phuslog.IOWriter{io.Discard}}
	for i := 0; i < b.N; i++ {
		logger.Info().Msgf("rate=%s low=%d high=%f msg=%s", "15", 16, 123.2, msg)
	}
}

func BenchmarkPhusLogCaller(b *testing.B) {
	logger := phuslog.Logger{Caller: 1, Writer: phuslog.IOWriter{io.Discard}}
	for i := 0; i < b.N; i++ {
		logger.Info().Str("rate", "15").Int("low", 16).Float32("high", 123.2).Msg(msg)
	}
}

func BenchmarkPhusLogAny(b *testing.B) {
	logger := phuslog.Logger{Writer: phuslog.IOWriter{io.Discard}}
	for i := 0; i < b.N; i++ {
		logger.Info().Any("rate", "15").Any("low", 16).Any("object", &obj).Msg(msg)
	}
}

A Performance result as below, for daily benchmark results see github actions

goos: linux
goarch: amd64
cpu: AMD EPYC 7763 64-Core Processor

BenchmarkSlogDisabled-4      	715096197	         8.452 ns/op	       0 B/op	       0 allocs/op
BenchmarkSlogSimple-4        	 4394904	      1367 ns/op	     120 B/op	       3 allocs/op
BenchmarkSlogPrintf-4        	 5546492	      1053 ns/op	      80 B/op	       1 allocs/op
BenchmarkSlogCaller-4        	 2708773	      2203 ns/op	     688 B/op	       9 allocs/op
BenchmarkSlogAny-4           	 3936673	      1516 ns/op	     112 B/op	       2 allocs/op

BenchmarkZapDisabled-4       	662012907	         9.076 ns/op	       0 B/op	       0 allocs/op
BenchmarkZapSimple-4         	 6586341	       926.9 ns/op	     384 B/op	       1 allocs/op
BenchmarkZapPrintf-4         	 6375831	       951.9 ns/op	      80 B/op	       1 allocs/op
BenchmarkZapCaller-4         	 3601339	      1673 ns/op	     632 B/op	       3 allocs/op
BenchmarkZapAny-4            	 4649176	      1288 ns/op	     480 B/op	       2 allocs/op

BenchmarkZeroLogDisabled-4   	606002878	         9.908 ns/op	       0 B/op	       0 allocs/op
BenchmarkZeroLogSimple-4     	18342879	       328.7 ns/op	       0 B/op	       0 allocs/op
BenchmarkZeroLogPrintf-4     	 8904566	       669.6 ns/op	      80 B/op	       1 allocs/op
BenchmarkZeroLogCaller-4     	 4687348	      1280 ns/op	     304 B/op	       4 allocs/op
BenchmarkZeroLogAny-4        	 7031146	       851.2 ns/op	      64 B/op	       3 allocs/op

BenchmarkPhusLogDisabled-4   	624706401	         9.599 ns/op	       0 B/op	       0 allocs/op
BenchmarkPhusLogSimple-4     	22249552	       243.1 ns/op	       0 B/op	       0 allocs/op
BenchmarkPhusLogPrintf-4     	11471342	       524.8 ns/op	       0 B/op	       0 allocs/op
BenchmarkPhusLogCaller-4     	12550828	       480.9 ns/op	       0 B/op	       0 allocs/op
BenchmarkPhusLogAny-4        	11623692	       516.4 ns/op	       0 B/op	       0 allocs/op

PASS
ok  	bench	139.331s

As slog handlers, comparing with stdlib/zap/zerolog implementations

// go test -v -cpu=1 -run=none -bench=. -benchtime=10s -benchmem bench_test.go
package bench

import (
	"io"
	"log/slog"
	"testing"

	"github.com/phsym/zeroslog"
	phuslog "github.com/phuslu/log"
	seankhliao "go.seankhliao.com/svcrunner/v3/jsonlog"
	"go.uber.org/zap"
	"go.uber.org/zap/exp/zapslog"
	"go.uber.org/zap/zapcore"
)

const msg = "The quick brown fox jumps over the lazy dog"

func BenchmarkSlogSimpleStd(b *testing.B) {
	logger := slog.New(slog.NewJSONHandler(io.Discard, nil))
	for i := 0; i < b.N; i++ {
		logger.Info(msg, "rate", "15", "low", 16, "high", 123.2)
	}
}

func BenchmarkSlogGroupsStd(b *testing.B) {
	logger := slog.New(slog.NewJSONHandler(io.Discard, nil)).With("a", 1).WithGroup("g").With("b", 2)
	for i := 0; i < b.N; i++ {
		logger.Info(msg, "rate", "15", "low", 16, "high", 123.2)
	}
}

func BenchmarkSlogSimpleZap(b *testing.B) {
	logcore := zapcore.NewCore(
		zapcore.NewJSONEncoder(zap.NewProductionEncoderConfig()),
		zapcore.AddSync(io.Discard),
		zapcore.InfoLevel,
	)
	logger := slog.New(zapslog.NewHandler(logcore, nil))
	for i := 0; i < b.N; i++ {
		logger.Info(msg, "rate", "15", "low", 16, "high", 123.2)
	}
}

func BenchmarkSlogGroupsZap(b *testing.B) {
	logcore := zapcore.NewCore(
		zapcore.NewJSONEncoder(zap.NewProductionEncoderConfig()),
		zapcore.AddSync(io.Discard),
		zapcore.InfoLevel,
	)
	logger := slog.New(zapslog.NewHandler(logcore, nil)).With("a", 1).WithGroup("g").With("b", 2)
	for i := 0; i < b.N; i++ {
		logger.Info(msg, "rate", "15", "low", 16, "high", 123.2)
	}
}

func BenchmarkSlogSimpleZerolog(b *testing.B) {
	logger := slog.New(zeroslog.NewJsonHandler(io.Discard, &zeroslog.HandlerOptions{Level: slog.LevelInfo}))
	for i := 0; i < b.N; i++ {
		logger.Info(msg, "rate", "15", "low", 16, "high", 123.2)
	}
}

func BenchmarkSlogGroupsZerolog(b *testing.B) {
	logger := slog.New(zeroslog.NewJsonHandler(io.Discard, &zeroslog.HandlerOptions{Level: slog.LevelInfo})).With("a", 1).WithGroup("g").With("b", 2)
	for i := 0; i < b.N; i++ {
		logger.Info(msg, "rate", "15", "low", 16, "high", 123.2)
	}
}

func BenchmarkSlogSimpleSeankhliao(b *testing.B) {
	logger := slog.New(seankhliao.New(slog.LevelInfo, io.Discard))
	for i := 0; i < b.N; i++ {
		logger.Info(msg, "rate", "15", "low", 16, "high", 123.2)
	}
}

func BenchmarkSlogGroupsSeankhliao(b *testing.B) {
	logger := slog.New(seankhliao.New(slog.LevelInfo, io.Discard)).With("a", 1).WithGroup("g").With("b", 2)
	for i := 0; i < b.N; i++ {
		logger.Info(msg, "rate", "15", "low", 16, "high", 123.2)
	}
}

func BenchmarkSlogSimplePhuslog(b *testing.B) {
	logger := slog.New((&phuslog.Logger{Writer: phuslog.IOWriter{io.Discard}}).Slog().Handler())
	for i := 0; i < b.N; i++ {
		logger.Info(msg, "rate", "15", "low", 16, "high", 123.2)
	}
}

func BenchmarkSlogGroupsPhuslog(b *testing.B) {
	logger := slog.New((&phuslog.Logger{Writer: phuslog.IOWriter{io.Discard}}).Slog().Handler()).With("a", 1).WithGroup("g").With("b", 2)
	for i := 0; i < b.N; i++ {
		logger.Info(msg, "rate", "15", "low", 16, "high", 123.2)
	}
}

func BenchmarkSlogSimplePhuslogStd(b *testing.B) {
	logger := slog.New(phuslog.SlogNewJSONHandler(io.Discard, nil))
	for i := 0; i < b.N; i++ {
		logger.Info(msg, "rate", "15", "low", 16, "high", 123.2)
	}
}

func BenchmarkSlogGroupsPhuslogStd(b *testing.B) {
	logger := slog.New(phuslog.SlogNewJSONHandler(io.Discard, nil)).With("a", 1).WithGroup("g").With("b", 2)
	for i := 0; i < b.N; i++ {
		logger.Info(msg, "rate", "15", "low", 16, "high", 123.2)
	}
}

A Performance result as below, for daily benchmark results see github actions

goos: linux
goarch: amd64
cpu: AMD EPYC 7763 64-Core Processor                

BenchmarkSlogSimpleStd        	 4314817	      1413 ns/op	     120 B/op	       3 allocs/op
BenchmarkSlogGroupsStd        	 4167734	      1462 ns/op	     120 B/op	       3 allocs/op

BenchmarkSlogSimpleZap        	 4824007	      1245 ns/op	     192 B/op	       1 allocs/op
BenchmarkSlogGroupsZap        	 4800220	      1256 ns/op	     192 B/op	       1 allocs/op

BenchmarkSlogSimpleZerolog    	 7713812	       783.7 ns/op	       0 B/op	       0 allocs/op
BenchmarkSlogGroupsZerolog    	 5506782	      1089 ns/op	     288 B/op	       1 allocs/op

BenchmarkSlogSimplePhuslog    	 8858504	       683.0 ns/op	       0 B/op	       0 allocs/op
BenchmarkSlogGroupsPhuslog    	 8615334	       694.0 ns/op	       0 B/op	       0 allocs/op

BenchmarkSlogSimplePhuslogStd 	 8889276	       666.7 ns/op	       0 B/op	       0 allocs/op
BenchmarkSlogGroupsPhuslogStd 	 8849634	       683.3 ns/op	       0 B/op	       0 allocs/op

PASS
ok  	bench	84.415s

As a drop-in replacement for slog.JSONHandler, it provides 50% to 100% speedup and full compatibility.

// go test -v -args -useWarnings && go test -v -run=none -bench=. -args -useWarnings
// a special thanks to @madkins23 for the help, with reference to https://github.com/phuslu/log/pull/70
package bench

import (
	"io"
	"log/slog"
	"testing"

	benchtests "github.com/madkins23/go-slog/bench/tests"
	"github.com/madkins23/go-slog/infra"
	"github.com/madkins23/go-slog/infra/warning"
	verifytests "github.com/madkins23/go-slog/verify/tests"
	"github.com/phuslu/log"
	"github.com/stretchr/testify/suite"
)

func BenchmarkSlogJSON(b *testing.B) {
	slogNewJSONHandler := func(w io.Writer, options *slog.HandlerOptions) slog.Handler {
		return slog.NewJSONHandler(w, options)
	}
	creator := infra.NewCreator("slog/JSONHandler", slogNewJSONHandler, nil,
		`^slog/JSONHandler^ is the JSON handler provided with the ^slog^ library.
		It is fast and as a part of the Go distribution it is used
		along with published documentation as a model for ^slog.Handler^ behavior.`,
		map[string]string{
			"slog/JSONHandler": "https://pkg.go.dev/log/slog#JSONHandler",
		})
	slogSuite := benchtests.NewSlogBenchmarkSuite(creator)
	benchtests.Run(b, slogSuite)
}

func BenchmarkPhusluSlog(b *testing.B) {
	creator := infra.NewCreator("phuslu/slog", log.SlogNewJSONHandler, nil,
		`^phuslu/slog^ is a wrapper around the pre-existing ^phuslu/log^ logging library.`,
		map[string]string{
			"phuslu/log": "https://github.com/phuslu/log",
		})
	slogSuite := benchtests.NewSlogBenchmarkSuite(creator)
	benchtests.Run(b, slogSuite)
}

func TestVerifyPhusluSlog(t *testing.T) {
	creator := infra.NewCreator("phuslu/slog", log.SlogNewJSONHandler, nil,
		`^phuslu/slog^ is a wrapper around the pre-existing ^phuslu/log^ logging library.`,
		map[string]string{
			"phuslu/log": "https://github.com/phuslu/log",
		})
	slogSuite := verifytests.NewSlogTestSuite(creator)
	slogSuite.WarnOnly(warning.Duplicates)
	suite.Run(t, slogSuite)
}

func TestMain(m *testing.M) {
	warning.WithWarnings(m)
}

A Performance result as below, for daily go-slog results see github actions

goos: linux
goarch: amd64
cpu: AMD EPYC 7763 64-Core Processor                

BenchmarkSlogJSON/BenchmarkAttributes-4         	  870120	      1441 ns/op	 290.15 MB/s	     472 B/op	       6 allocs/op
BenchmarkSlogJSON/BenchmarkBigGroup-4           	   10000	    102796 ns/op	 225.45 MB/s	  112990 B/op	      14 allocs/op
BenchmarkSlogJSON/BenchmarkDisabled-4           	309658138	         3.876 ns/op	       0 B/op	       0 allocs/op
BenchmarkSlogJSON/BenchmarkKeyValues-4          	  793542	      1509 ns/op	 277.01 MB/s	     472 B/op	       6 allocs/op
BenchmarkSlogJSON/BenchmarkLogging-4            	   42348	     27256 ns/op	 322.61 MB/s	       0 B/op	       0 allocs/op
BenchmarkSlogJSON/BenchmarkSimple-4             	 4208820	       286.2 ns/op	 289.98 MB/s	       0 B/op	       0 allocs/op
BenchmarkSlogJSON/BenchmarkSimpleSource-4       	 1388956	       867.6 ns/op	 359.61 MB/s	     568 B/op	       6 allocs/op
BenchmarkSlogJSON/BenchmarkWithAttrsAttributes-4         	  789448	      1468 ns/op	 534.76 MB/s	     472 B/op	       6 allocs/op
BenchmarkSlogJSON/BenchmarkWithAttrsKeyValues-4          	  746674	      1603 ns/op	 489.56 MB/s	     472 B/op	       6 allocs/op
BenchmarkSlogJSON/BenchmarkWithAttrsSimple-4             	 3369094	       315.5 ns/op	1426.53 MB/s	       0 B/op	       0 allocs/op
BenchmarkSlogJSON/BenchmarkWithGroupAttributes-4         	  653076	      1536 ns/op	 281.32 MB/s	     472 B/op	       6 allocs/op
BenchmarkSlogJSON/BenchmarkWithGroupKeyValues-4          	  806590	      1529 ns/op	 282.48 MB/s	     472 B/op	       6 allocs/op

BenchmarkPhusluSlog/BenchmarkAttributes-4                	 1358455	       901.1 ns/op	 480.53 MB/s	     240 B/op	       1 allocs/op
BenchmarkPhusluSlog/BenchmarkBigGroup-4                  	   50872	     23419 ns/op	 989.60 MB/s	      48 B/op	       1 allocs/op
BenchmarkPhusluSlog/BenchmarkDisabled-4                  	406019344	         2.947 ns/op	       0 B/op	       0 allocs/op
BenchmarkPhusluSlog/BenchmarkKeyValues-4                 	 1292756	       960.2 ns/op	 450.93 MB/s	     240 B/op	       1 allocs/op
BenchmarkPhusluSlog/BenchmarkLogging-4                   	   84048	     14283 ns/op	 616.25 MB/s	       0 B/op	       0 allocs/op
BenchmarkPhusluSlog/BenchmarkSimple-4                    	 7523289	       159.0 ns/op	 521.87 MB/s	       0 B/op	       0 allocs/op
BenchmarkPhusluSlog/BenchmarkSimpleSource-4              	 5962424	       201.8 ns/op	1546.16 MB/s	       0 B/op	       0 allocs/op
BenchmarkPhusluSlog/BenchmarkWithAttrsAttributes-4       	 1300897	       910.9 ns/op	 894.68 MB/s	     240 B/op	       1 allocs/op
BenchmarkPhusluSlog/BenchmarkWithAttrsKeyValues-4        	 1269901	       948.3 ns/op	 859.42 MB/s	     240 B/op	       1 allocs/op
BenchmarkPhusluSlog/BenchmarkWithAttrsSimple-4           	 7303563	       166.9 ns/op	2786.27 MB/s	       0 B/op	       0 allocs/op
BenchmarkPhusluSlog/BenchmarkWithGroupAttributes-4       	 1328126	       896.8 ns/op	 498.45 MB/s	     240 B/op	       1 allocs/op
BenchmarkPhusluSlog/BenchmarkWithGroupKeyValues-4        	 1294560	       951.7 ns/op	 469.70 MB/s	     240 B/op	       1 allocs/op

PASS
ok  	bench	37.548s

In summary, phuslog offers a blend of low latency, minimal memory usage, and efficient logging across various scenarios, making it an excellent option for high-performance logging in Go applications.

Acknowledgment

This log is heavily inspired by zerolog, glog, gjson and lumberjack.

Documentation

Index

• Constants
• Variables
• func Fastrandn(n uint32) uint32
• func Goid() int64
• func IsTerminal(fd uintptr) bool
• func Printf(format string, v ...any)
• func SlogNewJSONHandler(writer io.Writer, options *slog.HandlerOptions) slog.Handler
• type AsyncWriter
  • func (w *AsyncWriter) Close() (err error)
  • func (w *AsyncWriter) Write(p []byte) (n int, err error)
  • func (w *AsyncWriter) WriteEntry(e *Entry) (int, error)
• type ConsoleWriter
  • func (w *ConsoleWriter) Close() (err error)
  • func (w *ConsoleWriter) WriteEntry(e *Entry) (int, error)
• type Context
• type Entry
  • func Debug() (e *Entry)
  • func Error() (e *Entry)
  • func Fatal() (e *Entry)
  • func Info() (e *Entry)
  • func NewContext(dst []byte) (e *Entry)
  • func Panic() (e *Entry)
  • func Trace() (e *Entry)
  • func Warn() (e *Entry)
  • func (e *Entry) AnErr(key string, err error) *Entry
  • func (e *Entry) Any(key string, value any) *Entry
  • func (e *Entry) Bool(key string, b bool) *Entry
  • func (e *Entry) Bools(key string, b []bool) *Entry
  • func (e *Entry) Byte(key string, val byte) *Entry
  • func (e *Entry) Bytes(key string, val []byte) *Entry
  • func (e *Entry) BytesOrNil(key string, val []byte) *Entry
  • func (e *Entry) Caller(depth int) *Entry
  • func (e *Entry) Context(ctx Context) *Entry
  • func (e *Entry) Dict(key string, ctx Context) *Entry
  • func (e *Entry) Discard() *Entry
  • func (e *Entry) Dur(key string, d time.Duration) *Entry
  • func (e *Entry) Durs(key string, d []time.Duration) *Entry
  • func (e *Entry) EmbedObject(obj ObjectMarshaler) *Entry
  • func (e *Entry) Enabled() bool
  • func (e *Entry) Encode(key string, val []byte, enc interface{ ... }) *Entry
  • func (e *Entry) Err(err error) *Entry
  • func (e *Entry) Errs(key string, errs []error) *Entry
  • func (e *Entry) Fields(fields Fields) *Entry
  • func (e *Entry) Float32(key string, f float32) *Entry
  • func (e *Entry) Float64(key string, f float64) *Entry
  • func (e *Entry) Floats32(key string, f []float32) *Entry
  • func (e *Entry) Floats64(key string, f []float64) *Entry
  • func (e *Entry) Func(f func(e *Entry)) *Entry
  • func (e *Entry) GoStringer(key string, val fmt.GoStringer) *Entry
  • func (e *Entry) Hex(key string, val []byte) *Entry
  • func (e *Entry) IPAddr(key string, ip net.IP) *Entry
  • func (e *Entry) IPPrefix(key string, pfx net.IPNet) *Entry
  • func (e *Entry) Int(key string, i int) *Entry
  • func (e *Entry) Int16(key string, i int16) *Entry
  • func (e *Entry) Int32(key string, i int32) *Entry
  • func (e *Entry) Int64(key string, i int64) *Entry
  • func (e *Entry) Int8(key string, i int8) *Entry
  • func (e *Entry) Interface(key string, i any) *Entry
  • func (e *Entry) Ints(key string, a []int) *Entry
  • func (e *Entry) Ints16(key string, a []int16) *Entry
  • func (e *Entry) Ints32(key string, a []int32) *Entry
  • func (e *Entry) Ints64(key string, a []int64) *Entry
  • func (e *Entry) Ints8(key string, a []int8) *Entry
  • func (e *Entry) KeysAndValues(keysAndValues ...any) *Entry
  • func (e *Entry) MACAddr(key string, ha net.HardwareAddr) *Entry
  • func (e *Entry) Msg(msg string)
  • func (e *Entry) Msgf(format string, v ...any)
  • func (e *Entry) Msgs(args ...any)
  • func (e *Entry) NetIPAddr(key string, ip netip.Addr) *Entry
  • func (e *Entry) NetIPAddrPort(key string, ipPort netip.AddrPort) *Entry
  • func (e *Entry) NetIPPrefix(key string, pfx netip.Prefix) *Entry
  • func (e *Entry) Object(key string, obj ObjectMarshaler) *Entry
  • func (e *Entry) Objects(key string, objects any) *Entry
  • func (e *Entry) RawJSON(key string, b []byte) *Entry
  • func (e *Entry) RawJSONStr(key string, s string) *Entry
  • func (e *Entry) Stack() *Entry
  • func (e *Entry) Str(key string, val string) *Entry
  • func (e *Entry) StrInt(key string, val int64) *Entry
  • func (e *Entry) Stringer(key string, val fmt.Stringer) *Entry
  • func (e *Entry) Strs(key string, vals []string) *Entry
  • func (e *Entry) Time(key string, t time.Time) *Entry
  • func (e *Entry) TimeDiff(key string, t time.Time, start time.Time) *Entry
  • func (e *Entry) TimeFormat(key string, timefmt string, t time.Time) *Entry
  • func (e *Entry) Times(key string, a []time.Time) *Entry
  • func (e *Entry) TimesFormat(key string, timefmt string, a []time.Time) *Entry
  • func (e *Entry) Type(key string, v any) *Entry
  • func (e *Entry) Uint(key string, i uint) *Entry
  • func (e *Entry) Uint16(key string, i uint16) *Entry
  • func (e *Entry) Uint32(key string, i uint32) *Entry
  • func (e *Entry) Uint64(key string, i uint64) *Entry
  • func (e *Entry) Uint8(key string, i uint8) *Entry
  • func (e *Entry) Uints(key string, a []uint) *Entry
  • func (e *Entry) Uints16(key string, a []uint16) *Entry
  • func (e *Entry) Uints32(key string, a []uint32) *Entry
  • func (e *Entry) Uints64(key string, a []uint64) *Entry
  • func (e *Entry) Uints8(key string, a []uint8) *Entry
  • func (e *Entry) Value() Context
  • func (e *Entry) Xid(key string, xid [12]byte) *Entry
• type Fields
• type FileWriter
  • func (w *FileWriter) Close() (err error)
  • func (w *FileWriter) Rotate() (err error)
  • func (w *FileWriter) Write(p []byte) (n int, err error)
  • func (w *FileWriter) WriteEntry(e *Entry) (n int, err error)
  • func (w *FileWriter) WriteV(iovs []syscall.Iovec) (n uintptr, err error)
• type FormatterArgs
  • func (args *FormatterArgs) Get(key string) (value string)
• type IOWriteCloser
  • func (w IOWriteCloser) Close() (err error)
  • func (w IOWriteCloser) WriteEntry(e *Entry) (n int, err error)
• type IOWriter
  • func (w IOWriter) WriteEntry(e *Entry) (n int, err error)
• type JournalWriter
  • func (w *JournalWriter) Close() (err error)
  • func (w *JournalWriter) WriteEntry(e *Entry) (n int, err error)
• type Level
  • func ParseLevel(s string) (level Level)
  • func (l Level) String() (s string)
• type LogfmtFormatter
  • func (f LogfmtFormatter) Formatter(out io.Writer, args *FormatterArgs) (n int, err error)
• type Logger
  • func (l *Logger) Debug() (e *Entry)
  • func (l *Logger) Err(err error) (e *Entry)
  • func (l *Logger) Error() (e *Entry)
  • func (l *Logger) Fatal() (e *Entry)
  • func (l *Logger) Info() (e *Entry)
  • func (l *Logger) Log() (e *Entry)
  • func (l *Logger) Panic() (e *Entry)
  • func (l *Logger) Printf(format string, v ...any)
  • func (l *Logger) SetLevel(level Level)
  • func (l *Logger) Slog() *slog.Logger
  • func (l *Logger) Std(prefix string, flag int) *stdLog.Logger
  • func (l *Logger) Trace() (e *Entry)
  • func (l *Logger) Warn() (e *Entry)
  • func (l *Logger) WithLevel(level Level) (e *Entry)
• type MultiEntryWriter
  • func (w *MultiEntryWriter) Close() (err error)
  • func (w *MultiEntryWriter) WriteEntry(e *Entry) (n int, err error)
• type MultiIOWriter
  • func (w *MultiIOWriter) Close() (err error)
  • func (w *MultiIOWriter) WriteEntry(e *Entry) (n int, err error)
• type MultiLevelWriter
  • func (w *MultiLevelWriter) Close() (err error)
  • func (w *MultiLevelWriter) WriteEntry(e *Entry) (n int, err error)
• type MultiWriter
• type ObjectMarshaler
• type SyslogWriter
  • func (w *SyslogWriter) Close() (err error)
  • func (w *SyslogWriter) WriteEntry(e *Entry) (n int, err error)
• type TSVEntry
  • func (e *TSVEntry) Bool(b bool) *TSVEntry
  • func (e *TSVEntry) BoolString(b bool) *TSVEntry
  • func (e *TSVEntry) Byte(b byte) *TSVEntry
  • func (e *TSVEntry) Bytes(val []byte) *TSVEntry
  • func (e *TSVEntry) Caller(depth int) *TSVEntry
  • func (e *TSVEntry) Encode(key string, val []byte, enc interface{ ... }) *TSVEntry
  • func (e *TSVEntry) Float32(f float32) *TSVEntry
  • func (e *TSVEntry) Float64(f float64) *TSVEntry
  • func (e *TSVEntry) IPAddr(ip net.IP) *TSVEntry
  • func (e *TSVEntry) Int(i int) *TSVEntry
  • func (e *TSVEntry) Int16(i int16) *TSVEntry
  • func (e *TSVEntry) Int32(i int32) *TSVEntry
  • func (e *TSVEntry) Int64(i int64) *TSVEntry
  • func (e *TSVEntry) Int8(i int8) *TSVEntry
  • func (e *TSVEntry) Msg()
  • func (e *TSVEntry) NetIPAddr(ip netip.Addr) *TSVEntry
  • func (e *TSVEntry) NetIPAddrPort(ipPort netip.AddrPort) *TSVEntry
  • func (e *TSVEntry) NetIPPrefix(pfx netip.Prefix) *TSVEntry
  • func (e *TSVEntry) Str(val string) *TSVEntry
  • func (e *TSVEntry) Timestamp() *TSVEntry
  • func (e *TSVEntry) TimestampMS() *TSVEntry
  • func (e *TSVEntry) Uint(i uint) *TSVEntry
  • func (e *TSVEntry) Uint16(i uint16) *TSVEntry
  • func (e *TSVEntry) Uint32(i uint32) *TSVEntry
  • func (e *TSVEntry) Uint64(i uint64) *TSVEntry
  • func (e *TSVEntry) Uint8(i uint8) *TSVEntry
• type TSVLogger
  • func (l *TSVLogger) New() (e *TSVEntry)
• type Writer
• type WriterFunc
  • func (f WriterFunc) WriteEntry(e *Entry) (int, error)
• type XID
  • func NewXID() XID
  • func NewXIDWithTime(timestamp int64) (x XID)
  • func ParseXID(s string) (x XID, err error)
  • func (x XID) Counter() uint32
  • func (x XID) Machine() []byte
  • func (x XID) MarshalJSON() (dst []byte, err error)
  • func (x XID) MarshalText() (dst []byte, err error)
  • func (x XID) Pid() uint16
  • func (x XID) String() string
  • func (x XID) Time() time.Time
  • func (x *XID) UnmarshalJSON(b []byte) (err error)
  • func (x *XID) UnmarshalText(text []byte) (err error)

Constants

const ErrInvalidXID = xidError("xid: invalid XID")

ErrInvalidXID is returned when trying to parse an invalid XID

const TimeFormatUnix = "\x01"

TimeFormatUnix defines a time format that makes time fields to be serialized as Unix timestamp integers.

const TimeFormatUnixMs = "\x02"

TimeFormatUnixMs defines a time format that makes time fields to be serialized as Unix timestamp integers in milliseconds.

const TimeFormatUnixWithMs = "\x03"

TimeFormatUnixWithMs defines a time format that makes time fields to be serialized as Unix timestamp timestamp floats.

Variables

var DefaultLogger = Logger{
	Level:      DebugLevel,
	Caller:     0,
	TimeField:  "",
	TimeFormat: "",
	Writer:     IOWriter{os.Stderr},
}

DefaultLogger is the global logger.

var ErrAsyncWriterFull = errors.New("async writer is full")

Functions

func Fastrandn

func Fastrandn(n uint32) uint32

Fastrandn returns a pseudorandom uint32 in [0,n).

func Goid

func Goid() int64

Goid returns the current goroutine id. It exactly matches goroutine id of the stack trace.

func IsTerminal

func IsTerminal(fd uintptr) bool

IsTerminal returns whether the given file descriptor is a terminal.

func Printf

func Printf(format string, v ...any)

Printf sends a log entry without extra field. Arguments are handled in the manner of fmt.Printf.

func SlogNewJSONHandler

func SlogNewJSONHandler(writer io.Writer, options *slog.HandlerOptions) slog.Handler

SlogNewJSONHandler returns a drop-in replacement of slog.NewJSONHandler.

Types

type AsyncWriter

type AsyncWriter struct {
	// Writer specifies the writer of output.
	Writer Writer

	// ChannelSize is the size of the data channel, the default size is 1.
	ChannelSize uint

	// DiscardOnFull determines whether to discard new entry when the channel is full.
	DiscardOnFull bool

	// DisableWritev disables the writev syscall if the Writer is a FileWriter.
	DisableWritev bool
	// contains filtered or unexported fields
}

AsyncWriter is a Writer that writes asynchronously.

func (*AsyncWriter) Close

func (w *AsyncWriter) Close() (err error)

Close implements io.Closer, and closes the underlying Writer.

func (*AsyncWriter) Write

func (w *AsyncWriter) Write(p []byte) (n int, err error)

Write implements io.Writer.

func (*AsyncWriter) WriteEntry

func (w *AsyncWriter) WriteEntry(e *Entry) (int, error)

WriteEntry implements Writer.

type ConsoleWriter

type ConsoleWriter struct {
	// ColorOutput determines if used colorized output.
	ColorOutput bool

	// QuoteString determines if quoting string values.
	QuoteString bool

	// EndWithMessage determines if output message in the end.
	EndWithMessage bool

	// Formatter specifies an optional text formatter for creating a customized output,
	// If it is set, ColorOutput, QuoteString and EndWithMessage will be ignore.
	Formatter func(w io.Writer, args *FormatterArgs) (n int, err error)

	// Writer is the output destination. using os.Stderr if empty.
	Writer io.Writer
}

ConsoleWriter parses the JSON input and writes it in a colorized, human-friendly format to Writer. IMPORTANT: Don't use ConsoleWriter on critical path of a high concurrency and low latency application.

Default output format:

{Time} {Level} {Goid} {Caller} > {Message} {Key}={Value} {Key}={Value}

Note: The performance of ConsoleWriter is not good enough, because it will parses JSON input into structured records, then output in a specific order. Roughly 2x faster than logrus.TextFormatter, 0.8x fast as zap.ConsoleEncoder, and 5x faster than zerolog.ConsoleWriter.

func (*ConsoleWriter) Close

func (w *ConsoleWriter) Close() (err error)

Close implements io.Closer, will closes the underlying Writer if not empty.

func (*ConsoleWriter) WriteEntry

func (w *ConsoleWriter) WriteEntry(e *Entry) (int, error)

WriteEntry implements Writer.

type Context

type Context []byte

Context represents contextual fields.

type Entry

type Entry struct {
	Level Level
	// contains filtered or unexported fields
}

Entry represents a log entry. It is instanced by one of the level method of Logger and finalized by the Msg or Msgf method.

func Debug

func Debug() (e *Entry)

Debug starts a new message with debug level.

func Error

func Error() (e *Entry)

Error starts a new message with error level.

func Fatal

func Fatal() (e *Entry)

Fatal starts a new message with fatal level.

func Info

func Info() (e *Entry)

Info starts a new message with info level.

func NewContext

func NewContext(dst []byte) (e *Entry)

NewContext starts a new contextual entry.

func Panic

func Panic() (e *Entry)

Panic starts a new message with panic level.

func Trace

func Trace() (e *Entry)

Trace starts a new message with trace level.

func Warn

func Warn() (e *Entry)

Warn starts a new message with warning level.

func (*Entry) AnErr

func (e *Entry) AnErr(key string, err error) *Entry

AnErr adds the field key with serialized err to the logger context.

func (*Entry) Any

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

Any adds the field key with f as an any value to the entry.

func (*Entry) Bool

func (e *Entry) Bool(key string, b bool) *Entry

Bool append append the val as a bool to the entry.

func (*Entry) Bools

func (e *Entry) Bools(key string, b []bool) *Entry

Bools adds the field key with val as a []bool to the entry.

func (*Entry) Byte

func (e *Entry) Byte(key string, val byte) *Entry

Byte adds the field key with val as a byte to the entry.

func (*Entry) Bytes

func (e *Entry) Bytes(key string, val []byte) *Entry

Bytes adds the field key with val as a string to the entry.

func (*Entry) BytesOrNil

func (e *Entry) BytesOrNil(key string, val []byte) *Entry

BytesOrNil adds the field key with val as a string or nil to the entry.

func (*Entry) Caller

func (e *Entry) Caller(depth int) *Entry

Caller adds the file:line of the "caller" key. If depth is negative, adds the full /path/to/file:line of the "caller" key.

func (*Entry) Context

func (e *Entry) Context(ctx Context) *Entry

Context sends the contextual fields to entry.

func (*Entry) Dict

func (e *Entry) Dict(key string, ctx Context) *Entry

Dict sends the contextual fields with key to entry.

func (*Entry) Discard

func (e *Entry) Discard() *Entry

Discard disables the entry so Msg(f) won't print it.

func (*Entry) Dur

func (e *Entry) Dur(key string, d time.Duration) *Entry

Dur adds the field key with duration d to the entry.

func (*Entry) Durs

func (e *Entry) Durs(key string, d []time.Duration) *Entry

Durs adds the field key with val as a []time.Duration to the entry.

func (*Entry) EmbedObject

func (e *Entry) EmbedObject(obj ObjectMarshaler) *Entry

EmbedObject marshals and Embeds an object that implement the ObjectMarshaler interface.

func (*Entry) Enabled

func (e *Entry) Enabled() bool

Enabled return false if the entry is going to be filtered out by log level.

func (*Entry) Encode

func (e *Entry) Encode(key string, val []byte, enc interface {
	AppendEncode(dst, src []byte) []byte
}) *Entry

Encode encodes bytes using enc.AppendEncode to the entry.

func (*Entry) Err

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

Err adds the field "error" with serialized err to the entry.

func (*Entry) Errs

func (e *Entry) Errs(key string, errs []error) *Entry

Errs adds the field key with errs as an array of serialized errors to the entry.

func (*Entry) Fields

func (e *Entry) Fields(fields Fields) *Entry

Fields is a helper function to use a map to set fields using type assertion.

func (*Entry) Float32

func (e *Entry) Float32(key string, f float32) *Entry

Float32 adds the field key with f as a float32 to the entry.

func (*Entry) Float64

func (e *Entry) Float64(key string, f float64) *Entry

Float64 adds the field key with f as a float64 to the entry.

func (*Entry) Floats32

func (e *Entry) Floats32(key string, f []float32) *Entry

Floats32 adds the field key with f as a []float32 to the entry.

func (*Entry) Floats64

func (e *Entry) Floats64(key string, f []float64) *Entry

Floats64 adds the field key with f as a []float64 to the entry.

func (*Entry) Func

func (e *Entry) Func(f func(e *Entry)) *Entry

Func allows an anonymous func to run only if the entry is enabled.

func (*Entry) GoStringer

func (e *Entry) GoStringer(key string, val fmt.GoStringer) *Entry

GoStringer adds the field key with val.GoStringer() to the entry.

func (*Entry) Hex

func (e *Entry) Hex(key string, val []byte) *Entry

Hex adds the field key with val as a hex string to the entry.

func (*Entry) IPAddr

func (e *Entry) IPAddr(key string, ip net.IP) *Entry

IPAddr adds IPv4 or IPv6 Address to the entry.

func (*Entry) IPPrefix

func (e *Entry) IPPrefix(key string, pfx net.IPNet) *Entry

IPPrefix adds IPv4 or IPv6 Prefix (address and mask) to the entry.

func (*Entry) Int

func (e *Entry) Int(key string, i int) *Entry

Int adds the field key with i as a int to the entry.

func (*Entry) Int16

func (e *Entry) Int16(key string, i int16) *Entry

Int16 adds the field key with i as a int16 to the entry.

func (*Entry) Int32

func (e *Entry) Int32(key string, i int32) *Entry

Int32 adds the field key with i as a int32 to the entry.

func (*Entry) Int64

func (e *Entry) Int64(key string, i int64) *Entry

Int64 adds the field key with i as a int64 to the entry.

func (*Entry) Int8

func (e *Entry) Int8(key string, i int8) *Entry

Int8 adds the field key with i as a int8 to the entry.

func (*Entry) Interface

func (e *Entry) Interface(key string, i any) *Entry

Interface adds the field key with i marshaled using reflection.

func (*Entry) Ints

func (e *Entry) Ints(key string, a []int) *Entry

Ints adds the field key with i as a []int to the entry.

func (*Entry) Ints16

func (e *Entry) Ints16(key string, a []int16) *Entry

Ints16 adds the field key with i as a []int16 to the entry.

func (*Entry) Ints32

func (e *Entry) Ints32(key string, a []int32) *Entry

Ints32 adds the field key with i as a []int32 to the entry.

func (*Entry) Ints64

func (e *Entry) Ints64(key string, a []int64) *Entry

Ints64 adds the field key with i as a []int64 to the entry.

func (*Entry) Ints8

func (e *Entry) Ints8(key string, a []int8) *Entry

Ints8 adds the field key with i as a []int8 to the entry.

func (*Entry) KeysAndValues

func (e *Entry) KeysAndValues(keysAndValues ...any) *Entry

KeysAndValues sends keysAndValues to Entry

func (*Entry) MACAddr

func (e *Entry) MACAddr(key string, ha net.HardwareAddr) *Entry

MACAddr adds MAC address to the entry.

func (*Entry) Msg

func (e *Entry) Msg(msg string)

Msg sends the entry with msg added as the message field if not empty.

func (*Entry) Msgf

func (e *Entry) Msgf(format string, v ...any)

Msgf sends the entry with formatted msg added as the message field if not empty.

func (*Entry) Msgs

func (e *Entry) Msgs(args ...any)

Msgs sends the entry with msgs added as the message field if not empty.

func (*Entry) NetIPAddr

func (e *Entry) NetIPAddr(key string, ip netip.Addr) *Entry

NetIPAddr adds IPv4 or IPv6 Address to the entry.

func (*Entry) NetIPAddrPort

func (e *Entry) NetIPAddrPort(key string, ipPort netip.AddrPort) *Entry

NetIPAddrPort adds IPv4 or IPv6 with Port Address to the entry.

func (*Entry) NetIPPrefix

func (e *Entry) NetIPPrefix(key string, pfx netip.Prefix) *Entry

NetIPPrefix adds IPv4 or IPv6 Prefix (address and mask) to the entry.

func (*Entry) Object

func (e *Entry) Object(key string, obj ObjectMarshaler) *Entry

Object marshals an object that implement the ObjectMarshaler interface.

func (*Entry) Objects

func (e *Entry) Objects(key string, objects any) *Entry

Objects marshals a slice of objects that implement the ObjectMarshaler interface.

func (*Entry) RawJSON

func (e *Entry) RawJSON(key string, b []byte) *Entry

RawJSON adds already encoded JSON to the log line under key.

func (*Entry) RawJSONStr

func (e *Entry) RawJSONStr(key string, s string) *Entry

RawJSONStr adds already encoded JSON String to the log line under key.

func (*Entry) Stack

func (e *Entry) Stack() *Entry

Stack enables stack trace printing for the error passed to Err().

func (*Entry) Str

func (e *Entry) Str(key string, val string) *Entry

Str adds the field key with val as a string to the entry.

func (*Entry) StrInt

func (e *Entry) StrInt(key string, val int64) *Entry

StrInt adds the field key with integer val as a string to the entry.

func (*Entry) Stringer

func (e *Entry) Stringer(key string, val fmt.Stringer) *Entry

Stringer adds the field key with val.String() to the entry.

func (*Entry) Strs

func (e *Entry) Strs(key string, vals []string) *Entry

Strs adds the field key with vals as a []string to the entry.

func (*Entry) Time

func (e *Entry) Time(key string, t time.Time) *Entry

Time append append t formated as string using time.RFC3339Nano.

func (*Entry) TimeDiff

func (e *Entry) TimeDiff(key string, t time.Time, start time.Time) *Entry

TimeDiff adds the field key with positive duration between time t and start. If time t is not greater than start, duration will be 0. Duration format follows the same principle as Dur().

func (*Entry) TimeFormat

func (e *Entry) TimeFormat(key string, timefmt string, t time.Time) *Entry

TimeFormat append append t formated as string using timefmt.

func (*Entry) Times

func (e *Entry) Times(key string, a []time.Time) *Entry

Times append append a formated as string array using time.RFC3339Nano.

func (*Entry) TimesFormat

func (e *Entry) TimesFormat(key string, timefmt string, a []time.Time) *Entry

TimesFormat append append a formated as string array using timefmt.

func (*Entry) Type

func (e *Entry) Type(key string, v any) *Entry

Type adds type of the key using reflection to the entry.

func (*Entry) Uint

func (e *Entry) Uint(key string, i uint) *Entry

Uint adds the field key with i as a uint to the entry.

func (*Entry) Uint16

func (e *Entry) Uint16(key string, i uint16) *Entry

Uint16 adds the field key with i as a uint16 to the entry.

func (*Entry) Uint32

func (e *Entry) Uint32(key string, i uint32) *Entry

Uint32 adds the field key with i as a uint32 to the entry.

func (*Entry) Uint64

func (e *Entry) Uint64(key string, i uint64) *Entry

Uint64 adds the field key with i as a uint64 to the entry.

func (*Entry) Uint8

func (e *Entry) Uint8(key string, i uint8) *Entry

Uint8 adds the field key with i as a uint8 to the entry.

func (*Entry) Uints

func (e *Entry) Uints(key string, a []uint) *Entry

Uints adds the field key with i as a []uint to the entry.

func (*Entry) Uints16

func (e *Entry) Uints16(key string, a []uint16) *Entry

Uints16 adds the field key with i as a []uint16 to the entry.

func (*Entry) Uints32

func (e *Entry) Uints32(key string, a []uint32) *Entry

Uints32 adds the field key with i as a []uint32 to the entry.

func (*Entry) Uints64

func (e *Entry) Uints64(key string, a []uint64) *Entry

Uints64 adds the field key with i as a []uint64 to the entry.

func (*Entry) Uints8

func (e *Entry) Uints8(key string, a []uint8) *Entry

Uints8 adds the field key with i as a []uint8 to the entry.

func (*Entry) Value

func (e *Entry) Value() Context

Value builds the contextual fields.

func (*Entry) Xid

func (e *Entry) Xid(key string, xid [12]byte) *Entry

Xid adds the field key with xid.ID as a base32 string to the entry.

type Fields

type Fields map[string]any

Fields type, used to pass to `Fields`.

type FileWriter

type FileWriter struct {
	// Filename is the file to write logs to.  Backup log files will be retained
	// in the same directory.
	Filename string

	// MaxSize is the maximum size in bytes of the log file before it gets rotated.
	MaxSize int64

	// MaxBackups is the maximum number of old log files to retain.  The default
	// is to retain all old log files
	MaxBackups int

	// FileMode represents the file's mode and permission bits.  The default
	// mode is 0644
	FileMode os.FileMode

	// TimeFormat specifies the time format of filename, uses `2006-01-02T15-04-05` as default format.
	// If set with `TimeFormatUnix`, `TimeFormatUnixMs`, times are formated as UNIX timestamp.
	TimeFormat string

	// LocalTime determines if the time used for formatting the timestamps in
	// log files is the computer's local time.  The default is to use UTC time.
	LocalTime bool

	// HostName determines if the hostname used for formatting in log files.
	HostName bool

	// ProcessID determines if the pid used for formatting in log files.
	ProcessID bool

	// EnsureFolder ensures the file directory creation before writing.
	EnsureFolder bool

	// Header specifies an optional header function of log file after rotation,
	Header func(fileinfo os.FileInfo) []byte

	// Cleaner specifies an optional cleanup function of log backups after rotation,
	// if not set, the default behavior is to delete more than MaxBackups log files.
	Cleaner func(filename string, maxBackups int, matches []os.FileInfo)
	// contains filtered or unexported fields
}

FileWriter is an Writer that writes to the specified filename.

Backups use the log file name given to FileWriter, in the form `name.timestamp.ext` where name is the filename without the extension, timestamp is the time at which the log was rotated formatted with the time.Time format of `2006-01-02T15-04-05` and the extension is the original extension. For example, if your FileWriter.Filename is `/var/log/foo/server.log`, a backup created at 6:30pm on Nov 11 2016 would use the filename `/var/log/foo/server.2016-11-04T18-30-00.log`

Cleaning Up Old Log Files

Whenever a new logfile gets created, old log files may be deleted. The most recent files according to filesystem modified time will be retained, up to a number equal to MaxBackups (or all of them if MaxBackups is 0). Note that the time encoded in the timestamp is the rotation time, which may differ from the last time that file was written to.

func (*FileWriter) Close

func (w *FileWriter) Close() (err error)

Close implements io.Closer, and closes the current logfile.

func (*FileWriter) Rotate

func (w *FileWriter) Rotate() (err error)

Rotate causes Logger to close the existing log file and immediately create a new one. This is a helper function for applications that want to initiate rotations outside of the normal rotation rules, such as in response to SIGHUP. After rotating, this initiates compression and removal of old log files according to the configuration.

func (*FileWriter) Write

func (w *FileWriter) Write(p []byte) (n int, err error)

Write implements io.Writer. If a write would cause the log file to be larger than MaxSize, the file is closed, rotate to include a timestamp of the current time, and update symlink with log name file to the new file.

func (*FileWriter) WriteEntry

func (w *FileWriter) WriteEntry(e *Entry) (n int, err error)

WriteEntry implements Writer. If a write would cause the log file to be larger than MaxSize, the file is closed, rotate to include a timestamp of the current time, and update symlink with log name file to the new file.

func (*FileWriter) WriteV

func (w *FileWriter) WriteV(iovs []syscall.Iovec) (n uintptr, err error)

type FormatterArgs

type FormatterArgs struct {
	Time      string // "2019-07-10T05:35:54.277Z"
	Level     string // "info"
	Caller    string // "prog.go:42"
	Goid      string // "123"
	Stack     string // "<stack string>"
	Message   string // "a structure message"
	KeyValues []struct {
		Key       string // "foo"
		Value     string // "bar"
		ValueType byte   // 's'
	}
}

FormatterArgs is a parsed sturct from json input

func (*FormatterArgs) Get

func (args *FormatterArgs) Get(key string) (value string)

Get gets the value associated with the given key.

type IOWriteCloser

type IOWriteCloser struct {
	io.WriteCloser
}

IOWriteCloser wraps an io.IOWriteCloser to Writer.

func (IOWriteCloser) Close

func (w IOWriteCloser) Close() (err error)

Close implements Writer.

func (IOWriteCloser) WriteEntry

func (w IOWriteCloser) WriteEntry(e *Entry) (n int, err error)

WriteEntry implements Writer.

type IOWriter

type IOWriter struct {
	io.Writer
}

IOWriter wraps an io.Writer to Writer.

func (IOWriter) WriteEntry

func (w IOWriter) WriteEntry(e *Entry) (n int, err error)

WriteEntry implements Writer.

type JournalWriter

type JournalWriter struct {
	// JournalSocket specifies socket name, using `/run/systemd/journal/socket` if empty.
	JournalSocket string
	// contains filtered or unexported fields
}

JournalWriter is an Writer that writes logs to journald.

func (*JournalWriter) Close

func (w *JournalWriter) Close() (err error)

Close implements io.Closer.

func (*JournalWriter) WriteEntry

func (w *JournalWriter) WriteEntry(e *Entry) (n int, err error)

WriteEntry implements Writer.

type Level

type Level uint32

Level defines log levels.

const (
	// TraceLevel defines trace log level.
	TraceLevel Level = 1
	// DebugLevel defines debug log level.
	DebugLevel Level = 2
	// InfoLevel defines info log level.
	InfoLevel Level = 3
	// WarnLevel defines warn log level.
	WarnLevel Level = 4
	// ErrorLevel defines error log level.
	ErrorLevel Level = 5
	// FatalLevel defines fatal log level.
	FatalLevel Level = 6
	// PanicLevel defines panic log level.
	PanicLevel Level = 7
)

func ParseLevel

func ParseLevel(s string) (level Level)

ParseLevel converts a level string into a log Level value.

func (Level) String

func (l Level) String() (s string)

String return lowe case string of Level

type LogfmtFormatter

type LogfmtFormatter struct {
	TimeField string
}

func (LogfmtFormatter) Formatter

func (f LogfmtFormatter) Formatter(out io.Writer, args *FormatterArgs) (n int, err error)

type Logger

type Logger struct {
	// Level defines log levels.
	Level Level

	// Caller determines if adds the file:line of the "caller" key.
	// If Caller is negative, adds the full /path/to/file:line of the "caller" key.
	Caller int

	// TimeField defines the time field name in output.  It uses "time" in if empty.
	TimeField string

	// TimeFormat specifies the time format in output. It uses time.RFC3339 with milliseconds if empty.
	// Strongly recommended to leave TimeFormat empty for optimal built-in log formatting performance.
	// If set with `TimeFormatUnix`, `TimeFormatUnixMs`, times are formated as UNIX timestamp.
	TimeFormat string

	// TimeLocation specifics that the location which TimeFormat used. It uses time.Local if empty.
	TimeLocation *time.Location

	// Context specifies an optional context of logger.
	Context Context

	// Writer specifies the writer of output. It uses a wrapped os.Stderr Writer in if empty.
	Writer Writer
}

A Logger represents an active logging object that generates lines of JSON output to an io.Writer.

func (*Logger) Debug

func (l *Logger) Debug() (e *Entry)

Debug starts a new message with debug level.

func (*Logger) Err

func (l *Logger) Err(err error) (e *Entry)

Err starts a new message with error level with err as a field if not nil or with info level if err is nil.

func (*Logger) Error

func (l *Logger) Error() (e *Entry)

Error starts a new message with error level.

func (*Logger) Fatal

func (l *Logger) Fatal() (e *Entry)

Fatal starts a new message with fatal level.

func (*Logger) Info

func (l *Logger) Info() (e *Entry)

Info starts a new message with info level.

func (*Logger) Log

func (l *Logger) Log() (e *Entry)

Log starts a new message with no level.

func (*Logger) Panic

func (l *Logger) Panic() (e *Entry)

Panic starts a new message with panic level.

func (*Logger) Printf

func (l *Logger) Printf(format string, v ...any)

Printf sends a log entry without extra field. Arguments are handled in the manner of fmt.Printf.

func (*Logger) SetLevel

func (l *Logger) SetLevel(level Level)

SetLevel changes logger default level.

func (*Logger) Slog

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

Slog wraps the Logger to provide *slog.Logger

func (*Logger) Std

func (l *Logger) Std(prefix string, flag int) *stdLog.Logger

Std wraps the Logger to provide *stdLog.Logger

func (*Logger) Trace

func (l *Logger) Trace() (e *Entry)

Trace starts a new message with trace level.

func (*Logger) Warn

func (l *Logger) Warn() (e *Entry)

Warn starts a new message with warning level.

func (*Logger) WithLevel

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

WithLevel starts a new message with level.

type MultiEntryWriter

type MultiEntryWriter []Writer

MultiEntryWriter is an array Writer that log to different writers

func (*MultiEntryWriter) Close

func (w *MultiEntryWriter) Close() (err error)

Close implements io.Closer, and closes the underlying MultiEntryWriter.

func (*MultiEntryWriter) WriteEntry

func (w *MultiEntryWriter) WriteEntry(e *Entry) (n int, err error)

WriteEntry implements entryWriter.

type MultiIOWriter

type MultiIOWriter []io.Writer

MultiIOWriter is an array io.Writer that log to different writers

func (*MultiIOWriter) Close

func (w *MultiIOWriter) Close() (err error)

Close implements io.Closer, and closes the underlying MultiIOWriter.

func (*MultiIOWriter) WriteEntry

func (w *MultiIOWriter) WriteEntry(e *Entry) (n int, err error)

WriteEntry implements entryWriter.

type MultiLevelWriter

type MultiLevelWriter struct {
	// InfoWriter specifies all the level logs writes to
	InfoWriter Writer

	// WarnWriter specifies the level greater than or equal to WarnLevel writes to
	WarnWriter Writer

	// WarnWriter specifies the level greater than or equal to ErrorLevel writes to
	ErrorWriter Writer

	// ConsoleWriter specifies the console writer
	ConsoleWriter Writer

	// ConsoleLevel specifies the level greater than or equal to it also writes to
	ConsoleLevel Level
}

MultiLevelWriter is an Writer that log to different writers by different levels

func (*MultiLevelWriter) Close

func (w *MultiLevelWriter) Close() (err error)

Close implements io.Closer, and closes the underlying LeveledWriter.

func (*MultiLevelWriter) WriteEntry

func (w *MultiLevelWriter) WriteEntry(e *Entry) (n int, err error)

WriteEntry implements entryWriter.

type MultiWriter

type MultiWriter = MultiLevelWriter

MultiWriter is an alias for MultiLevelWriter

type ObjectMarshaler

type ObjectMarshaler interface {
	MarshalObject(e *Entry)
}

ObjectMarshaler provides a strongly-typed and encoding-agnostic interface to be implemented by types used with Entry's Object methods.

type SyslogWriter

type SyslogWriter struct {
	// Network specifies network of the syslog server
	Network string

	// Address specifies address of the syslog server
	Address string

	// Hostname specifies hostname of the syslog message
	Hostname string

	// Tag specifies tag of the syslog message
	Tag string

	// Marker specifies prefix of the syslog message, e.g. `@cee:`
	Marker string

	// Dial specifies the dial function for creating TCP/TLS connections.
	Dial func(network, addr string) (net.Conn, error)
	// contains filtered or unexported fields
}

SyslogWriter is an Writer that writes logs to a syslog server..

func (*SyslogWriter) Close

func (w *SyslogWriter) Close() (err error)

Close closes a connection to the syslog server.

func (*SyslogWriter) WriteEntry

func (w *SyslogWriter) WriteEntry(e *Entry) (n int, err error)

WriteEntry implements Writer, sends logs with priority to the syslog server.

type TSVEntry

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

TSVEntry represents a tsv log entry. It is instanced by one of TSVLogger and finalized by the Msg method.

func (*TSVEntry) Bool

func (e *TSVEntry) Bool(b bool) *TSVEntry

Bool append the b as a bool to the entry, the value of output bool is 0 or 1.

func (*TSVEntry) BoolString

func (e *TSVEntry) BoolString(b bool) *TSVEntry

BoolString append the b as a bool to the entry, the value of output bool is false or true.

func (*TSVEntry) Byte

func (e *TSVEntry) Byte(b byte) *TSVEntry

Byte append the b as a byte to the entry.

func (*TSVEntry) Bytes

func (e *TSVEntry) Bytes(val []byte) *TSVEntry

Bytes adds a bytes as string to the entry.

func (*TSVEntry) Caller

func (e *TSVEntry) Caller(depth int) *TSVEntry

Caller adds the file:line of to the entry.

func (*TSVEntry) Encode

func (e *TSVEntry) Encode(key string, val []byte, enc interface {
	AppendEncode(dst, src []byte) []byte
}) *TSVEntry

Encode encodes bytes using enc.AppendEncode to the entry.

func (*TSVEntry) Float32

func (e *TSVEntry) Float32(f float32) *TSVEntry

Float32 adds a float32 to the entry.

func (*TSVEntry) Float64

func (e *TSVEntry) Float64(f float64) *TSVEntry

Float64 adds a float64 to the entry.

func (*TSVEntry) IPAddr

func (e *TSVEntry) IPAddr(ip net.IP) *TSVEntry

IPAddr adds IPv4 or IPv6 Address to the entry.

func (*TSVEntry) Int

func (e *TSVEntry) Int(i int) *TSVEntry

Int adds a int to the entry.

func (*TSVEntry) Int16

func (e *TSVEntry) Int16(i int16) *TSVEntry

Int16 adds a int16 to the entry.

func (*TSVEntry) Int32

func (e *TSVEntry) Int32(i int32) *TSVEntry

Int32 adds a int32 to the entry.

func (*TSVEntry) Int64

func (e *TSVEntry) Int64(i int64) *TSVEntry

Int64 adds a int64 to the entry.

func (*TSVEntry) Int8

func (e *TSVEntry) Int8(i int8) *TSVEntry

Int8 adds a int8 to the entry.

func (*TSVEntry) Msg

func (e *TSVEntry) Msg()

Msg sends the entry.

func (*TSVEntry) NetIPAddr

func (e *TSVEntry) NetIPAddr(ip netip.Addr) *TSVEntry

NetIPAddr adds IPv4 or IPv6 Address to the entry.

func (*TSVEntry) NetIPAddrPort

func (e *TSVEntry) NetIPAddrPort(ipPort netip.AddrPort) *TSVEntry

NetIPAddrPort adds IPv4 or IPv6 with Port Address to the entry.

func (*TSVEntry) NetIPPrefix

func (e *TSVEntry) NetIPPrefix(pfx netip.Prefix) *TSVEntry

NetIPPrefix adds IPv4 or IPv6 Prefix (address and mask) to the entry.

func (*TSVEntry) Str

func (e *TSVEntry) Str(val string) *TSVEntry

Str adds a string to the entry.

func (*TSVEntry) Timestamp

func (e *TSVEntry) Timestamp() *TSVEntry

Timestamp adds the current time as UNIX timestamp

func (*TSVEntry) TimestampMS

func (e *TSVEntry) TimestampMS() *TSVEntry

TimestampMS adds the current time with milliseconds as UNIX timestamp

func (*TSVEntry) Uint

func (e *TSVEntry) Uint(i uint) *TSVEntry

Uint adds a uint to the entry.

func (*TSVEntry) Uint16

func (e *TSVEntry) Uint16(i uint16) *TSVEntry

Uint16 adds a uint16 to the entry.

func (*TSVEntry) Uint32

func (e *TSVEntry) Uint32(i uint32) *TSVEntry

Uint32 adds a uint32 to the entry.

func (*TSVEntry) Uint64

func (e *TSVEntry) Uint64(i uint64) *TSVEntry

Uint64 adds a uint64 to the entry.

func (*TSVEntry) Uint8

func (e *TSVEntry) Uint8(i uint8) *TSVEntry

Uint8 adds a uint8 to the entry.

type TSVLogger

type TSVLogger struct {
	Separator byte
	Writer    io.Writer
}

TSVLogger represents an active logging object that generates lines of TSV output to an io.Writer.

func (*TSVLogger) New

func (l *TSVLogger) New() (e *TSVEntry)

New starts a new tsv message.

type Writer

type Writer interface {
	WriteEntry(*Entry) (int, error)
}

Writer defines an entry writer interface.

type WriterFunc

type WriterFunc func(*Entry) (int, error)

The WriterFunc type is an adapter to allow the use of ordinary functions as log writers. If f is a function with the appropriate signature, WriterFunc(f) is a Writer that calls f.

func (WriterFunc) WriteEntry

func (f WriterFunc) WriteEntry(e *Entry) (int, error)

WriteEntry calls f(e).

type XID

type XID [12]byte

XID represents a unique request id

func NewXID

func NewXID() XID

NewXID generates a globally unique XID

func NewXIDWithTime

func NewXIDWithTime(timestamp int64) (x XID)

NewXIDWithTime generates a globally unique XID with unix timestamp

func ParseXID

func ParseXID(s string) (x XID, err error)

ParseXID parses an XID from its string representation

func (XID) Counter

func (x XID) Counter() uint32

Counter returns the incrementing value part of the id.

func (XID) Machine

func (x XID) Machine() []byte

Machine returns the 3-byte machine id part of the id.

func (XID) MarshalJSON

func (x XID) MarshalJSON() (dst []byte, err error)

MarshalJSON implements encoding/json Marshaler interface

func (XID) MarshalText

func (x XID) MarshalText() (dst []byte, err error)

MarshalText implements encoding/text TextMarshaler interface

func (XID) Pid

func (x XID) Pid() uint16

Pid returns the process id part of the id.

func (XID) String

func (x XID) String() string

String returns a base32 hex lowercased representation of the id.

func (XID) Time

func (x XID) Time() time.Time

Time returns the timestamp part of the id.

func (*XID) UnmarshalJSON

func (x *XID) UnmarshalJSON(b []byte) (err error)

UnmarshalJSON implements encoding/json Unmarshaler interface

func (*XID) UnmarshalText

func (x *XID) UnmarshalText(text []byte) (err error)

UnmarshalText implements encoding/text TextUnmarshaler interface