zerolog

README

Opinionated zerolog configuration

A Go package providing opinionated zerolog configuration and a pretty-printer tool for its logs, prettylog.

Features:

• Logging to both the console (with or without colors) and appending to a file at the same time. Each with its own logging level.
• JSON timestamps are in millisecond RFC format in UTC, e.g., 2006-01-02T15:04:05.000Z07:00.
• JSON does not escape HTML. #568
• Error's are converted to JSON using gitlab.com/tozd/go/errors's Formatter into an object with error's message, a stack trace, optional details and recursively with joined and cause errors.
• Error's optional details and a stack trace are shown when logging to the console.
• Integrates well with github.com/alecthomas/kong CLI argument parsing.
• Both Go's global log and zerolog's global log are redirected to the configured zerolog logger.
• Supports adding logger to the context which can buffer log entries (usually debug entries) until a log entry with a triggering level happens (usually an error), if ever.
• Provides a pretty-printer tool, prettylog, matching the configured zerolog's console output.

Installation

This is a Go package. You can add it to your project using go get:

go get gitlab.com/tozd/go/zerolog

It requires Go 1.23 or newer.

Releases page contains a list of stable versions of the prettylog tool. Each includes:

• Statically compiled binaries.
• Docker images.

You should just download/use the latest one.

The tool is implemented in Go. You can also use go install to install the latest stable (released) version:

go install gitlab.com/tozd/go/zerolog/cmd/go/prettylog@latest

To install the latest development version (main branch):

go install gitlab.com/tozd/go/zerolog/cmd/go/prettylog@main

Usage

As a package

The package can be used with github.com/alecthomas/kong CLI argument parsing. In that case Kong populates the logging configuration which you then pass to zerolog.New which then configures zerolog and sets Logger and WithContext fields:

int main() {
  var config zerolog.LoggingConfig
  parser := kong.Must(&config,
    kong.UsageOnError(),
    kong.Writers(
      os.Stderr,
      os.Stderr,
    ),
    kong.Vars{
      "defaultLoggingConsoleType":             DefaultConsoleType,
      "defaultLoggingConsoleLevel":            DefaultConsoleLevel,
      "defaultLoggingFileLevel":               DefaultFileLevel,
      "defaultLoggingMainLevel":               DefaultMainLevel,
      "defaultLoggingContextLevel":            DefaultContextLevel,
      "defaultLoggingContextConditionalLevel": DefaultContextConditionalLevel,
      "defaultLoggingContextTriggerLevel":     DefaultContextTriggerLevel,
    },
    zerolog.KongLevelTypeMapper,
  )
  ctx, err := parser.Parse(os.Args[1:])
  parser.FatalIfErrorf(err)
  logFile, errE := zerolog.New(&config)
  defer logFile.Close()
  parser.FatalIfErrorf(errE)
  config.Logger.Info().Msgf("%s running", ctx.Model.Name)
}

Of course, you can construct the configuration struct yourself, too. zerolog.LoggingConfig struct can also be embedded inside another struct if you need additional CLI arguments.

The main logger is available as config.Logger. You have to close returned logFile once you stop using the logger (e.g., at the end of the program).

There is also config.WithContext which allows you to add a logger to the context. Added logger buffers log entries (usually debug entries) until a log entry with a triggering level happens (usually an error), if ever. This allows you to log at a lower level (e.g., debug) but output all those log entries only if an error happens. Those logged debug entries can then help debug the error. If you want to disable this behavior, make trigger level be the same as conditional level.

zerolog.WithContext returns a new context, and two functions, close and trigger. You have to call close when you are done with the context to free up resources. And you can call trigger if you want to force writing out any buffered log entries (e.g., on panic).

See full package documentation with examples on pkg.go.dev.

prettylog tool

zerolog can output logs as JSON. If your program happens to have such output, or if you stored those logs somewhere and would like to format them in the same way zerolog's console output looks like, you can use prettylog tool:

./program | prettylog

cat program.log | prettylog

If you have Go available, you can run it without installation:

cat program.log | go run gitlab.com/tozd/go/zerolog/cmd/go/prettylog@latest

Or with Docker:

cat program.log | docker run -i registry.gitlab.com/tozd/go/zerolog/branch/main:latest

The above command runs the latest development version (main branch). See releases page for a Docker image for the latest stable version.

GitHub mirror

There is also a read-only GitHub mirror available, if you need to fork the project there.

Documentation

Overview

Package zerolog provides opinionated configuration of the zerolog package.

For details on what all is configured and initialized see package's README.

Index

• Constants
• Variables
• func New[LoggingConfigT hasLoggingConfig](config LoggingConfigT) (*os.File, errors.E)
• func NewHandler(withContext func(context.Context) (context.Context, func(), func())) func(http.Handler) http.Handler
• func PrettyLog(noColor bool, input io.Reader, output io.Writer) errors.E
• type Console
  • func (c *Console) UnmarshalJSON(b []byte) error
  • func (c *Console) UnmarshalYAML(value *yaml.Node) error
• type Context
  • func (c *Context) UnmarshalJSON(b []byte) error
  • func (c *Context) UnmarshalYAML(value *yaml.Node) error
• type File
  • func (f *File) UnmarshalJSON(b []byte) error
  • func (f *File) UnmarshalYAML(value *yaml.Node) error
• type Logging
• type LoggingConfig
  • func (l *LoggingConfig) GetLoggingConfig() *LoggingConfig
• type Main
  • func (m *Main) UnmarshalJSON(b []byte) error
  • func (m *Main) UnmarshalYAML(value *yaml.Node) error

Constants

