kv

README

kv

Package kv provides support for working with collections of key/value pairs.

• Lists
• Errors
• Context
• Parse
• Logging

Lists

The List type represents a sequence of alternating key/value pairs. Lists can render themselves as text in logfmt format, so if you like logging messages with key value pairs but are not ready to move away from the standard library log package you can use something like:

log.Println("this is a log message", kv.With(
    "key1", "value 1",
    "key2", 2,
))

// Output:
// this is a log message key1="value 1" key2=2

The output from the previous example can be easily read by humans, and easily parsed by machines. This makes it an excellent format for structured logging.

Errors

The Error type implements the builtin error interface and renders its error message as a free text message followed by key/value pairs:

cannot open file: permission denied file="/etc/passwd" user=alice

Errors are constructed with message text and key/value pairs.

// create an error
err := kv.NewError("permission denied").With("user", user)
log.Println(err)

// Output:
// permission denied user=alice

Errors can wrap other errors:

err = kv.Wrap(err, "cannot open file").With("file", filename)
log.Println(err)

// Output:
// cannot open file: permission denied file="/etc/passwd" user=alice

Context

Key/value pairs can be stored in the context:

ctx := context.Background()

// associate some key/value pairs with the context
ctx = kv.From(ctx).With("url", "/api/widgets", "method", "get")

// ... later on ...

log.Println("access denied", kv.From(ctx).With("file", filename))

// Output:
// access denied file="/etc/passwd" url="/api/widgets" method=get

Parse

One of the key points of structured logging is that logs are machine readable. The Parse function provides an easy way to read messages.

// read one line
line := []byte(`cannot open file: access denied file="/etc/passwd" user=alice`)

 text, list := kv.Parse(line)
 log.Println("text:", string(text))
 log.Println("list:", list)

// Output:
// text: cannot open file: access denied
// list: file="/etc/passwd" user=alice

Logging

The kvlog subdirectory contains a package that works well with the log package in the Go standard library. Its usage is as simple as:

func main() {
    kvlog.Attach() // attach to the standard logger
    log.Println("program started", kv.With("args", os.Args))
}

See the GoDoc for more details.

Documentation

Overview

Package kv provides support for working with collections of key/value pairs.

See https://github.com/jjeffery/kv for an overview of how to use this package, and why you might want to use it.

Index

• Variables
• func Log(args ...interface{})
• type Context
  • func From(ctx context.Context) Context
• type Error
  • func NewError(text string) Error
  • func Wrap(err error, text ...string) Error
• type List
  • func Parse(input []byte) (text []byte, list List)
  • func With(keyvals ...interface{}) List
  • func (l List) From(ctx context.Context) Context
  • func (l List) Keyvals() []interface{}
  • func (l List) Log(args ...interface{})
  • func (l List) MarshalText() (text []byte, err error)
  • func (l List) NewError(text string) Error
  • func (l List) String() string
  • func (l *List) UnmarshalText(text []byte) error
  • func (l List) With(keyvals ...interface{}) List
  • func (l List) Wrap(err error, text ...string) Error

Examples

• Context
• Error
• Log

Variables

var (
	// LogOutput is the function called to log a message.
	// The default value calls the Output function for the
	// standard logger in the Go standard liberary.
	LogOutput = log.Output
)

Functions

func Log

func Log(args ...interface{})

Log is used to log a message. By default the message is logged using the standard logger in the Go "log" package.

Example

package main

import (
	"context"

	"github.com/jjeffery/kv"
)

func main() {
	kv.Log("message 1")
	kv.Log("message 2", kv.With("a", 1))

	kv := kv.With("p", "q")

	kv.Log("message 3")
	kv.Log("message 4", kv.With("a", 1, "b", 2))

	ctx := kv.From(context.Background()).With("c1", 100, "c2", 200)

	kv.Log(ctx, "message 5")
	kv.Log("message 6:", ctx, "can be in any order")
	kv.Log(ctx, "message 7", kv.With("a", 1, "b", 2))

}

