logrus_logstash

README

Logstash hook for logrus

Use this hook to send the logs to Logstash over both UDP and TCP.

Usage

package main

import (
        "github.com/Sirupsen/logrus"
        "github.com/bshuster-repo/logrus-logstash-hook"
)

func main() {
        log := logrus.New()
        hook, err := logrus_logstash.NewHook("tcp", "172.17.0.2:9999", "myappName")

        if err != nil {
                log.Fatal(err)
        }
        log.Hooks.Add(hook)
        ctx := log.WithFields(logrus.Fields{
          "method": "main",
        })
        ...
        ctx.Info("Hello World!")
}

This is how it will look like:

{
    "@timestamp" => "2016-02-29T16:57:23.000Z",
      "@version" => "1",
         "level" => "info",
       "message" => "Hello World!",
        "method" => "main",
          "host" => "172.17.0.1",
          "port" => 45199,
          "type" => "myappName"
}

Hook Fields

Fields can be added to the hook, which will always be in the log context. This can be done when creating the hook:

hook, err := logrus_logstash.NewHookWithFields("tcp", "172.17.0.2:9999", "myappName", logrus.Fields{
        "hostname":    os.Hostname(),
        "serviceName": "myServiceName",
})

Or afterwards:

hook.WithFields(logrus.Fields{
        "hostname":    os.Hostname(),
        "serviceName": "myServiceName",
})

This allows you to set up the hook so logging is available immediately, and add important fields as they become available.

Single fields can be added/updated using 'WithField':

hook.WithField("status", "running")

Field prefix

The hook allows you to send logging to logstash and also retain the default std output in text format. However to keep this console output readable some fields might need to be omitted from the default non-hooked log output. Each hook can be configured with a prefix used to identify fields which are only to be logged to the logstash connection. For example if you don't want to see the hostname and serviceName on each log line in the console output you can add a prefix:

hook, err := logrus_logstash.NewHookWithFields("tcp", "172.17.0.2:9999", "myappName", logrus.Fields{
        "_hostname":    os.Hostname(),
        "_serviceName": "myServiceName",
})
...
hook.WithPrefix("_")

There are also constructors available which allow you to specify the prefix from the start. The std-out will not have the '_hostname' and '_servicename' fields, and the logstash output will, but the prefix will be dropped from the name.

Documentation

Index

• func WrapTLSClient(conn net.Conn, insecureSkipVerify bool) net.Conn
• type Hook
  • func NewFilterHook() *Hook
  • func NewFilterHookWithPrefix(prefix string) *Hook
  • func NewHook(protocol, address, appName string) (*Hook, error)
  • func NewHookWithConn(conn net.Conn, appName string) (*Hook, error)
  • func NewHookWithFields(protocol, address, appName string, alwaysSentFields logrus.Fields) (*Hook, error)
  • func NewHookWithFieldsAndConn(conn net.Conn, appName string, alwaysSentFields logrus.Fields) (*Hook, error)
  • func NewHookWithFieldsAndConnAndPrefix(conn net.Conn, appName string, alwaysSentFields logrus.Fields, prefix string) (*Hook, error)
  • func NewHookWithFieldsAndPrefix(protocol, address, appName string, alwaysSentFields logrus.Fields, ...) (*Hook, error)
  • func (h *Hook) Fire(entry *logrus.Entry) error
  • func (h *Hook) Levels() []logrus.Level
  • func (h *Hook) WithField(key string, value interface{})
  • func (h *Hook) WithFields(fields logrus.Fields)
  • func (h *Hook) WithPrefix(prefix string)
• type LogstashFormatter
  • func (f *LogstashFormatter) Format(entry *logrus.Entry) ([]byte, error)
  • func (f *LogstashFormatter) FormatWithPrefix(entry *logrus.Entry, prefix string) ([]byte, error)

Functions

func WrapTLSClient

func WrapTLSClient(conn net.Conn, insecureSkipVerify bool) net.Conn

wraps the existing connection in tls

Types

type Hook

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

Hook represents a connection to a Logstash instance

func NewFilterHook

func NewFilterHook() *Hook

NewFilterHook makes a new hook which does not forward to logstash, but simply enforces the prefix rules

func NewFilterHookWithPrefix

func NewFilterHookWithPrefix(prefix string) *Hook

NewFilterHookWithPrefix make a new hook which does not forward to logstash, but simply enforces the specified prefix

func NewHook

func NewHook(protocol, address, appName string) (*Hook, error)

NewHook creates a new hook to a Logstash instance, which listens on `protocol`://`address`.

func NewHookWithConn

func NewHookWithConn(conn net.Conn, appName string) (*Hook, error)

NewHookWithConn creates a new hook to a Logstash instance, using the supplied connection

func NewHookWithFields

func NewHookWithFields(protocol, address, appName string, alwaysSentFields logrus.Fields) (*Hook, error)

NewHookWithFields creates a new hook to a Logstash instance, which listens on `protocol`://`address`. alwaysSentFields will be sent with every log entry.

func NewHookWithFieldsAndConn

func NewHookWithFieldsAndConn(conn net.Conn, appName string, alwaysSentFields logrus.Fields) (*Hook, error)

NewHookWithFieldsAndConn creates a new hook to a Logstash instance using the supplied connection

func NewHookWithFieldsAndConnAndPrefix

func NewHookWithFieldsAndConnAndPrefix(conn net.Conn, appName string, alwaysSentFields logrus.Fields, prefix string) (*Hook, error)

NewHookWithFieldsAndConnAndPrefix creates a new hook to a Logstash instance using the suppolied connection and prefix

func NewHookWithFieldsAndPrefix

func NewHookWithFieldsAndPrefix(protocol, address, appName string, alwaysSentFields logrus.Fields, prefix string) (*Hook, error)

NewHookWithFieldsAndPrefix creates a new hook to a Logstash instance, which listens on `protocol`://`address`. alwaysSentFields will be sent with every log entry. prefix is used to select fields to filter

func (*Hook) Fire

func (h *Hook) Fire(entry *logrus.Entry) error

func (*Hook) Levels

func (h *Hook) Levels() []logrus.Level

func (*Hook) WithField

func (h *Hook) WithField(key string, value interface{})

func (*Hook) WithFields

func (h *Hook) WithFields(fields logrus.Fields)

func (*Hook) WithPrefix

func (h *Hook) WithPrefix(prefix string)

WithPrefix sets a prefix filter to use in all subsequent logging

type LogstashFormatter

type LogstashFormatter struct {
	Type string // if not empty use for logstash type field.

	// TimestampFormat sets the format used for timestamps.
	TimestampFormat string
}

Formatter generates json in logstash format. Logstash site: http://logstash.net/

func (*LogstashFormatter) Format

func (f *LogstashFormatter) Format(entry *logrus.Entry) ([]byte, error)

func (*LogstashFormatter) FormatWithPrefix

func (f *LogstashFormatter) FormatWithPrefix(entry *logrus.Entry, prefix string) ([]byte, error)