README

Go package for parsing (and, eventually, generating)
log lines in the logfmt style.

See http://godoc.org/github.com/kr/logfmt for format, and other documentation and examples.

Copyright (C) 2013 Keith Rarick, Blake Mizerany

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Expand ▾ Collapse ▴

Documentation

Overview

    Package implements the decoding of logfmt key-value pairs.

    Example logfmt message:

    foo=bar a=14 baz="hello kitty" cool%story=bro f %^asdf
    

    Example result in JSON:

    { "foo": "bar", "a": 14, "baz": "hello kitty", "cool%story": "bro", "f": true, "%^asdf": true }
    

    EBNFish:

    ident_byte = any byte greater than ' ', excluding '=' and '"'
    string_byte = any byte excluding '"' and '\'
    garbage = !ident_byte
    ident = ident_byte, { ident byte }
    key = ident
    value = ident | '"', { string_byte | '\', '"' }, '"'
    pair = key, '=', value | key, '=' | key
    message = { garbage, pair }, garbage
    
    Example (CustomHandler)
    Output:
    
    {a 1 ms}
    {b 10 }
    {c 100 MB}
    {d 1 s}
    

    Index

    Examples

    Constants

    This section is empty.

    Variables

    View Source
    var ErrUnterminatedString = errors.New("logfmt: unterminated string")

    Functions

    func Unmarshal

    func Unmarshal(data []byte, v interface{}) (err error)

      Unmarshal parses the logfmt encoding data and stores the result in the value pointed to by v. If v is an Handler, HandleLogfmt will be called for each key-value pair.

      If v is not a Handler, it will pass v to NewStructHandler and use the returned StructHandler for decoding.

      Types

      type Handler

      type Handler interface {
      	HandleLogfmt(key, val []byte) error
      }

        Handler is the interface implemented by objects that accept logfmt key-value pairs. HandleLogfmt must copy the logfmt data if it wishes to retain the data after returning.

        func NewStructHandler

        func NewStructHandler(v interface{}) (Handler, error)

        type HandlerFunc

        type HandlerFunc func(key, val []byte) error

          The HandlerFunc type is an adapter to allow the use of ordinary functions as logfmt handlers. If f is a function with the appropriate signature, HandlerFunc(f) is a Handler object that calls f.

          func (HandlerFunc) HandleLogfmt

          func (f HandlerFunc) HandleLogfmt(key, val []byte) error

          type InvalidUnmarshalError

          type InvalidUnmarshalError struct {
          	Type reflect.Type
          }

            An InvalidUnmarshalError describes an invalid argument passed to Unmarshal. (The argument to Unmarshal must be a non-nil pointer.)

            func (*InvalidUnmarshalError) Error

            func (e *InvalidUnmarshalError) Error() string

            type StructHandler

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

              StructHandler unmarshals logfmt into a struct. It matches incoming keys to the the struct's fields (either the struct field name or its tag, preferring an exact match but also accepting a case-insensitive match.

              Field types supported by StructHandler are:

              all numeric types (e.g. float32, int, etc.)
              []byte
              string
              bool - true if key is present, false otherwise (the value is ignored).
              time.Duration - uses time.ParseDuration
              

              If a field is a pointer to an above type, and a matching key is not present in the logfmt data, the pointer will be untouched.

              If v is not a pointer to an Handler or struct, Unmarshal will return an error.

              func (*StructHandler) HandleLogfmt

              func (h *StructHandler) HandleLogfmt(key, val []byte) error

              type UnmarshalTypeError

              type UnmarshalTypeError struct {
              	Value string       // the logfmt value
              	Type  reflect.Type // type of Go value it could not be assigned to
              }

                An UnmarshalTypeError describes a logfmt value that was not appropriate for a value of a specific Go type.

                func (*UnmarshalTypeError) Error

                func (e *UnmarshalTypeError) Error() string