Output:

message 1
message 2 a=1
message 3 p=q
message 4 p=q a=1 b=2
message 5 p=q c1=100 c2=200
message 6: can be in any order p=q c1=100 c2=200
message 7 p=q a=1 b=2 c1=100 c2=200

Types

type Context

type Context interface {
	context.Context

	// With returns a new context based on the existing context,
	// but with with the key/value pairs attached.
	With(keyvals ...interface{}) context.Context

	// NewError returns a new error with the message text and
	// the key/value pairs from the context attached.
	NewError(text string) Error

	// Wrap returns an error that wraps the existing error with
	// the optional message text, and the key/value pairs from
	// the context attached.
	Wrap(err error, text ...string) Error
}

Context implements the context.Context interface, and can create a new context with key/value pairs attached to it.

Example

package main

import (
	"context"
	"fmt"

	"github.com/jjeffery/kv"
)

func main() {
	// start with a context
	ctx := context.Background()

	// attach some key/value pairs
	ctx = kv.From(ctx).With("method", "get", "url", "/api/widgets")

	// ... later on log a message ...

	fmt.Println("permission denied", kv.From(ctx).With("user", "alice"))

}

Output:

permission denied user=alice method=get url="/api/widgets"

func From

func From(ctx context.Context) Context

From creates a new context based on ctx. See the Context example.

type Error

type Error interface {
	error

	// With returns a new error based on this error
	// with the key/value pairs attached.
	With(keyvals ...interface{}) Error
}

Error implements the builtin error interface, and provides an additional method for attaching key/value pairs.

Example

package main

import (
	"fmt"

	"github.com/jjeffery/kv"
)

func main() {
	// setup the user
	user := "alice"

	// ... later on ...

	// create an error and log it
	err := kv.NewError("permission denied").With("user", user)
	fmt.Println(err)

	// alternatively, wrap an existing error
	err = kv.Wrap(err, "cannot open file").With("file", "/etc/passwd")
	fmt.Println(err)

}

Output:

permission denied user=alice
cannot open file: permission denied file="/etc/passwd" user=alice

func NewError

func NewError(text string) Error

NewError returns an error that formats as the given text.

func Wrap

func Wrap(err error, text ...string) Error

Wrap returns an error that wraps err, optionally annotating with the message text.

type List

type List []interface{}

List is a slice of alternating keys and values.

func Parse

func Parse(input []byte) (text []byte, list List)

Parse parses the input and reports the message text, and the list of key/value pairs.

The text slice, if non-nil, points to the same backing array as input.

func With

func With(keyvals ...interface{}) List

With returns a list populated with keyvals as the key/value pairs.

func (List) From

func (l List) From(ctx context.Context) Context

From returns a new context with key/value pairs copied both from the list and the context.

func (List) Keyvals

func (l List) Keyvals() []interface{}

Keyvals returns the list cast as []interface{}.

func (List) Log

func (l List) Log(args ...interface{})

Log is used to log a message. By default the message is logged using the standard logger in the Go "log" package.

func (List) MarshalText

func (l List) MarshalText() (text []byte, err error)

MarshalText implements the TextMarshaler interface.

func (List) NewError

func (l List) NewError(text string) Error

NewError returns an error with the given message and a list of key/value pairs copied from the list.

func (List) String

func (l List) String() string

String returns a string representation of the key/value pairs in logfmt format: "key1=value1 key2=value2 ...".

func (*List) UnmarshalText

func (l *List) UnmarshalText(text []byte) error

UnmarshalText implements the TextUnmarshaler interface.

func (List) With

func (l List) With(keyvals ...interface{}) List

With returns a new list with keyvals appended. The original list (l) is not modified.

func (List) Wrap

func (l List) Wrap(err error, text ...string) Error

Wrap wraps the error with the key/value pairs copied from the list, and the optional text.