stdr

README

Minimal Go logging using logr and Go's standard library

This package implements the logr interface in terms of Go's standard log package(https://pkg.go.dev/log).

Documentation

Overview

Package stdr implements github.com/go-logr/logr.Logger in terms of Go's standard log package.

Index

• func New(std StdLogger) logr.Logger
• func NewWithOptions(std StdLogger, opts Options) logr.Logger
• func SetVerbosity(v int) int
• type MessageClass
• type Options
• type StdLogger
• type Underlier

Examples

• New
• New (WithName)
• NewWithOptions

Functions

func New

func New(std StdLogger) logr.Logger

New returns a logr.Logger which is implemented by Go's standard log package, or something like it. If std is nil, this will use a default logger instead.

Example: stdr.New(log.New(os.Stderr, "", log.LstdFlags|log.Lshortfile)))

Example

package main

import (
	"errors"
	"log"
	"os"

	"github.com/go-logr/stdr"
)

var errSome = errors.New("some error")

func newStdLogger(flags int) stdr.StdLogger {
	return log.New(os.Stdout, "", flags)
}

func main() {
	log := stdr.New(newStdLogger(log.Lshortfile))
	log.Info("info message with default options")
	log.Error(errSome, "error message with default options")
	log.Info("invalid key", 42, "answer")
	log.Info("missing value", "answer")
}

Output:

example_test.go:35: "level"=0 "msg"="info message with default options"
example_test.go:36: "msg"="error message with default options" "error"="some error"
example_test.go:37: "level"=0 "msg"="invalid key" "<non-string-key: 42>"="answer"
example_test.go:38: "level"=0 "msg"="missing value" "answer"="<no-value>"

Example (WithName)

package main

import (
	"log"
	"os"

	"github.com/go-logr/stdr"
)

func newStdLogger(flags int) stdr.StdLogger {
	return log.New(os.Stdout, "", flags)
}

func main() {
	log := stdr.New(newStdLogger(0))
	log.WithName("hello").WithName("world").Info("thanks for the fish")
}

Output:

hello/world: "level"=0 "msg"="thanks for the fish"

func NewWithOptions

func NewWithOptions(std StdLogger, opts Options) logr.Logger

NewWithOptions returns a logr.Logger which is implemented by Go's standard log package, or something like it. See New for details.

Example

package main

import (
	"log"
	"os"

	"github.com/go-logr/stdr"
)

func newStdLogger(flags int) stdr.StdLogger {
	return log.New(os.Stdout, "", flags)
}

func main() {
	log := stdr.NewWithOptions(newStdLogger(0), stdr.Options{LogCaller: stdr.All})
	log.Info("with LogCaller=All")
}

Output:

"caller"={"file":"example_test.go","line":55} "level"=0 "msg"="with LogCaller=All"

func SetVerbosity

func SetVerbosity(v int) int

SetVerbosity sets the global level against which all info logs will be compared. If this is greater than or equal to the "V" of the logger, the message will be logged. A higher value here means more logs will be written. The previous verbosity value is returned. This is not concurrent-safe - callers must be sure to call it from only one goroutine.

Types

type MessageClass

type MessageClass int

MessageClass indicates which category or categories of messages to consider.

const (
	// None ignores all message classes.
	None MessageClass = iota
	// All considers all message classes.
	All
	// Info only considers info messages.
	Info
	// Error only considers error messages.
	Error
)

type Options

type Options struct {
	// Depth biases the assumed number of call frames to the "true" caller.
	// This is useful when the calling code calls a function which then calls
	// stdr (e.g. a logging shim to another API).  Values less than zero will
	// be treated as zero.
	Depth int

	// LogCaller tells stdr to add a "caller" key to some or all log lines.
	// Go's log package has options to log this natively, too.
	LogCaller MessageClass
}

Options carries parameters which influence the way logs are generated.

type StdLogger

type StdLogger interface {
	// Output is the same as log.Output and log.Logger.Output.
	Output(calldepth int, logline string) error
}

StdLogger is the subset of the Go stdlib log.Logger API that is needed for this adapter.

type Underlier

type Underlier interface {
	GetUnderlying() StdLogger
}

Underlier exposes access to the underlying logging implementation. Since callers only have a logr.Logger, they have to know which implementation is in use, so this interface is less of an abstraction and more of way to test type conversion.