logfmt

package module
Version: v0.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 15, 2016 License: MIT Imports: 13 Imported by: 4

README

GoDoc Go Report Card TravisCI Coverage Status

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 releases via semver compatible Git tags prefixed with a single 'v'.

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

Examples

Constants

This section is empty.

Variables

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

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

View Source
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.

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

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

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

ErrUnsupportedValueType 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 Decoder

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

A Decoder reads and decodes logfmt records from an input stream.

Example
package main

import (
	"fmt"
	"strings"

	"github.com/go-logfmt/logfmt"
)

func main() {
	in := `
id=1 dur=1.001s
id=1 path=/path/to/file err="file not found"
`

	d := logfmt.NewDecoder(strings.NewReader(in))
	for d.ScanRecord() {
		for d.ScanKeyval() {
			fmt.Printf("k: %s v: %s\n", d.Key(), d.Value())
		}
		fmt.Println()
	}
	if d.Err() != nil {
		panic(d.Err())
	}

}
Output:

k: id v: 1
k: dur v: 1.001s

k: id v: 1
k: path v: /path/to/file
k: err v: file not found

func NewDecoder

func NewDecoder(r io.Reader) *Decoder

NewDecoder returns a new decoder that reads from r.

The decoder introduces its own buffering and may read data from r beyond the logfmt records requested.

func (*Decoder) Err

func (dec *Decoder) Err() error

Err returns the first non-EOF error that was encountered by the Scanner.

func (*Decoder) Key

func (dec *Decoder) Key() []byte

Key returns the most recent key found by a call to ScanKeyval. The returned slice may point to internal buffers and is only valid until the next call to ScanRecord. It does no allocation.

func (*Decoder) ScanKeyval

func (dec *Decoder) ScanKeyval() bool

ScanKeyval advances the Decoder to the next key/value pair of the current record, which can then be retrieved with the Key and Value methods. It returns false when decoding stops, either by reaching the end of the current record or an error.

func (*Decoder) ScanRecord

func (dec *Decoder) ScanRecord() bool

ScanRecord advances the Decoder to the next record, which can then be parsed with the ScanKeyval method. It returns false when decoding stops, either by reaching the end of the input or an error. After ScanRecord returns false, the Err method will return any error that occurred during decoding, except that if it was io.EOF, Err will return nil.

func (*Decoder) Value

func (dec *Decoder) Value() []byte

Value returns the most recent value found by a call to ScanKeyval. The returned slice may point to internal buffers and is only valid until the next call to ScanRecord. It does no allocation when the value has no escape sequences.

type Encoder

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

An Encoder writes logfmt data to an output stream.

Example
package main

import (
	"errors"
	"os"
	"time"

	"github.com/go-logfmt/logfmt"
)

func main() {
	check := func(err error) {
		if err != nil {
			panic(err)
		}
	}

	e := logfmt.NewEncoder(os.Stdout)

	check(e.EncodeKeyval("id", 1))
	check(e.EncodeKeyval("dur", time.Second+time.Millisecond))
	check(e.EndRecord())

	check(e.EncodeKeyval("id", 1))
	check(e.EncodeKeyval("path", "/path/to/file"))
	check(e.EncodeKeyval("err", errors.New("file not found")))
	check(e.EndRecord())

}
Output:

id=1 dur=1.001s
id=1 path=/path/to/file err="file not found"

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) EncodeKeyvals added in v0.2.0

func (enc *Encoder) EncodeKeyvals(keyvals ...interface{}) error

EncodeKeyvals writes the logfmt encoding of keyvals to the stream. Keyvals is a variadic sequence of alternating keys and values. Keys of unsupported type are skipped along with their corresponding value. Values of unsupported type or that cause a MarshalerError are replaced by their error but do not cause EncodeKeyvals to return an error. If a non-nil error is returned some key/value pairs may not have be written.

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
}

MarshalerError represents an error encountered while marshaling a value.

func (*MarshalerError) Error

func (e *MarshalerError) Error() string

type SyntaxError

type SyntaxError struct {
	Msg  string
	Line int
	Pos  int
}

A SyntaxError represents a syntax error in the logfmt input stream.

func (*SyntaxError) Error

func (e *SyntaxError) Error() string

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL