logentrus

README

Logentrus | a Logentries hook for Logrus

Logrus created by Simon Eskildsen

Install

go get -u github.com/Sirupsen/logrus github.com/puddingfactory/logentrus

Setup

First, you should get a token for your logentries account, which you'll need to feed into your app somehow.

1. Log into your logentries account

• Navigate to create Add New Log
• Select Manual (specifically since we're using the Token-based approach)
• Set your values such as your Log Name and Log Set
• Receive your token!

I'd strongly recommend against storing the token directly in your source code. I personally use Environment Variables for testing purposes and have done so in the example provided below.

Usage

Just like with Logrus, it's best to define your options in init or in some early stage of your program.

package main

import (
	"os"

	"github.com/Sirupsen/logrus"
	"github.com/puddingfactory/logentrus"
)

func init() {
	logrus.SetLevel(logrus.InfoLevel)
	logrus.SetFormatter(&logrus.TextFormatter{}) // logentrus hook will always submit JSON to Logentries

	hook, err := logentrus.New(
		os.Getenv("LOGENTRIESTOKEN"), // grabbing Logentries Token from environment variable
		&logentrus.Opts{
			Priority:        logrus.InfoLevel, // since set to InfoLevel, DebugLevel is the only level that will be ignored
			TimestampFormat: "Jan 2 15:04:05", // setting empty string here will default to logrus's typically time format
			EncTLSConfig:    nil,              // setting config to nil means that conn will use root certs from local system
			UnencryptedTCP:  false,            // disable encryption, but still use TCP
			UnencryptedUDP:  false,            // disable encryption and use UDP
			UnencryptedPort: 514,              // omitting will result in port 514 usage; valid options are 80, 514, and 10000
		},
	)
	if err != nil {
		panic(err)
	}
	logrus.AddHook(hook)
}

func main() {
	logrus.Debug("This is a debug entry that should *not* show in logentries")
	logrus.Info("This is an info entry that should show up in logentries")
}

Features

Logentrus does its own formatting

Since Logentries prefers JSON formatting, I didn't want to require it to be set in Logrus. Instead, there is a separate logrus.JSONFormatter within this hook that processes the log entries for you automatically.

You have the option of setting the logrus.JSONFormatter.TimestampFormatter value when calling logentrus.New if there's a Timestamp format you prefer.

Support for various transmission types

As a safety-net, data is sent with encrypted (TLS) over TCP by default.

But for those sitautions where you know that you'll only be transmitting non-sensitive data, then switching away from the default to an unencrypted TCP or UDP connection may have a noticable impact on the speed of our program - particularly if it's log-heavy.

hook, err := logentrus.New(
	logentriesToken,
	&logentrus.Opts{
		UnencryptedTCP:  true,  // disable encryption, but still use TCP
		UnencryptedUDP:  false, // disable encryption and use UDP
		UnencryptedPort: 514,   // omitting will result in port 514 usage; valid options are 80, 514, and 10000
	},
)

You can provide your own set of root certs when using NewEncryptedHook

This is a feature of Google's crypto/tls package that you can apply to logentrus.

1. First you'll want to create a tls.Config by following this example.

• After that, you can drop your tls.Config into logentrus.New.

hook, err := logentrus.New(
	logentriesToken,
	&logentrus.Opts{
		EncTLSConfig: theConfig, // setting config to nil means that conn will use root certs already set up on local system
	},
)

Documentation

Overview

Package logentrus acts as a Logentries (https://logentries.com) hook for Logrus (https://github.com/Sirupsen/logrus)

Index

• type Hook
  • func New(token string, options *Opts) (hook *Hook, err error)
  • func (hook *Hook) Fire(entry *logrus.Entry) (err error)
  • func (hook *Hook) Levels() []logrus.Level
• type Opts

Types

type Hook

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

Hook used to send logs to logentries

func New

func New(token string, options *Opts) (hook *Hook, err error)

New creates and returns a Logrus hook for Logentries Token-based logging ref: https://docs.logentries.com/docs/input-token

func (*Hook) Fire

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

Fire formats and sends JSON entry to Logentries service

func (*Hook) Levels

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

Levels returns the log levels supported by this hook

type Opts

type Opts struct {
	Priority        logrus.Level // defaults to logrus.DebugLevel (include all)
	TimestampFormat string       // defaults to logrus's typical timestamp format
	EncTLSConfig    *tls.Config  // defaults to use system's cert store; provide if you'd like to enforce your own root certs
	UnencryptedTCP  bool         // defaults to false (encryption enabled, using TCP)
	UnencryptedUDP  bool         // defaults to false (encryption enabled, using TCP)
	UnencryptedPort int          // defaults to 80; available ports are 80, 514, and 10000
}

Opts is a set of optional parameters for NewEncrytpedHook