log

README

Simple logging overlay for Arcalot

This is a very simple API abstracting away other logging libraries, such as Go log and the Go test logger. You can use it by running:

go get go.arcalot.io/log

Why create a custom logging library?

Why create a custom logging library, when there are a ton of them already out there?

The answer is simple: to create a clean API we can rely on. Even the log and testing packages in Go don't implement a common API for logging, not to mention the myriad libraries out there. We don't proscribe what library an application should use, but we do wish to standardize how we communicate with these libraries.

Should I use this library for my project?

You can! However, keep in mind, this library is intended for Arcalot, and especially the Arcaflow use case. Features that are not needed here will not be added.

You can always use this library on an as-is basis if you are happy with the feature set and we won't be breaking backwards compatibility in minor versions, but if we need a major change, we may move on from the current API in the next major version.

Using the logger

The easiest way to create a logger is to use the Config struct:

package yourapplication

import "go.arcalot.io/log"

func main() {
    logConfig := log.Config{
        Level: log.LevelInfo,
        Destination: log.DestinationStdout,
        Stdout: os.Stdout,
    }
    logger := log.New(logConfig)
    logger.Infof("Hello world!")
}

You should now see a log message on your console. If you wish to log from a test utility, you can do so like this:

package yourapplication_test

import "go.arcalot.io/log"

func TestSomething(t *testing.T) {
    logConfig := log.Config{
        Level: log.LevelInfo,
        Destination: log.DestinationTest,
        T: t,
    }
    logger := log.New(logConfig)
    logger.Infof("Hello world!")
}

You can also apply labels to the log messages. This will add metadata to your log messages. Extending the previous example:

package yourapplication_test

import "go.arcalot.io/log"

func TestSomething(t *testing.T) {
    logConfig := log.Config{
        Level: log.LevelInfo,
        Destination: log.DestinationTest,
        T: t,
    }
    logger := log.New(logConfig)
    logger = logger.WithLabel("source", "mytest")
    logger.Infof("Hello world!")
}

For a more detailed explanation please see our documentation.

Documentation

Index

• type BufferWriter
  • func NewBufferWriter() BufferWriter
• type Config
  • func (c Config) Validate() error
• type Destination
  • func (d Destination) Validate() error
• type Labels
  • func (l Labels) String() string
• type Level
  • func (l Level) ShouldPrint(messageLevel Level) bool
  • func (l Level) Validate() error
• type Logger
  • func New(config Config) Logger
  • func NewGoLogger(minimumLevel Level, logger ...*goLog.Logger) Logger
  • func NewLogger(minLevel Level, writer Writer) Logger
  • func NewTestLogger(t *testing.T) Logger
• type Message
  • func (m Message) String() string
• type Writer
  • func NewGoLogWriter(logger ...*log.Logger) Writer
  • func NewNOOPLogger() Writer
  • func NewTestWriter(t *testing.T) Writer

Types

type BufferWriter

type BufferWriter interface {
	Writer

	// String returns all recorded logs.
	String() string
}

BufferWriter provides a writer that records all log messages. This logger is most useful for tests.

func NewBufferWriter

func NewBufferWriter() BufferWriter

type Config

type Config struct {
	// Level sets the minimum log level for the logger.
	Level Level `json:"level"`

	// Destination is the place the logger writes to.
	Destination Destination `json:"destination"`

	// T is the Go test for logging purposes.
	T *testing.T `json:"-" yaml:"-"`

	// Stdout is the standard output used by the DestinationStdout destination. If not set, os.Stdout is used.
	Stdout io.Writer `json:"-" yaml:"-"`
}

Config is the configuration for the logger.

func (Config) Validate

func (c Config) Validate() error

type Destination

type Destination string

Destination is the place a LogWriter writes to.

const (
	// DestinationStdout writes to the standard output.
	DestinationStdout Destination = "stdout"
	// DestinationTest writes the logs to the *testing.T facility.
	DestinationTest Destination = "test"
)

func (Destination) Validate

func (d Destination) Validate() error

type Labels

type Labels map[string]string

Labels are applied to a message to indicate where they are coming from or other relevant data.

func (Labels) String

func (l Labels) String() string

type Level

type Level string

Level is the logging level.

const (
	// LevelDebug logs for debugging purposes. These logs are likely to contain excessive amounts of information.
	LevelDebug Level = "debug"
	// LevelInfo logs informational messages.
	LevelInfo Level = "info"
	// LevelWarning logs warning messages.
	LevelWarning Level = "warning"
	// LevelError logs error messages.
	LevelError Level = "error"
)

func (Level) ShouldPrint

func (l Level) ShouldPrint(messageLevel Level) bool

ShouldPrint returns true if the a message at messageLevel should be printed if l is the current minimum level.

func (Level) Validate

func (l Level) Validate() error

type Logger

type Logger interface {
	Debugf(format string, args ...interface{})
	Infof(format string, args ...interface{})
	Warningf(format string, args ...interface{})
	Errorf(format string, args ...interface{})

	// WithLabel creates a child logger with this label attached.
	WithLabel(name string, value string) Logger
}

Logger provides pluggable logging for Arcalot.

func New

func New(config Config) Logger

func NewGoLogger

func NewGoLogger(minimumLevel Level, logger ...*goLog.Logger) Logger

NewGoLogger writes to the Go log facility. If no logger is passed, the standard logger is used.

func NewLogger

func NewLogger(minLevel Level, writer Writer) Logger

NewLogger creates a new logger with the specified minimum level and target writer.

func NewTestLogger

func NewTestLogger(t *testing.T) Logger

NewTestLogger creates a logger that writes to the Go test output.

type Message

type Message struct {
	Timestamp time.Time `json:"timestamp"`
	Level     Level     `json:"level"`
	Labels    Labels    `json:"labels"`
	Message   string    `json:"message"`
}

Message is a single log message.

func (Message) String

func (m Message) String() string

type Writer

type Writer interface {
	// Write writes a message to the output.
	Write(Message) error

	// Rotate gets called if logs need to be rotated.
	Rotate()

	io.Closer
}

Writer is an abstraction over the possible logging targets.

func NewGoLogWriter

func NewGoLogWriter(logger ...*log.Logger) Writer

NewGoLogWriter creates a log writer that writes to the Go log facility. The optional logger parameter can be used to pass one scoped logger, otherwise the global logger is used. If multiple loggers are passed the function will panic.

func NewNOOPLogger

func NewNOOPLogger() Writer

NewNOOPLogger returns a logger that does nothing.

func NewTestWriter

func NewTestWriter(t *testing.T) Writer

NewTestWriter returns a writer that logs via the Go test facility.