lokirus

README

Logrus + Loki = ❤️

A Loki hook for Logrus

Installation

go get github.com/yukitsune/lokirus

Usage

package main

func main() {

	// Configure the Loki hook
	opts := lokirus.NewLokiHookOptions().
		// Grafana doesn't have a "panic" level, but it does have a "critical" level
  // https://grafana.com/docs/grafana/latest/explore/logs-integration/
		WithLevelMap(lokirus.LevelMap{logrus.PanicLevel: "critical"}).
    WithFormatter(&logrus.JsonFormatter{})
		WithStaticLabels(lokirus.Labels{
			"app":         "example",
			"environment": "development",
		}).
		WithBasicAuth("admin", "secretpassword") // Optional

	hook := lokirus.NewLokiHookWithOpts(
		"http://localhost:3100",
		opts,
		logrus.InfoLevel,
		logrus.WarnLevel,
		logrus.ErrorLevel,
		logrus.FatalLevel)

	// Configure the logger
	logger := logrus.New()
	logger.AddHook(hook)

	// Log all the things!
  logger.WithField("fizz", "buzz").Warnln("warning")
}

Contributing

Contributions are what make the open source community such an amazing place to be, learn, inspire, and create. Any contributions you make are greatly appreciated!

Documentation

Index

• type BasicAuthCredentials
• type DynamicLabelProviderFunc
• type Labels
• type LevelMap
• type LokiHook
  • func NewLokiHook(host string, levels ...logrus.Level) *LokiHook
  • func NewLokiHookWithOpts(host string, opts LokiHookOptions, levels ...logrus.Level) *LokiHook
  • func (hook *LokiHook) Fire(entry *logrus.Entry) error
  • func (hook *LokiHook) Levels() []logrus.Level
• type LokiHookOptions
  • func NewLokiHookOptions() LokiHookOptions

Types

type BasicAuthCredentials

type BasicAuthCredentials struct {
	Username string
	Password string
}

BasicAuthCredentials is a structure that holds a username and a password. to be used for HTTP queries.

type DynamicLabelProviderFunc

type DynamicLabelProviderFunc func(entry *logrus.Entry) Labels

DynamicLabelProviderFunc defines the func for providing custom dynamic labels https://grafana.com/docs/loki/latest/best-practices/#use-dynamic-labels-sparingly

type Labels

type Labels map[string]string

Labels defines a set of key-value pairs

type LevelMap

type LevelMap map[logrus.Level]string

LevelMap defines a map between a logrus.Level and a custom level value

type LokiHook

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

LokiHook sends logs to Loki via HTTP.

func NewLokiHook

func NewLokiHook(host string, levels ...logrus.Level) *LokiHook

NewLokiHook creates a Loki hook for logrus if no levels are provided, then logrus.AllLevels is used

func NewLokiHookWithOpts

func NewLokiHookWithOpts(host string, opts LokiHookOptions, levels ...logrus.Level) *LokiHook

NewLokiHookWithOpts creates a Loki hook for logrus with the specified LokiHookOptions if no levels are provided, then logrus.AllLevels is used

func (*LokiHook) Fire

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

Fire sends a log entry to Loki

func (*LokiHook) Levels

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

Levels returns the levels for which Fire will be called

type LokiHookOptions

type LokiHookOptions interface {

	// LevelMap returns the map of logrus.Levels and custom log level values
	LevelMap() LevelMap

	// StaticLabels returns the static labels added to the loki log stream
	StaticLabels() Labels

	// DynamicLabelProvider returns the DynamicLabelProviderFunc used to populate a log entry with dynamic labels
	DynamicLabelProvider() DynamicLabelProviderFunc

	// HttpClient returns the http.Client to be used for pushing logs to loki
	HttpClient() *http.Client

	// Formatter returns the logrus.Formatter to be used when writing log entries
	Formatter() logrus.Formatter

	// BasicAuth returns the basic authentication credentials to be used
	// when connecting to Loki.
	// nil means that no credentials should be used.
	BasicAuth() *BasicAuthCredentials

	// WithLevelMap allows for logrus.Levels to be re-mapped to a different label value
	WithLevelMap(LevelMap) LokiHookOptions

	// WithStaticLabels allow for multiple static labels to be added to the loki log stream
	// These should be preferred over dynamic labels:
	// https://grafana.com/docs/loki/latest/best-practices/#static-labels-are-good
	WithStaticLabels(Labels) LokiHookOptions

	// WithDynamicLabelProvider allows for dynamic labels to be added to log entries
	// Dynamic labels should be used sparingly:
	// https://grafana.com/docs/loki/latest/best-practices/#use-dynamic-labels-sparingly
	WithDynamicLabelProvider(DynamicLabelProviderFunc) LokiHookOptions

	// WithHttpClient allows for a custom http.Client to be used for pushing logs to loki
	// By default, the http.DefaultClient will be used
	WithHttpClient(*http.Client) LokiHookOptions

	// WithFormatter allows for a custom logrus.Formatter to be used when writing log entries
	// By default, the logrus.TextFormatter will be used
	WithFormatter(logrus.Formatter) LokiHookOptions

	// WithBasicAuth allows to set a username and password to use when writing to the remote Loki host.
	WithBasicAuth(username, password string) LokiHookOptions
}

LokiHookOptions allows for the behaviour of the LokiHook to be customised

func NewLokiHookOptions

func NewLokiHookOptions() LokiHookOptions