zeroconfig

https://pkg.go.dev/go.mau.fi/zeroconfig
Admin
zeroconfig is a relatively simple declarative configuration format for zerolog, designed to compile...
Tokens:2,800
Snippets:22
Trust Score:9.6
Update:2 months ago
Show doc for...
Tokens:
Raw
### Initialize zerolog with zeroconfig

Source: https://pkg.go.dev/go.mau.fi/zeroconfig

Example showing how to unmarshal YAML configuration into a zeroconfig struct and compile it into a zerolog logger.

```go
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")
}
```

--------------------------------

### Compile Configuration to Logger

Source: https://pkg.go.dev/go.mau.fi/zeroconfig

Creates a zerolog.Logger instance from the provided configuration.

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

--------------------------------

### zeroconfig Configuration Reference

Source: https://pkg.go.dev/go.mau.fi/zeroconfig

A comprehensive YAML template defining global log settings and various writer types.

```yaml
# 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

# `js` writes to the JavaScript console. It only works when compiling to WASM.
# It will also ignore the `format` field and do custom formatting internally.
- type: js
```

--------------------------------

### Compile WriterConfig into io.Writer

Source: https://pkg.go.dev/go.mau.fi/zeroconfig

Creates an io.Writer instance based on the configuration defined in the WriterConfig struct.

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

--------------------------------

### Define Log Formats

Source: https://pkg.go.dev/go.mau.fi/zeroconfig

Supported log output formats.

```go
type LogFormat string
```

```go
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"
)
```

--------------------------------

### Define Syslog Configuration

Source: https://pkg.go.dev/go.mau.fi/zeroconfig

Configuration options for syslog-based logging.

```go
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"`
}
```

--------------------------------

### Define Logger Configuration Structure

Source: https://pkg.go.dev/go.mau.fi/zeroconfig

Main configuration struct for initializing a zerolog logger.

```go
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"`
}
```

--------------------------------

### Define Writer Configuration

Source: https://pkg.go.dev/go.mau.fi/zeroconfig

Configuration structure for individual log writers.

```go
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"`
```

--------------------------------

### Define File Writer Configuration

Source: https://pkg.go.dev/go.mau.fi/zeroconfig

Configuration options for file-based logging with rotation support.

```go
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"`
}
```

--------------------------------

### func (*WriterConfig) Compile

Source: https://pkg.go.dev/go.mau.fi/zeroconfig

Creates an io.Writer instance based on the configuration defined in the WriterConfig struct.

```APIDOC
## func (*WriterConfig) Compile

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

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

### Returns
- **io.Writer** - The configured writer instance.
- **error** - An error if the compilation fails.
```

--------------------------------

### func (*Config) Compile

Source: https://pkg.go.dev/go.mau.fi/zeroconfig

Compiles a Config struct into a usable zerolog.Logger instance.

```APIDOC
## func (*Config) Compile() (*zerolog.Logger, error)

### Description
Creates a zerolog.Logger instance out of the configuration defined in the Config struct.

### Returns
- **(*zerolog.Logger, error)** - Returns the configured logger or an error if compilation fails.
```

--------------------------------

### func (*WriterConfig) Compile

Source: https://pkg.go.dev/go.mau.fi/zeroconfig

Compiles a WriterConfig into an io.Writer.

```APIDOC
## func (*WriterConfig) Compile() (io.Writer, error)

### Description
Compiles the writer configuration into an io.Writer instance.

### Returns
- **(io.Writer, error)** - Returns the configured writer or an error if compilation fails.
```

--------------------------------

### Define MinMaxLevelWriter Function

Source: https://pkg.go.dev/go.mau.fi/zeroconfig

Wraps an io.Writer into a zerolog.LevelWriter with specific level constraints.

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

--------------------------------

### Define WriterType constants

Source: https://pkg.go.dev/go.mau.fi/zeroconfig

Enumerates the supported logging destinations, including standard streams, files, syslog, journald, and JavaScript console output.

```go
type WriterType string

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"
	// WriterTypeJS writes to a JavaScript console.
	// Only usable in environments where syscall/js is available (i.e. GOOS=js/GOARCH=wasm).
	WriterTypeJS WriterType = "js"
)
```

--------------------------------

### Define Standard Output Variables

Source: https://pkg.go.dev/go.mau.fi/zeroconfig

Standard output and error writer variables used for logging destinations.

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

--------------------------------

### Register Custom Writer

Source: https://pkg.go.dev/go.mau.fi/zeroconfig

Registers a custom compiler for a specific writer type.

```go
func RegisterWriter(wt WriterType, compiler WriterCompiler)
```

--------------------------------

### Define Writer Compiler Type

Source: https://pkg.go.dev/go.mau.fi/zeroconfig

Function signature for compiling a writer configuration into an io.Writer.

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

--------------------------------

### func MinMaxLevelWriter

Source: https://pkg.go.dev/go.mau.fi/zeroconfig

Wraps an io.Writer in a zerolog.LevelWriter, restricting the log levels that are permitted to pass through.

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

### Description
Wraps a writer in a zerolog.LevelWriter, but limits the log levels that can pass through.

### Parameters
- **writer** (io.Writer) - Required - The underlying writer to wrap.
- **minLevel** (zerolog.Level) - Required - The minimum log level allowed.
- **maxLevel** (zerolog.Level) - Required - The maximum log level allowed.
```

--------------------------------

### func RegisterWriter

Source: https://pkg.go.dev/go.mau.fi/zeroconfig

Registers a custom writer type and its associated compiler function.

```APIDOC
## func RegisterWriter(wt WriterType, compiler WriterCompiler)

### Description
Registers a new writer type with a specific compiler function for configuration processing.

### Parameters
- **wt** (WriterType) - Required - The identifier for the writer type.
- **compiler** (WriterCompiler) - Required - The function used to compile the writer configuration.
```
Tokens:
Raw