log

Documentation

Overview

Package log provides structured logging

Index

• Constants
• Variables
• func Error(err error, msg string, keysAndValues ...interface{})
• func GetLogger() logr.Logger
• func Info(msg string, keysAndValues ...interface{})
• func Init(component string, keyValuePairs ...interface{})
• func InitWithOptions(component string, opts []Option, keyValuePairs ...interface{})
• func MustInit(component string, keyValuePairs ...interface{})
• func MustInitWithOptions(component string, opts []Option, keyValuePairs ...interface{})
• func SetLogLevel(v int)
• func SetOutput(w io.Writer) error
• func UseLogger(l logr.Logger)
• func V(level int) logr.Logger
• func WithName(name string) logr.Logger
• func WithValues(keysAndValues ...interface{}) logr.Logger
• type Encoder
• type JSONEncoder
  • func (j JSONEncoder) Encode(w io.Writer, entry interface{}) error
• type Line
  • func (l Line) MarshalJSON() ([]byte, error)
• type LineJSON
• type LineJSONDev
• type Logger
  • func NewLogger(name string, w io.Writer, v Verbosity, e Encoder, keysAndValues ...interface{}) *Logger
  • func (l *Logger) Enabled() bool
  • func (l *Logger) Error(err error, msg string, keysAndValues ...interface{})
  • func (l *Logger) Info(msg string, keysAndValues ...interface{})
  • func (l *Logger) SetOutput(w io.Writer)
  • func (l *Logger) V(v int) logr.Logger
  • func (l *Logger) WithName(name string) logr.Logger
  • func (l *Logger) WithValues(keysAndValues ...interface{}) logr.Logger
• type Option
  • func WithLogLevel(v int) Option
  • func WithOutput(w io.Writer) Option
• type Verbosity
  • func (v Verbosity) MarshalJSON() ([]byte, error)
  • func (v Verbosity) String() string

Constants

const (
	TimeStampKey = "_ts"
	FileLineKey  = "_file:line"
	LevelKey     = "_level"
	ComponentKey = "_component"
	MessageKey   = "_message"
	ErrorKey     = "_error"
)

Keys used to log specific builtin fields

Variables

var ErrUnknownLoggerType = kverrors.New("unknown error type")

ErrUnknownLoggerType is returned when trying to perform a *Logger only function that is incompatible with logr.Logger interface

var TimestampFunc = func() string {
	return time.Now().UTC().Format(time.RFC3339Nano)
}

TimestampFunc returns a string formatted version of the current time. This should probably only be used with tests or if you want to change the default time formatting of the output logs.

Functions

func Error

func Error(err error, msg string, keysAndValues ...interface{})

Error logs an error, with the given message and key/value pairs as context. It functions similarly to calling Info with the "error" named value, but may have unique behavior, and should be preferred for logging errors (see the package documentations for more information).

The msg field should be used to add context to any underlying error, while the err field should be used to attach the actual error that triggered this log line, if present.

func GetLogger

func GetLogger() logr.Logger

GetLogger returns the root logger used for logging

func Info

func Info(msg string, keysAndValues ...interface{})

Info logs a non-error message with the given key/value pairs as context.

The msg argument should be used to add some constant description to the log line. The key/value pairs can then be used to add additional variable information. The key/value pairs should alternate string keys and arbitrary values.

func Init

func Init(component string, keyValuePairs ...interface{})

Init initializes the logger. This is required to use logging correctly component is the name of the component being used to log messages. Typically this is your application name.

keyValuePairs are key/value pairs to be used with all logs in the future

func InitWithOptions

func InitWithOptions(component string, opts []Option, keyValuePairs ...interface{})

InitWithOptions inits the logger with the provided opts

func MustInit

func MustInit(component string, keyValuePairs ...interface{})

MustInit calls Init and panics if it returns an error

func MustInitWithOptions

func MustInitWithOptions(component string, opts []Option, keyValuePairs ...interface{})

MustInitWithOptions calls InitWithOptions and panics if an error is returned

func SetLogLevel

func SetLogLevel(v int)

SetLogLevel sets the output verbosity

func SetOutput

func SetOutput(w io.Writer) error

SetOutput sets the logger output to w if the root logger is *log.Logger otherwise it returns ErrUnknownLoggerType

func UseLogger

func UseLogger(l logr.Logger)

UseLogger bypasses the requirement for Init and sets the logger to l

func V

func V(level int) logr.Logger

V returns an Logger value for a specific verbosity level, relative to this Logger. In other words, V values are additive. V higher verbosity level means a log message is less important. V(level uint8) Logger

