nxlog

README

NXLog Hook for Logrus

This Logrus hook allows sending logs to a NXLog server.

Configuration

The hook must be configured with:

• The protocol NXLog is using (tcp, udp, ssl or unixgram)
• The endpoint where NXLog is listening to:
  • As an "ip:port" or "hostname:port" string, in case of an IP protocol.
  • or as a valid path, in case of UDS.

Usage

After importing the logrus-nxlog-hook package, you can create a new hook with:

NewNxlogHook([PROTOCOL], [ENDPOINT], [OPTIONAL_TLS_CONFIGURATION])

For example, for a TCP setup:

package main

import (
  log "github.com/sirupsen/logrus"
  nxlog "github.com/affectv/logrus-nxlog-hook"
)

func main() {
  nxlogHook, err := nxlog.NewNxlogHook("tcp", "127.0.0.1:514", nil)
  if err == nil {
    log.AddHook(nxlogHook)
  }
  log.Info("Hello World")
}

See the Examples section for other setups.

Filtering by Level

This hook allows setting the minimum logging level which will trigger the forwarding of the messages.

You can specify it with Level.

e.g.

func main() {
  nxlogHook, _ := nxlog.NewNxlogHook("tcp", "127.0.0.1:514", nil)
  nxlogHook.Level = log.InfoLevel
  log.AddHook(nxlogHook)
  log.Info("Info message to be logged")
}

Specifying the Format

The default logging formatter is JSON, but you can change it as follows, using Formatter.

e.g.

func main() {
  nxlogHook, _ := nxlog.NewNxlogHook("tcp", "127.0.0.1:514", nil)
  nxlogHook.Formatter = &log.TextFormatter{}
  log.AddHook(nxlogHook)
  log.Info("Info message to be logged")
}

Examples

Some examples of how to use the plugin are the following:

TCP Connection

Specify tcp and a "host:port" string to NewNxlogHook.

e.g.

func main() {
  nxlogHook, _ := nxlog.NewNxlogHook("tcp", "127.0.0.1:514", nil)
  log.AddHook(nxlogHook)
  log.Info("TCP info message to be logged")
}

UDP Connection

Specify udp and a "host:port" string to NewNxlogHook.

func main() {
  nxlogHook, _ := nxlog.NewNxlogHook("udp", "127.0.0.1:514", nil)
  log.AddHook(nxlogHook)
  log.Info("UDP info message to be logged")
}

SSL Connection

Please remember you should have a compatible SSL certificate available to use. If you don't have it, you can create one with:

openssl req -newkey rsa:2048 -nodes -keyout sample-key.pem -x509 -days 365 -out sample-certificate.pem

You must ensure NXLog is configured to accept Connections via SSL as well. The SSL certificate files should be included in the following section of the nxlog.conf file:

<Input in_ssl>
    Module im_ssl
    Host 0.0.0.0
    Port 516
    CertFile	   %CERTSERVER%/sample-certificate.pem
    CertKeyFile	 %CERTSERVER%/sample-key.pem
    AllowUntrusted True
</Input>

Now you are ready to connect via SSL. Specify ssl and a "host:port" string to NewNxlogHook.

import (
	"crypto/tls"
	nxlog "github.com/affectv/logrus-nxlog-hook"
	"github.com/sirupsen/logrus"
)

func main() {
  certificate, _ := tls.LoadX509KeyPair(
		"%CERTCLIENT%/sample-certificate.pem",
		"%CERTCLIENT%/sample-key.pem",
	)
  nxlogHook, _ := nxlog.NewNxlogHook("ssl", "127.0.0.1:514", &tls.Config{
    InsecureSkipVerify: true,
    Certificates: []tls.Certificate{certificate},
  })
  log.AddHook(nxlogHook)
  log.Info("SSL info message to be logged")
}

UDS Connection

Specify unixgram and "path" string to NewNxlogHook.

func main() {
  nxlogHook, _ := nxlog.NewNxlogHook("unixgram", "/var/run/nxlog/devlog", nil)
  log.AddHook(nxlogHook)
  log.Info("UDS info message to be logged")
}

Plugin Development and Testing

This plugin was developed using ginkgo and gomega test frameworks.

To execute the tests:

ginkgo ./...

Documentation

Index

• type Hook
  • func NewNxlogHook(protocol string, endpoint string, options interface{}) (*Hook, error)
  • func (hook *Hook) Fire(entry *logrus.Entry) error
  • func (hook *Hook) Levels() []logrus.Level
• type Writer
  • func NewWriter(protocol string, endpoint string, settings interface{}) (*Writer, error)
  • func (w *Writer) Close()
  • func (w *Writer) Connect() error
  • func (w *Writer) Reconnect()
  • func (w *Writer) Write(message []byte, reconnect bool) (int, error)

Types

type Hook

type Hook struct {
	Level     logrus.Level
	Formatter logrus.Formatter
	// contains filtered or unexported fields
}

Hook to send logs to a service compatible with the NXlog API.

func NewNxlogHook

func NewNxlogHook(protocol string, endpoint string, options interface{}) (*Hook, error)

NewNxlogHook creates a hook to be added to an instance of logrus logger.

func (*Hook) Fire

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

Fire is triggered by a log event. The event might be altered by another hook.

func (*Hook) Levels

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

Levels returns the available logging levels.

type Writer

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

Writer represents a writer to NXLog

func NewWriter

func NewWriter(protocol string, endpoint string, settings interface{}) (*Writer, error)

NewWriter returns a reference to a new writer, with protocol, endpoint and settings populated. It also tries to connect to it and returns nil on success or error otherwise.

func (*Writer) Close

func (w *Writer) Close()

Close will close the current connection if possible.

func (*Writer) Connect

func (w *Writer) Connect() error

Connect with the protocol and endpoint specified in the writer.

func (*Writer) Reconnect

func (w *Writer) Reconnect()

Reconnect will close the connection and open it again.

func (*Writer) Write

func (w *Writer) Write(message []byte, reconnect bool) (int, error)

Write will send a message to the open connection of the writer. In case of error, it will try to reconnect once.