logfmt

README

logfmt

Package logfmt implements utilities to marshal and unmarshal data in the logfmt format. It provides an API similar to encoding/json and encoding/xml.

The logfmt format was first documented by Brandur Leach in this article. The format has not been formally standardized. The most authoritative public specification to date has been the documentation of a Go Language package written by Blake Mizerany and Keith Rarick.

Goals

This project attempts to conform as closely as possible to the prior art, while also removing ambiguity where necessary to provide well behaved encoder and decoder implementations.

Non-goals

This project does not attempt to formally standardize the logfmt format. In the event that logfmt is standardized this project would take conforming to the standard as a goal.

Versioning

Package logfmt publishes stable APIs via gopkg.in. The API is not yet stable, so the current version is v0, which is imported like so:

import "gopkg.in/logfmt.v0"

Documentation

Overview

Package logfmt implements utilities to marshal and unmarshal data in the logfmt format. The logfmt format records key/value pairs in a way that balances readability for humans and simplicity of computer parsing. It is most commonly used as a more human friendly alternative to JSON for structured logging.

Index

• Variables
• func MarshalKeyvals(keyvals ...interface{}) ([]byte, error)
• type Encoder
  • func NewEncoder(w io.Writer) *Encoder
  • func (enc *Encoder) EncodeKeyval(key, value interface{}) error
  • func (enc *Encoder) EndRecord() error
  • func (enc *Encoder) Reset()
• type MarshalerError
  • func (e *MarshalerError) Error() string

Variables

var ErrInvalidKey = errors.New("invalid key")

ErrInvalidKey is returned by Marshal functions and Encoder methods if a key contains an invalid character.

var ErrNilKey = errors.New("nil key")

ErrNilKey is returned by Marshal functions and Encoder methods if a key is a nil interface or pointer value.

var ErrUnsupportedKeyType = errors.New("unsupported key type")

ErrUnsupportedType is returned by Encoder methods if a key has an unsupported type.

var ErrUnsupportedValueType = errors.New("unsupported value type")

ErrUnsupportedType is returned by Encoder methods if a value has an unsupported type.

Functions

func MarshalKeyvals

func MarshalKeyvals(keyvals ...interface{}) ([]byte, error)

MarshalKeyvals returns the logfmt encoding of keyvals, a variadic sequence of alternating keys and values.

Types

type Encoder

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

An Encoder writes logfmt data to an output stream.

func NewEncoder

func NewEncoder(w io.Writer) *Encoder

NewEncoder returns a new encoder that writes to w.

func (*Encoder) EncodeKeyval

func (enc *Encoder) EncodeKeyval(key, value interface{}) error

EncodeKeyval writes the logfmt encoding of key and value to the stream. A single space is written before the second and subsequent keys in a record. Nothing is written if a non-nil error is returned.

func (*Encoder) EndRecord

func (enc *Encoder) EndRecord() error

EndRecord writes a newline character to the stream and resets the encoder to the beginning of a new record.

func (*Encoder) Reset

func (enc *Encoder) Reset()

Reset resets the encoder to the beginning of a new record.

type MarshalerError

type MarshalerError struct {
	Type reflect.Type
	Err  error
}

func (*MarshalerError) Error

func (e *MarshalerError) Error() string