func WithName

func WithName(name string) logr.Logger

WithName adds a new element to the logger's name. Successive calls with WithName continue to append suffixes to the logger's name. It's strongly recommended that name segments contain only letters, digits, and hyphens (see the package documentation for more information).

func WithValues

func WithValues(keysAndValues ...interface{}) logr.Logger

WithValues adds some key-value pairs of context to a logger. See Info for documentation on how key/value pairs work.

Types

type Encoder

type Encoder interface {
	Encode(w io.Writer, entry interface{}) error
}

Encoder encodes messages

type JSONEncoder

type JSONEncoder struct{}

JSONEncoder encodes messages as JSON

func (JSONEncoder) Encode

func (j JSONEncoder) Encode(w io.Writer, entry interface{}) error

Encode encodes the message as JSON to w

type Line

type Line struct {
	Timestamp string
	FileLine  string
	Verbosity string
	Component string
	Message   string
	Context   map[string]interface{}
}

Line orders log line fields

func (Line) MarshalJSON

func (l Line) MarshalJSON() ([]byte, error)

MarshalJSON implements custom marshaling for log line: (1) flattening context (2) support for developer mode

type LineJSON

type LineJSON struct {
	Timestamp string                 `json:"_ts"`
	FileLine  string                 `json:"-"`
	Verbosity string                 `json:"_level"`
	Component string                 `json:"_component"`
	Message   string                 `json:"_message"`
	Context   map[string]interface{} `json:"-"`
}

LineJSON add json tags to Line struct (production logs)

type LineJSONDev

type LineJSONDev struct {
	Timestamp string                 `json:"_ts"`
	FileLine  string                 `json:"_file:line"`
	Verbosity string                 `json:"_level"`
	Component string                 `json:"_component"`
	Message   string                 `json:"_message"`
	Context   map[string]interface{} `json:"-"`
}

LineJSONDev add json tags to Line struct (developer logs, enable using environment variable LOG_DEV)

type Logger

type Logger struct {
	// contains filtered or unexported fields
}

Logger writes logs to a specified output

func NewLogger

func NewLogger(name string, w io.Writer, v Verbosity, e Encoder, keysAndValues ...interface{}) *Logger

NewLogger creates a new logger

func (*Logger) Enabled

func (l *Logger) Enabled() bool

Enabled tests whether this Logger is enabled. For example, commandline flags might be used to set the logging verbosity and disable some info logs.

func (*Logger) Error

func (l *Logger) Error(err error, msg string, keysAndValues ...interface{})

Error logs an error, with the given message and key/value pairs as context. It functions similarly to calling Info with the "error" named value, but may have unique behavior, and should be preferred for logging errors (see the package documentations for more information).

The msg field should be used to add context to any underlying error, while the err field should be used to attach the actual error that triggered this log line, if present.

func (*Logger) Info

func (l *Logger) Info(msg string, keysAndValues ...interface{})

Info logs a non-error message with the given key/value pairs as context.

The msg argument should be used to add some constant description to the log line. The key/value pairs can then be used to add additional variable information. The key/value pairs should alternate string keys and arbitrary values.

func (*Logger) SetOutput

func (l *Logger) SetOutput(w io.Writer)

SetOutput sets the writer that JSON is written to

func (*Logger) V

func (l *Logger) V(v int) logr.Logger

V returns an Logger value for a specific verbosity level, relative to this Logger. In other words, V values are additive. V higher verbosity level means a log message is less important. It's illegal to pass a log level less than zero.

func (*Logger) WithName

func (l *Logger) WithName(name string) logr.Logger

WithName adds a new element to the logger's name. Successive calls with WithName continue to append suffixes to the logger's name. It's strongly recommended that name segments contain only letters, digits, and hyphens (see the package documentation for more information).

func (*Logger) WithValues

func (l *Logger) WithValues(keysAndValues ...interface{}) logr.Logger

WithValues clones the logger and appends keysAndValues

type Option

type Option func(*Logger)

Option is a configuration option

func WithLogLevel

func WithLogLevel(v int) Option

WithLogLevel sets the output log level and controls which verbosity logs are printed

func WithOutput

func WithOutput(w io.Writer) Option

WithOutput sets the output to w

type Verbosity

type Verbosity int

Verbosity is a level of verbosity to log between 0 and math.MaxInt32 However it is recommended to keep the numbers between 0 and 3

func (Verbosity) MarshalJSON

func (v Verbosity) MarshalJSON() ([]byte, error)

MarshalJSON marshals JSON

func (Verbosity) String

func (v Verbosity) String() string