gelf

README

Gelf Handler for log15

Adds the GELF format for Graylog-based logging to the log15 logging library. GELF can be udp+tcp based, and supports chunking with udp, thus avoiding reconnection- and performance issues.

Usage

create a Handler with:

 h,err:=gelf.Handler("myhost:12201")

Currently only udp is transport implemented. You can also use log15-config with the config package from this repo.

Duplicate keys

Currently log15 will append duplicate keys to the contect list. Gelf expects a map, therefore keys have to be unique. This implementation assures that only the last value is used for this key.

    l1:=log.New("foo","bar")
    l1.Info("a message","foo","baz")
    // Output: in GELF: msg: "a message", foo: "baz"

Limitations

• only supports udp with gzip compression.
• buffer size not adjustable

License

Released under the MIT License.

Documentation

Overview

Package gelf provides a Gelf Handler for log15 in order to enable logging to Graylog taken from https://gist.github.com/jmtuley/d4b09617967e59c58c3e and parts from https://github.com/gemnasium/logrus-hooks it has no external dependencies outside the std library and of course log15 the actual Handler still resides inside the log15 package; here we have the supporting functions

Index

• Constants
• Variables
• func Handler(address string) (log15.Handler, error)
• type CompressType
• type Message
  • func (m *Message) MarshalJSON() ([]byte, error)
  • func (m *Message) UnmarshalJSON(data []byte) error
• type Reader
  • func NewReader(addr string) (*Reader, error)
  • func (r *Reader) Addr() string
  • func (r *Reader) Read(p []byte) (int, error)
  • func (r *Reader) ReadMessage() (*Message, error)
• type Writer
  • func NewWriter(addr string) (*Writer, error)
  • func (w *Writer) WriteMessage(m *Message) (err error)

Constants

const (
	ChunkSize = 1420
)

Used to control GELF chunking. Should be less than (MTU - len(UDP header)).

TODO: generate dynamically using Path MTU Discovery?

Variables

var Must muster

Must encapsulates GelfHandler and panics if it returns an error.

Functions

func Handler

func Handler(address string) (log15.Handler, error)

Handler returns a handler that writes GELF messages to a service at gelfAddr. It is already wrapped in log15's CallerFileHandler and SyncHandler helpers. Its error is non-nil if there is a problem creating the GELF writer or determining our hostname. address is in the format host:port.

h,err:=gelf.GelfHandler("myhost:12201")

Types

type CompressType

type CompressType int

CompressType tells what compression type the writer should use when sending messages to the graylog2 server

const (
	// CompressGzip indicates gzip compression
	CompressGzip CompressType = iota
	// CompressZlib indicates zlib compression
	CompressZlib
)

type Message

type Message struct {
	Version  string                 `json:"version"`
	Host     string                 `json:"host"`
	Short    string                 `json:"short_message"`
	Full     string                 `json:"full_message"`
	TimeUnix float64                `json:"timestamp"`
	Level    int32                  `json:"level"`
	Facility string                 `json:"facility"`
	File     string                 `json:"file"`
	Line     int                    `json:"line"`
	Extra    map[string]interface{} `json:"-"`
}

Message represents the contents of the GELF message. It is gzipped before sending.

func (*Message) MarshalJSON

func (m *Message) MarshalJSON() ([]byte, error)

MarshalJSON marshals a message to json

func (*Message) UnmarshalJSON

func (m *Message) UnmarshalJSON(data []byte) error

UnmarshalJSON unmarshals a message from json

type Reader

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

Reader provides interanl structures for a Reader

func NewReader

func NewReader(addr string) (*Reader, error)

NewReader returns a reader listening to udp traffic at an address in the form "host:port". if port is 0, a new free address is taken. Retrieve it with Addr(). The reader is mainly intended for testing

func (*Reader) Addr

func (r *Reader) Addr() string

Addr returns the address a Reader is listening on.

func (*Reader) Read

func (r *Reader) Read(p []byte) (int, error)

Read reads date into a fixed size buffer. ATTN: this will discard data if p isn't big enough to hold the full message.

func (*Reader) ReadMessage

func (r *Reader) ReadMessage() (*Message, error)

ReadMessage reads a Message

type Writer

type Writer struct {
	Facility         string // defaults to current process name
	CompressionLevel int    // one of the consts from compress/flate
	CompressionType  CompressType
	// contains filtered or unexported fields
}

Writer implements io.Writer and is used to send both discrete messages to a graylog2 server, or data from a stream-oriented interface (like the functions in log).

func NewWriter

func NewWriter(addr string) (*Writer, error)

NewWriter returns a new GELF Writer. This writer can be used to send the output of the standard Go log functions to a central GELF server by passing it to log.SetOutput()

func (*Writer) WriteMessage

func (w *Writer) WriteMessage(m *Message) (err error)

WriteMessage sends the specified message to the GELF server specified in the call to New(). It assumes all the fields are filled out appropriately. In general, clients will want to use Write, rather than WriteMessage.