const (
	DefaultConsoleType             = "color"
	DefaultConsoleLevel            = "debug"
	DefaultFileLevel               = "debug"
	DefaultMainLevel               = "info"
	DefaultContextLevel            = "debug"
	DefaultContextConditionalLevel = "debug"
	DefaultContextTriggerLevel     = "error"
)

Defaults to be used with Kong initialization for LoggingConfig struct:

kong.Vars{
	"defaultLoggingConsoleType":             DefaultConsoleType,
	"defaultLoggingConsoleLevel":            DefaultConsoleLevel,
	"defaultLoggingFileLevel":               DefaultFileLevel,
	"defaultLoggingMainLevel":               DefaultMainLevel,
	"defaultLoggingContextLevel":            DefaultContextLevel,
	"defaultLoggingContextConditionalLevel": DefaultContextConditionalLevel,
	"defaultLoggingContextTriggerLevel":     DefaultContextTriggerLevel,
}

const TimeFieldFormat = "2006-01-02T15:04:05.000Z07:00"

TimeFieldFormat is the format for timestamps in log entries.

Variables

var KongLevelTypeMapper = kongLevelTypeMapper

KongLevelTypeMapper should be used with Kong initialization so that logging levels found in LoggingConfig struct can be correctly parsed on populated.

Functions

func New

func New[LoggingConfigT hasLoggingConfig](config LoggingConfigT) (*os.File, errors.E)

New configures and initializes zerolog and Go's standard log package for logging.

New expects configuration embedded inside config as a LoggingConfig struct and returns the logger in its Logger field and sets its WithContext field. LoggingConfig can be initially populated with configuration using Kong.

Returned file handle belongs to the file to which log entries are appended (if file logging is enabled in configuration). Closing it is caller's responsibility.

For details on what all is configured and initialized see package's README.

func NewHandler

func NewHandler(withContext func(context.Context) (context.Context, func(), func())) func(http.Handler) http.Handler

NewHandler injects log into requests context.

func PrettyLog

func PrettyLog(noColor bool, input io.Reader, output io.Writer) errors.E

PrettyLog reads JSON lines from the input and writes to the output pretty-printed console lines using ConsoleWriter configured and initialized in the same way as New does.

Types

type Console

type Console struct {
	Type  string        `` /* 229-byte string literal not displayed */
	Level zerolog.Level `` /* 230-byte string literal not displayed */

	// Used primarily for testing.
	Output io.Writer `json:"-" kong:"-" yaml:"-"`
}

Console is configuration of logging log entries to the console (stdout by default).

Type can be the following values: color (human-friendly formatted and colorized), nocolor (just human-friendly formatted), json, disable (do not log to the console).

Level can be trace, debug, info, warn, and error.

func (*Console) UnmarshalJSON

func (c *Console) UnmarshalJSON(b []byte) error

func (*Console) UnmarshalYAML

func (c *Console) UnmarshalYAML(value *yaml.Node) error

type Context

type Context struct {
	Level            zerolog.Level `` /* 306-byte string literal not displayed */
	ConditionalLevel zerolog.Level `` /* 317-byte string literal not displayed */
	TriggerLevel     zerolog.Level `` /* 313-byte string literal not displayed */
}

Context is configuration of the context logger.

Levels can be trace, debug, info, warn, and error. Level can be also disabled to disable context logger.

It supports buffering log lines at the ConditionalLevel or below until triggered by a log entry at the TriggerLevel or higher. To disable this behavior, set Level and TriggerLevel to the same level.

func (*Context) UnmarshalJSON

func (c *Context) UnmarshalJSON(b []byte) error

func (*Context) UnmarshalYAML

func (c *Context) UnmarshalYAML(value *yaml.Node) error

type File

type File struct {
	Path  string        `` /* 235-byte string literal not displayed */
	Level zerolog.Level `` /* 236-byte string literal not displayed */
}

File is configuration of logging log entries as JSON by appending them to a file at path.

Level can be trace, debug, info, warn, and error.

func (*File) UnmarshalJSON

func (f *File) UnmarshalJSON(b []byte) error

func (*File) UnmarshalYAML

func (f *File) UnmarshalYAML(value *yaml.Node) error

type Logging

type Logging struct {
	Console Console `embed:"" json:"console" prefix:"console." yaml:"console"`
	File    File    `embed:"" json:"file"    prefix:"file."    yaml:"file"`
	Main    Main    `embed:"" json:"main"    prefix:"main."    yaml:"main"`
	Context Context `embed:"" json:"context" prefix:"context." yaml:"context"`
}

Logging is configuration for console and file logging.

type LoggingConfig

type LoggingConfig struct {
	Logger      zerolog.Logger                                          `         json:"-"       kong:"-"                   yaml:"-"`
	WithContext func(context.Context) (context.Context, func(), func()) `         json:"-"       kong:"-"                   yaml:"-"`
	Logging     Logging                                                 `embed:"" json:"logging"          prefix:"logging." yaml:"logging"`
}

LoggingConfig struct can be provided embedded inside the config argument to function New and function New returns the logger in its Logger field and sets its WithContext field.

func (*LoggingConfig) GetLoggingConfig

func (l *LoggingConfig) GetLoggingConfig() *LoggingConfig

type Main

type Main struct {
	Level zerolog.Level `` /* 290-byte string literal not displayed */
}

Main is configuration of the main logger.

Level can be trace, debug, info, warn, and error. Level can be also disabled to disable main logger.

func (*Main) UnmarshalJSON

func (m *Main) UnmarshalJSON(b []byte) error

func (*Main) UnmarshalYAML

func (m *Main) UnmarshalYAML(value *yaml.Node) error