logdna

README

LogDNA Logrus and Logrus Mate library

This library allows logging to LogDNA from Logrus, optionally configuring everything using Logrus Mate.

This library is not currently actively maintained.

Configuration

Check out the example/ subdirectory for a simple example.

You can create hook manually, New method or using Logrus Mate. For HOCON configuration provider (the default), add a hook like this:

your-logger {
    ...
    hooks {
        logdna {
            api-key = "your-ingestion-key-here"
            app = "myapp"
            json = true
        }
        ...
    }
    ...
}

The supported options are:

• api-key: ingestion key, mandatory
• hostname: hostname override, if not specified will use os.Hostname()
• mac: host MAC address, not sent if empty, no autodetection for now
• ip: host IP address, ditto
• app: app identifier, for LogDNA to filter
• env: environment identifier, for LogDNA to filter
• size: buffer size, in entries, defaults to 4096
• flush: flush interval, defaults to 10 seconds
• qsize: buffered channel size
• drop: whenever hook's allowed to drop messages (if buffer's full etc). Logging will block if this is false and there are size+qsize entries waiting to be sent.
• json: how to send structured log fields. Will format line as JSON if set to true (using "message" key for log message), or pass fields as meta if not.
• text-format: whenever to also include structured logging data in the message. Default to false, enabling will append key-value pairs to the message texts, so they'll be immediately visible.
• url allows to override the ignestion endpoint URL (e.g. for testing)

With New method and Config struct you have a little more flexibility, as you can specify any MessageFormatter rather than just text-format.

Limitations

As the logging is asynchronous, error handling is limited. If drop is set to true, you can lose messages on outages. If drop is false, program may panic at shutdown, or buffer size may grow past the size limit.

Also, to give the hooks chance flush before the program exits, don't forget to add defer logrus.Exit(0) to your main.

Suggestions (and pull requests) are welcomed.

Documentation

Index

• Constants
• func New(config Config) (logrus.Hook, error)
• func NewFromConfig(cfg config.Configuration) (logrus.Hook, error)
• type Config
  • func NewConfig(cfg config.Configuration) Config
• type Hook
  • func (hook *Hook) Close() error
  • func (hook *Hook) Fire(entry *logrus.Entry) error
  • func (hook *Hook) Flush() error
  • func (hook *Hook) Levels() []logrus.Level
• type SimpleTextFormatter
  • func (f *SimpleTextFormatter) Format(entry *logrus.Entry) ([]byte, error)

Constants

const DefaultIngestURL = "https://logs.logdna.com/logs/ingest"

DefaultIngestURL is the URL of the LogDNA ingestion API endpoint

Functions

func New

func New(config Config) (logrus.Hook, error)

New creates a new LogDNA hook from a given Config struct

func NewFromConfig

func NewFromConfig(cfg config.Configuration) (logrus.Hook, error)

NewFromConfig creates a new LogDNA hook from the Logrus Mate configuration

Types

type Config

type Config struct {
	IngestURL        string
	APIKey           string
	Hostname         string
	MAC              string
	IP               string
	App              string // NOTE: App and Env are global at the moment
	Env              string
	BufferSize       int
	QueueSize        int
	FlushEvery       time.Duration
	MayDrop          bool
	LineJSON         bool
	MessageFormatter logrus.Formatter

	// Instrumentation functions, called in a separate goroutine
	OnDrop  func(entries int)
	OnFlush func(entries int, err error)
}

Config is the configuration struct for LogDNAHook

func NewConfig

func NewConfig(cfg config.Configuration) Config

NewConfig creates a new LogDNA Config from the Logrus Mate configuration

type Hook

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

Hook is a Logrus hook that sends entries to LogDNA

func (*Hook) Close

func (hook *Hook) Close() error

Close stops the processing

func (*Hook) Fire

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

Fire queues the message for submission to LogDNA

func (*Hook) Flush

func (hook *Hook) Flush() error

Flush sends all the pending entries to the LogDNA ingestion API

func (*Hook) Levels

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

Levels returns a list of all supported log levels

type SimpleTextFormatter

type SimpleTextFormatter struct {
	DisableSorting   bool
	QuoteEmptyFields bool
}

SimpleTextFormatter is a simplified version of logrus.TextFormatter It only renders the message text followed with key-value pairs, no colors (and terminal detection) or timestamps.

func (*SimpleTextFormatter) Format

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

Format renders a single log entry