consolejson

Documentation

Overview

Package consolejson is a concrete implementation of the logger.Sink and logger.Context used for outputting JSON-formatted log lines.

Its speed and memory footprint is what gains it its edge over the alternative consolepretty Sink, and is optimally combined with log interpreters such as Kibana.

Index

• Variables
• func New(conf Config) logger.Sink
• type Config
• type TimeFormat

Examples

• New
• TimeFormat

Variables

var Default = New(Config{})

Default is a logger Sink that outputs JSON-formatted logs to the console using its default settings.

Functions

func New

func New(conf Config) logger.Sink

New creates a new JSON-console logging Sink.

Example

package main

import (
	"github.com/iver-wharf/wharf-core/v2/pkg/logger"
	"github.com/iver-wharf/wharf-core/v2/pkg/logger/consolejson"
)

func main() {
	defer logger.ClearOutputs()
	logger.AddOutput(logger.LevelDebug, consolejson.New(consolejson.Config{
		DisableDate:       true,
		DisableCallerLine: true,
	}))

	logger.New().Debug().Message("Sample message.")

}

Output:

{"level":"debug","caller":"consolejson/json_example_test.go","message":"Sample message."}

Types

type Config

type Config struct {
	// DisableDate removes the date field from the log when set to true.
	//
	// When set to false:
	// 	{"level":"info","date":"2006-01-02T15:04:05Z","caller":"example.go","line":20,"message":"Sample message."}
	// When set to true:
	// 	{"level":"info","caller":"example.go","line":20,"message":"Sample message."}
	DisableDate bool
	// DisableCaller removes the caller file name and line fields from the log
	// when set to true.
	//
	// When set to false:
	// 	{"level":"info","date":"2006-01-02T15:04:05Z","caller":"example.go","line":20,"message":"Sample message."}
	// When set to true:
	// 	{"level":"info","date":"2006-01-02T15:04:05Z","message":"Sample message."}
	DisableCaller bool
	// DisableCallerLine removes just the caller line field from the log
	// when set to true, but leaves the caller file name as-is.
	//
	// When set to false:
	// 	{"level":"info","caller":"example.go","line":20,"message":"Sample message."}
	// When set to true:
	// 	{"level":"info","caller":"example.go","message":"Sample message."}
	DisableCallerLine bool
	// CallerFileField sets the name of the JSON property used in the logs
	// caller file path. The value is automatically escaped.
	// Defaults to "caller".
	//
	// When set to "" (empty string):
	// 	{"level":"info","caller":"example.go","line":20,"message":"Sample message."}
	// When set to "foo":
	// 	{"level":"info","foo":"example.go","line":20,"message":"Sample message."}
	CallerFileField string
	// CallerLineField sets the name of the JSON property used in the logs
	// caller line number. The value is automatically escaped.
	// Defaults to "line".
	//
	// When set to "" (empty string):
	// 	{"level":"info","caller":"example.go","line":20,"message":"Sample message."}
	// When set to "foo":
	// 	{"level":"info","caller":"example.go","foo":20,"message":"Sample message."}
	CallerLineField string
	// ErrorField sets the name of the JSON property used in the logs error.
	// The value is automatically escaped.
	// Defaults to "error".
	//
	// When set to "" (empty string):
	// 	{"level":"info","message":"Sample message.","error":"strconv.Atoi: parsing \"bar\": invalid syntax"}
	// When set to "foo":
	// 	{"level":"info","message":"Sample message.","foo":"strconv.Atoi: parsing \"bar\": invalid syntax"}
	ErrorField string
	// LevelField sets the name of the JSON property used in the logs severity
	// level. The value is automatically escaped.
	// Defaults to "level".
	//
	// When set to "" (empty string):
	// 	{"level":"info","message":"Sample message."}
	// When set to "foo":
	// 	{"foo":"info","message":"Sample message."}
	LevelField string
	// MessageField sets the name of the JSON property used in the logs message.
	// The value is automatically escaped.
	// Defaults to "message".
	//
	// When set to "" (empty string):
	// 	{"level":"info","message":"Sample message."}
	// When set to "foo":
	// 	{"level":"info","foo":"Sample message."}
	MessageField string
	// ScopeField sets the name of the JSON property used in the logs scope.
	// The value is automatically escaped.
	// Defaults to "scope".
	//
	// When set to "" (empty string):
	// 	{"level":"info","scope":"GORM","message":"Sample message."}
	// When set to "foo":
	// 	{"level":"info","foo":"GORM","message":"Sample message."}
	ScopeField string
	// DateField sets the name of the JSON property used in the logs scope.
	// The value is automatically escaped.
	// Defaults to "date".
	//
	// When set to "" (empty string):
	// 	{"level":"info","date":"2006-01-02T15:04:05Z","message":"Sample message."}
	// When set to "foo":
	// 	{"level":"info","foo":"2006-01-02T15:04:05Z","message":"Sample message."}
	DateField string
	// TiemFormat defines how time.Time fields added via Event.WithTime is
	// rendered. Defaults to TimeRFC3339, which looks like so:
	// 	2006-01-02T15:04:05Z
	TimeFormat TimeFormat
	// TimeDurationUnit defines how time.Duration fields added via
	// Event.WithDuration is rendered. A value of time.Second will then show
	// the duration in whole seconds, whereas time.Minute will
	// show the duration in full minutes.
	//
	// Defaults to 0, which will show the time in nanoseconds.
	//
	// If not using floats for duration, then the values will be rounded down
	// to the nearest unit. Where adding a 30 seconds duration to the log Event
	// with a unit of time.Minute will result in the integer value 0.
	TimeDurationUnit time.Duration
	// TimeDurationUseFloat defines how time.Duration fields added via
	// Event.WithDuration is rendered.
	//
	// Usually combined with also specifying the time unit. Setting this to true
	// and the duration unit to time.Minute will result in showing a 30 seconds
	// duration as 0.5 instead of rounding down to the integer 0.
	//
	// When set to false (which is the default) the duration is formatted as an
	// integer.
	TimeDurationUseFloat bool
}

