zeroconfig

README

zeroconfig

A relatively simple declarative config format for zerolog.

Meant to be used as YAML, but JSON struct tags are included as well.

Config reference

# Global minimum log level. Defaults to trace.
min_level: trace

# Should logs include timestamps? Defaults to true.
timestamps: true
# Should logs include the caller function? Defaults to false.
caller: false

# Additional log metadata to add globally. Map from string key to arbitrary value.
metadata: null

# List of writers to output logs to.
# The `type` field is always required. `format`, `min_level` and `max_level` can be specified for any type of writer.
# Some types have additional custom configuration
writers:
# `stdout` and `stderr` write to the corresponding standard IO streams.
# They have no custom configuration fields, the extra fields below showcase the fields that can be added to any writer.
- # The type of writer.
  type: stdout
  # The format to write. Available formats are json, pretty and pretty-colored. Defaults to json.
  format: pretty-colored
  # If format is pretty or pretty-colored, time_format can be used to specify how timestamps are formatted.
  # Uses Go time formatting https://pkg.go.dev/time#pkg-constants and defaults to RFC3339 (2006-01-02T15:04:05Z07:00).
  time_format: 2006-01-02 15:04:05
  # Minimum level for this writer. Defaults to no level (i.e. inherited from root min_level).
  # This can only reduce the amount of logs written to this writer, levels below the global min_level are never logged.
  min_level: info
  # Maximum level for this writer. Defaults to no level (all logs above minimum are logged).
  max_level: warn
# If you want errors in stderr, make a separate writer like this:
# If you want all logs in stdout, just remove this and the max_level above.
- type: stderr
  format: pretty-colored
  min_level: error

# `file` is a rotating file handler (https://github.com/natefinch/lumberjack).
- type: file
  # File name for the current log. Backups will be stored in the same directory, named as name-<timestamp>.ext
  filename: example.log
  # Maximum size in megabytes for the log file before rotating. Defaults to 100 megabytes.
  max_size: 100
  # Maximum age of rotated log files to keep as days. Defaults to no limit.
  max_age: 0
  # Maximum number of rotated log files to keep. Defaults to no limit.
  max_backups: 0
  # Should rotated log file names use local time instead of UTC? Defaults to false.
  local_time: false
  # Should rotated log files be compressed with gzip? Defaults to false.
  compress: false

# `syslog` writes to the system log service using the Go stdlib syslog package.
- type: syslog  # you can also use syslog-cee to add the MITRE CEE prefix.
  # These four parameters are passed to https://pkg.go.dev/log/syslog#Dial directly.
  network: udp
  host: localhost
  # Priority flags as defined in syslog.h
  flags: 8
  tag: zerolog

# `journald` writes to systemd's logging service using https://github.com/coreos/go-systemd.
# It has no custom configuration fields.
- type: journald

Usage example

package main

import (
	"github.com/rs/zerolog"
	"go.mau.fi/zeroconfig"
	"gopkg.in/yaml.v3"
)

func prepareLog(yamlConfig []byte) (*zerolog.Logger, error) {
	var cfg zeroconfig.Config
	err := yaml.Unmarshal(yamlConfig, &cfg)
	if err != nil {
		return nil, err
	}
	return cfg.Compile()
}

// This should obviously be loaded from a file rather than hardcoded
const logConfig = `
min_level: debug
writers:
- type: stdout
  format: pretty-colored
`

func main() {
	log, err := prepareLog([]byte(logConfig))
	if err != nil {
		panic(err)
	}
	log.Info().Msg("Logger initialized")
}

Documentation

Index

• Variables
• func MinMaxLevelWriter(writer io.Writer, minLevel, maxLevel zerolog.Level) zerolog.LevelWriter
• func RegisterWriter(wt WriterType, compiler WriterCompiler)
• type Config
  • func (c *Config) Compile() (*zerolog.Logger, error)
• type FileConfig
• type LogFormat
• type SyslogConfig
• type WriterCompiler
• type WriterConfig
  • func (wc *WriterConfig) Compile() (io.Writer, error)
• type WriterType

Variables

var (
	Stdout io.Writer = os.Stdout
	Stderr io.Writer = os.Stderr
)

Outputs used for the stdout and stderr writer types.

Functions

func MinMaxLevelWriter

func MinMaxLevelWriter(writer io.Writer, minLevel, maxLevel zerolog.Level) zerolog.LevelWriter

MinMaxLevelWriter wraps a writer in a zerolog.LevelWriter, but limits the log levels that can pass through.

func RegisterWriter

func RegisterWriter(wt WriterType, compiler WriterCompiler)

Types

type Config

