discordrus

README

discordrus | a Discord hook for Logrus

Current version: v1.1.0

Install

go get -u github.com/kz/discordrus

Setup

In order to use this package, a Discord webhook URL is required. Find out how to obtain one here. You will need to be a server administrator to do this.

Usage

Below is an example of how this package may be used. The options below are used only for the purpose of demonstration and chances are that you will not need to use any options at all (or if any, only the Username option).

package main

import (
	"github.com/sirupsen/logrus"
	"os"
	"github.com/kz/discordrus"
)

func init() {
	logrus.SetFormatter(&logrus.TextFormatter{})
	logrus.SetOutput(os.Stderr)
	logrus.SetLevel(logrus.DebugLevel)

	logrus.AddHook(discordrus.NewHook(
		// Use environment variable for security reasons
		os.Getenv("DISCORDRUS_WEBHOOK_URL"),
		// Set minimum level to DebugLevel to receive all log entries
		logrus.DebugLevel,
		&discordrus.Opts{
			Username:           "Test Username",
			Author:             "",                         // Setting this to a non-empty string adds the author text to the message header
			DisableTimestamp:   false,                      // Setting this to true will disable timestamps from appearing in the footer
			TimestampFormat:    "Jan 2 15:04:05.00000 MST", // The timestamp takes this format; if it is unset, it will take logrus' default format
			TimestampLocale:    nil,                        // The timestamp uses this locale; if it is unset, it will use time.Local
			EnableCustomColors: true,                       // If set to true, the below CustomLevelColors will apply
			CustomLevelColors: &discordrus.LevelColors{
				Debug: 10170623,
				Info:  3581519,
				Warn:  14327864,
				Error: 13631488,
				Panic: 13631488,
				Fatal: 13631488,
			},
			DisableInlineFields: false, // If set to true, fields will not appear in columns ("inline")
		},
	))
}

func main() {
	logrus.WithFields(logrus.Fields{"String": "hi", "Integer": 2, "Boolean": false}).Debug("Check this out! Awesome, right?")
}

All discordrus.Opts fields are optional.

Option	Description	Default	Valid options
Username	Replaces the default username of the webhook bot for the sent message only	Username unchanged	Any non-empty string (2-32 chars. inclusive)
Author	Adds an author field to the header if set	Author not set	Any non-empty string (1-256 chars inclusive)
DisableInlineFields	Inline means whether Discord will display the field in a column (with maximum three columns to a row). Setting this to true will cause Discord to display the field in its own row.	false	bool
DisableTimestamp	Specifies whether the timestamp in the footer should be disabled	false	bool
TimestampFormat	Change the timestamp format	logrus's default time format	"Jan 2 15:04:05.00000 MST", or any format accepted by Golang
TimestampLocale	Change the timestamp locale	nil	nil == time.Local, time.UTC, time.LoadLocation("America/New_York"), etc
EnableCustomColors	Specifies whether the CustomLevelColors opt value should be used instead of discordrus.DefaultLevelColors. If true, CustomLevelColors must be specified (or all colors will be set to the nil value of 0, therefore displayed as white)	false	bool
CustomLevelColors	Replaces discordrus.DefaultLevelColors. All fields must be entered or they will default to the nil value of 0.	Pointer to struct instance of discordrus.LevelColors

In addition to the above character count constraints, Discord has a maximum of 25 fields with their name and value limits being 256 and 1024 respectively. Furthermore, the description (i.e., logrus' error message) must be a maximum of 2048. All of these constraints, including the option constraints above, will automatically be truncated with no further action required.

Acknowledgements

The following repositories have been helpful in creating this package: puddingfactory/logentrus for Logentries, johntdyer/slackrus for Slack and nubo/hiprus for Hipchat. Check them out!

Documentation

Index

• Variables
• func LevelThreshold(l logrus.Level) []logrus.Level
• type Hook
  • func NewHook(webhookURL string, minLevel logrus.Level, opts *Opts) *Hook
  • func (hook *Hook) Fire(entry *logrus.Entry) error
  • func (hook *Hook) Levels() []logrus.Level
• type LevelColors
  • func (lc LevelColors) LevelColor(l logrus.Level) int
• type Opts

Variables

var DefaultLevelColors = LevelColors{
	Debug: 10170623,
	Info:  3581519,
	Warn:  14327864,
	Error: 13631488,
	Panic: 13631488,
	Fatal: 13631488,
}

DefaultLevelColors is a struct of the default colors used

Functions

func LevelThreshold

func LevelThreshold(l logrus.Level) []logrus.Level

LevelThreshold returns a slice of all the levels above and including the level specified

Types

type Hook

type Hook struct {
	// WebhookURL is the full Discord webhook URL
	WebhookURL string
	// MinLevel is the minimum priority level to enable logging for
	MinLevel logrus.Level
	// Opts contains the options available for the hook
	Opts *Opts
}

Hook is a hook to send logs to Discord

func NewHook

func NewHook(webhookURL string, minLevel logrus.Level, opts *Opts) *Hook

NewHook creates a new instance of a hook, ensures correct string lengths and returns its pointer

func (*Hook) Fire

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

func (*Hook) Levels

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

type LevelColors

type LevelColors struct {
	Debug int
	Info  int
	Warn  int
	Error int
	Panic int
	Fatal int
}

LevelColors is a struct of the possible colors used in Discord color format (0x[RGB] converted to int)

func (LevelColors) LevelColor

func (lc LevelColors) LevelColor(l logrus.Level) int

LevelColor returns the respective color for the logrus level

type Opts

type Opts struct {
	// Username replaces the default username of the webhook bot for the sent message only if set (default: none)
	Username string
	// Author adds an author field if set (default: none)
	Author string
	// DisableInlineFields causes fields to be displayed one per line as opposed to being inline (i.e., in columns) (default: false)
	DisableInlineFields bool
	// EnableCustomColors specifies whether CustomLevelColors should be used instead of DefaultLevelColors (default: true)
	EnableCustomColors bool
	// CustomLevelColors is a LevelColors struct which replaces DefaultLevelColors if EnableCustomColors is set to true (default: none)
	CustomLevelColors *LevelColors
	// DisableTimestamp specifies whether the timestamp in the footer should be disabled (default: false)
	DisableTimestamp bool
	// TimestampFormat specifies a custom format for the footer
	TimestampFormat string
	// TimestampLocale specifies a custom locale for the timestamp
	TimestampLocale *time.Location
}

Opts contains the options available for the hook