Config lets you gradually configure the output of the logger by disabling certain features or changing the format of certain field types.

type TimeFormat

type TimeFormat string

TimeFormat specifies the formatting used when logging time.Time values.

You may use a custom time format by casting a time-package compatible format into this type.

Example

package main

import (
	"time"

	"github.com/iver-wharf/wharf-core/v2/pkg/logger"
	"github.com/iver-wharf/wharf-core/v2/pkg/logger/consolejson"
)

func main() {
	defer logger.ClearOutputs()
	logger.AddOutput(logger.LevelDebug, consolejson.New(consolejson.Config{
		DisableDate:   true,
		DisableCaller: true,
		TimeFormat:    consolejson.TimeUnix,
	}))
	logger.AddOutput(logger.LevelDebug, consolejson.New(consolejson.Config{
		DisableDate:   true,
		DisableCaller: true,
		TimeFormat:    time.Kitchen, // any format string is supported
	}))

	t := time.Date(2006, 1, 2, 3, 4, 5, 0, time.UTC)
	logger.New().Debug().WithTime("sample", t).Message("Sample message.")

}

Output:

{"level":"debug","message":"Sample message.","sample":1136171045}
{"level":"debug","message":"Sample message.","sample":"3:04AM"}

const (
	// TimeRFC3339 will render a time.Time as a string with the format
	// 	2006-01-02T15:04:05Z07:00
	TimeRFC3339 TimeFormat = time.RFC3339
	// TimeUnix will render a time.Time as an integer of seconds since
	// January 1, 1970 UTC.
	TimeUnix TimeFormat = "wharf-core/Unix"
	// TimeUnixMs will render a time.Time as an integer of milliseconds since
	// January 1, 1970 UTC.
	TimeUnixMs TimeFormat = "wharf-core/UnixMs"
	// TimeUnixMicro will render a time.Time as an integer of microseconds since
	// January 1, 1970 UTC.
	TimeUnixMicro TimeFormat = "wharf-core/UnixMicro"
	// TimeUnixNano will render a time.Time as an integer of nanoseconds since
	// January 1, 1970 UTC.
	TimeUnixNano TimeFormat = "wharf-core/UnixNano"
)