graylog

README

Graylog Hook for Logrus   

Use this hook to send your logs to Graylog server over UDP. The hook is non-blocking: even if UDP is used to send messages, the extra work should not block the logging function.

All logrus fields will be sent as additional fields on Graylog.

Usage

The hook must be configured with:

• A Graylog GELF UDP address (a "ip:port" string).
• an optional hash with extra global fields. These fields will be included in all messages sent to Graylog

package main

import (
    "log/syslog"
    log "github.com/sirupsen/logrus"
    "gopkg.in/gemnasium/logrus-graylog-hook.v2"
    )

func main() {
    hook := graylog.NewGraylogHook("<graylog_ip>:<graylog_port>", map[string]interface{}{"this": "is logged every time"})
    log.AddHook(hook)
    log.Info("some logging message")
}

Asynchronous logger

package main

import (
    "log/syslog"
    log "github.com/sirupsen/logrus"
    "gopkg.in/gemnasium/logrus-graylog-hook.v2"
    )

func main() {
    hook := graylog.NewAsyncGraylogHook("<graylog_ip>:<graylog_port>", map[string]interface{}{"this": "is logged every time"})
    defer hook.Flush()
    log.AddHook(hook)
    log.Info("some logging message")
}

Disable standard logging

For some reason, you may want to disable logging on stdout, and keep only the messages in Graylog (ie: a webserver inside a docker container). You can redirect stdout to /dev/null, or just not log anything by creating a NullFormatter implementing logrus.Formatter interface:

type NullFormatter struct {
}

// Don't spend time formatting logs
func (NullFormatter) Format(e *log.Entry) ([]byte, error) {
    return []byte{}, nil
}

And set this formatter as the new logging formatter:

log.Infof("Log messages are now sent to Graylog (udp://%s)", graylogAddr) // Give a hint why logs are empty
log.AddHook(graylog.NewGraylogHook(graylogAddr, "api", map[string]interface{}{})) // set graylogAddr accordingly
log.SetFormatter(new(NullFormatter)) // Don't send logs to stdout

Documentation

Index

• Constants
• Variables
• type CompressType
• type GraylogHook
  • func NewAsyncGraylogHook(addr string, extra map[string]interface{}) *GraylogHook
  • func NewGraylogHook(addr string, extra map[string]interface{}) *GraylogHook
  • func (hook *GraylogHook) AddIgnoreSuffix(suffix ...string)
  • func (hook *GraylogHook) Blacklist(b []string)
  • func (hook *GraylogHook) Fire(entry *logrus.Entry) error
  • func (hook *GraylogHook) Flush()
  • func (hook *GraylogHook) Levels() []logrus.Level
  • func (hook *GraylogHook) SetWriter(w *Writer) error
  • func (hook *GraylogHook) Writer() *Writer
• 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) Write(p []byte) (n int, err 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?

const StackTraceKey = "_stacktrace"

Variables

var BufSize uint = 8192

Set graylog.BufSize = <value> _before_ calling NewGraylogHook Once the buffer is full, logging will start blocking, waiting for slots to be available in the queue.

Types

type CompressType

type CompressType int

What compression type the writer should use when sending messages to the graylog2 server

const (
	CompressGzip CompressType = iota
	CompressZlib
	NoCompress
)

type GraylogHook

type GraylogHook struct {
	Extra map[string]interface{}
	Host  string
	Level logrus.Level
	// contains filtered or unexported fields
}

GraylogHook to send logs to a logging service compatible with the Graylog API and the GELF format.

func NewAsyncGraylogHook

func NewAsyncGraylogHook(addr string, extra map[string]interface{}) *GraylogHook

NewAsyncGraylogHook creates a hook to be added to an instance of logger. The hook created will be asynchronous, and it's the responsibility of the user to call the Flush method before exiting to empty the log queue.

func NewGraylogHook

func NewGraylogHook(addr string, extra map[string]interface{}) *GraylogHook

NewGraylogHook creates a hook to be added to an instance of logger.

func (*GraylogHook) AddIgnoreSuffix

func (hook *GraylogHook) AddIgnoreSuffix(suffix ...string)

AddIgnoreSuffix adds a file to the suffixes to ignore the call stack of this file

func (*GraylogHook) Blacklist

func (hook *GraylogHook) Blacklist(b []string)

Blacklist create a blacklist map to filter some message keys. This useful when you want your application to log extra fields locally but don't want graylog to store them.

func (*GraylogHook) Fire

func (hook *GraylogHook) Fire(entry *logrus.Entry) error

Fire is called when a log event is fired. We assume the entry will be altered by another hook, otherwise we might logging something wrong to Graylog

func (*GraylogHook) Flush

func (hook *GraylogHook) Flush()

Flush waits for the log queue to be empty. This func is meant to be used when the hook was created with NewAsyncGraylogHook.

func (*GraylogHook) Levels

func (hook *GraylogHook) Levels() []logrus.Level

Levels returns the available logging levels.

func (*GraylogHook) SetWriter

func (hook *GraylogHook) SetWriter(w *Writer) error

SetWriter sets the hook Gelf Writer

func (*GraylogHook) Writer

func (hook *GraylogHook) Writer() *Writer

Writer returns the logger Gelf Writer

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)

func (*Message) UnmarshalJSON

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

type Reader

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

func NewReader

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

func (*Reader) Addr

func (r *Reader) Addr() string

func (*Reader) Read

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

FIXME: this will discard data if p isn't big enough to hold the full message.

func (*Reader) ReadMessage

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

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)

New 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) Write

func (w *Writer) Write(p []byte) (n int, err error)

Write encodes the given string in a GELF message and sends it to the server specified in New().

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.