zord

README

zord

zord provides a writer for https://github.com/rs/zerolog that reorders the log event objects for better readability.

Example

package main

import (
	"os"
	"github.com/7fffffff/zord"
	"github.com/rs/zerolog"
)

func main() {
	var logger zerolog.Logger

	// using zerolog by itself
	logger = zerolog.New(os.Stderr).With().Timestamp().Str("service", "greeter").Logger()
	logger.Debug().Int("a", 1).Msg("hello, world!")
	// => {"level":"debug","service":"greeter","a":1,"time":"2006-01-02T15:04:05-07:00","message":"hello, world!"}

	// let's move some common fields to the front
	writer := zord.NewWriter()
	//writer.Wr = os.Stderr // default
	//writer.FirstKeys = zord.DefaultFirstKeys() // default
	logger = zerolog.New(writer).With().Timestamp().Str("service", "greeter").Logger()
	logger.Debug().Int("a", 1).Msg("hello, world!")
	// => {"time":"2006-01-02T15:04:05-07:00","level":"debug","message":"hello, world!","service":"greeter","a":1}

	// let's make "service" appear after "level"
	writer = zord.NewWriter()
	writer.FirstKeys = []string{
		zerolog.TimestampFieldName,
		zerolog.LevelFieldName,
		"service",
		zerolog.CallerFieldName,
		zerolog.MessageFieldName,
		zerolog.ErrorFieldName,
	}
	logger = zerolog.New(writer).With().Timestamp().Str("service", "greeter").Logger()
	logger.Debug().Int("a", 1).Msg("hello, world!")
	// => {"time":"2006-01-02T15:04:05-07:00","level":"debug","service":"greeter","message":"hello, world!","a":1}
}

Why?

In development, log lines are a little easier to read when common fields like the timestamp are always in the same place. JSON objects are defined as unordered sets of name/value pairs, so rearranging the pairs should not change how objects are interpreted by a downstream system.

In production scenarios where log output is only ever read by other programs, there's not much point in using zord.Writer.

Duplicate Keys

zerolog doesn't deduplicate keys and neither does zord.Writer. Duplicate keys will maintain their ordering relative to each other.

Binary Logs (CBOR)

If compiled with the binary_log build tag, zord.Writer won't inspect or modify the bytes it's given.

Efficiency

zord.Writer parses and reassembles the event object, so there's inevitably some overhead compared using just zerolog.

Logging an event with 10 fields
Using zerolog v1.5.0, the minimum version for this package
BenchmarkZerologDefault-12         1791386       659.0 ns/op      0 B/op      0 allocs/op
BenchmarkZerologConsoleWriter-12     85569     13859 ns/op     2457 B/op     88 allocs/op
BenchmarkZordWriter-12              333338      3575 ns/op     2120 B/op     24 allocs/op

License

Mozilla Public License 2.0: https://www.mozilla.org/MPL/2.0/

Documentation

Overview

Package zord provides a writer for github.com/rs/zerolog that reorders the log event objects for better readability.

Index

• func DefaultFirstKeys() []string
• type Writer
  • func NewWriter() *Writer
  • func (z Writer) Write(event []byte) (n int, err error)

Functions

func DefaultFirstKeys

func DefaultFirstKeys() []string

Types

type Writer

type Writer struct {
	Output    io.Writer // output writer
	FirstKeys []string  // keys to be moved to the beginning of event objects
}

Writer parses each Write for a JSON object and reorders the top level keys according to FirstKeys, before writing to Output. Writer does not deduplicate keys.

If the reordering process fails, Writer will write the log event as-is without signalling the parsing error.

If compiled with the binary_log build tag, Writer will not inspect or reorder the data written to it.

func NewWriter

func NewWriter() *Writer

NewWriter creates a new Writer. The default output writer is os.Stderr and the default list of keys is defined by DefaultFirstKeys()

func (Writer) Write

func (z Writer) Write(event []byte) (n int, err error)