type Config struct {
	Writers  []WriterConfig `json:"writers,omitempty" yaml:"writers,omitempty"`
	MinLevel *zerolog.Level `json:"min_level,omitempty" yaml:"min_level,omitempty"`

	Timestamp *bool `json:"timestamp,omitempty" yaml:"timestamp,omitempty"`
	Caller    bool  `json:"caller,omitempty" yaml:"caller,omitempty"`

	Metadata map[string]any `json:"metadata,omitempty" yaml:"metadata,omitempty"`
}

Config contains all the configuration to create a zerolog logger.

func (*Config) Compile

func (c *Config) Compile() (*zerolog.Logger, error)

Compile creates a zerolog.Logger instance out of the configuration in this struct.

type FileConfig

type FileConfig struct {
	// File name for the current log. Backups will be stored in the same directory, named as name-<timestamp>.ext
	Filename string `json:"filename,omitempty" yaml:"filename,omitempty"`
	// Maximum size in megabytes for the log file before rotating. Defaults to 100 megabytes.
	MaxSize int `json:"max_size,omitempty" yaml:"max_size,omitempty"`
	// Maximum age of rotated log files to keep as days. Defaults to no limit.
	MaxAge int `json:"max_age,omitempty" yaml:"max_age,omitempty"`
	// Maximum number of rotated log files to keep. Defaults to no limit.
	MaxBackups int `json:"max_backups,omitempty" yaml:"max_backups,omitempty"`
	// Should rotated log file names use local time instead of UTC? Defaults to false.
	LocalTime bool `json:"local_time,omitempty" yaml:"local_time,omitempty"`
	// Should rotated log files be compressed with gzip? Defaults to false.
	Compress bool `json:"compress,omitempty" yaml:"compress,omitempty"`
}

FileConfig contains the configuration options for the file writer.

See https://github.com/natefinch/lumberjack for exact details.

type LogFormat

type LogFormat string

LogFormat describes how logs should be formatted for a writer.

const (
	// LogFormatJSON outputs logs as the raw JSON that zerolog produces.
	LogFormatJSON LogFormat = "json"
	// LogFormatPretty uses zerolog's console writer, but disables color.
	LogFormatPretty LogFormat = "pretty"
	// LogFormatPrettyColored uses zerolog's console writer including color.
	LogFormatPrettyColored LogFormat = "pretty-colored"
)

type SyslogConfig

type SyslogConfig struct {
	// All parameters are passed to https://pkg.go.dev/log/syslog#Dial directly.
	Network string `json:"network,omitempty" yaml:"network,omitempty"`
	Host    string `json:"host,omitempty" yaml:"host,omitempty"`
	Flags   int    `json:"flags,omitempty" yaml:"flags,omitempty"`
	Tag     string `json:"tag,omitempty" yaml:"tag,omitempty"`
}

SyslogConfig contains the configuration options for the syslog writer.

See https://pkg.go.dev/log/syslog for exact details.

type WriterCompiler

type WriterCompiler = func(*WriterConfig) (io.Writer, error)

type WriterConfig

type WriterConfig struct {
	// The type of writer.
	Type   WriterType `json:"type" yaml:"type"`
	Format LogFormat  `json:"format,omitempty" yaml:"format,omitempty"`

	MinLevel *zerolog.Level `json:"min_level,omitempty" yaml:"min_level,omitempty"`
	MaxLevel *zerolog.Level `json:"max_level,omitempty" yaml:"max_level,omitempty"`

	// Only applies when format=console or format=console-colored
	TimeFormat string `json:"time_format,omitempty" yaml:"time_format,omitempty"`

	SyslogConfig `json:",inline,omitempty" yaml:",inline,omitempty"`
	FileConfig   `json:",inline,omitempty" yaml:",inline,omitempty"`
}

WriterConfig contains the configuration for an individual log writer.

func (*WriterConfig) Compile

func (wc *WriterConfig) Compile() (io.Writer, error)

Compile creates an io.Writer instance out of the configuration in this struct.

type WriterType

type WriterType string

WriterType is a type of writer.

const (
	// WriterTypeStdout writes to stdout.
	WriterTypeStdout WriterType = "stdout"
	// WriterTypeStderr writes to stderr.
	WriterTypeStderr WriterType = "stderr"
	// WriterTypeFile writes to a file, including rotating the file when it gets big.
	// The configuration is stored in the FileConfig struct.
	WriterTypeFile WriterType = "file"
	// WriterTypeSyslog writes to the system logging service.
	// The configuration is stored in the SyslogConfig struct.
	WriterTypeSyslog WriterType = "syslog"
	// WriterTypeSyslogCEE writes to the system logging service with MITRE CEE prefixes.
	WriterTypeSyslogCEE WriterType = "syslog-cee"
	// WriterTypeJournald writes to systemd's logging service.
	WriterTypeJournald WriterType = "journald"
)