logrus_sentry

README

Sentry Hook for Logrus

Sentry provides both self-hosted and hosted solutions for exception tracking. Both client and server are open source.

Usage

Every sentry application defined on the server gets a different DSN. In the example below replace YOUR_DSN with the one created for your application.

import (
  "github.com/Sirupsen/logrus"
  "github.com/evalphobia/logrus_sentry"
)

func main() {
  log       := logrus.New()
  hook, err := logrus_sentry.NewSentryHook(YOUR_DSN, []logrus.Level{
    logrus.PanicLevel,
    logrus.FatalLevel,
    logrus.ErrorLevel,
  })

  if err == nil {
    log.Hooks.Add(hook)
  }
}

If you wish to initialize a SentryHook with tags, you can use the NewWithTagsSentryHook constructor to provide default tags:

tags := map[string]string{
  "site": "example.com",
}
levels := []logrus.Level{
  logrus.PanicLevel,
  logrus.FatalLevel,
  logrus.ErrorLevel,
}
hook, err := logrus_sentry.NewWithTagsSentryHook(YOUR_DSN, tags, levels)

If you wish to initialize a SentryHook with an already initialized raven client, you can use the NewWithClientSentryHook constructor:

import (
  "github.com/Sirupsen/logrus"
  "github.com/evalphobia/logrus_sentry"
  "github.com/getsentry/raven-go"
)

func main() {
  log := logrus.New()

  client, err := raven.New(YOUR_DSN)
  if err != nil {
      log.Fatal(err)
  }

  hook, err := logrus_sentry.NewWithClientSentryHook(client, []logrus.Level{
    logrus.PanicLevel,
    logrus.FatalLevel,
    logrus.ErrorLevel,
  })

  if err == nil {
    log.Hooks.Add(hook)
  }
}

hook, err := NewWithClientSentryHook(client, []logrus.Level{
	logrus.ErrorLevel,
})

Special fields

Some logrus fields have a special meaning in this hook, and they will be especially processed by Sentry.

Field key	Description
event_id	Each logged event is identified by the event_id, which is hexadecimal string representing a UUID4 value. You can manually specify the identifier of a log event by supplying this field. The event_id string should be in one of the following UUID format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx and urn:uuid:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)
user_name	Name of the user who is in the context of the event
user_email	Email of the user who is in the context of the event
user_id	ID of the user who is in the context of the event
user_ip	IP of the user who is in the context of the event
server_name	Also known as hostname, it is the name of the server which is logging the event (hostname.example.com)
tags	tags are raven.Tags struct from github.com/getsentry/raven-go and override default tags data
logger	logger is the part of the application which is logging the event. In go this usually means setting it to the name of the package.
http_request	http_request is the in-coming request(*http.Request). The detailed request data are sent to Sentry.

Timeout

Timeout is the time the sentry hook will wait for a response from the sentry server.

If this time elapses with no response from the server an error will be returned.

If Timeout is set to 0 the SentryHook will not wait for a reply and will assume a correct delivery.

The SentryHook has a default timeout of 100 milliseconds when created with a call to NewSentryHook. This can be changed by assigning a value to the Timeout field:

hook, _ := logrus_sentry.NewSentryHook(...)
hook.Timeout = 20*time.Second

Enabling Stacktraces

By default the hook will not send any stacktraces. However, this can be enabled with:

hook, _ := logrus_sentry.NewSentryHook(...)
hook.StacktraceConfiguration.Enable = true

Subsequent calls to logger.Error and above will create a stacktrace.

Other configuration options are:

• StacktraceConfiguration.Level the logrus level at which to start capturing stacktraces.
• StacktraceConfiguration.Skip how many stack frames to skip before stacktrace starts recording.
• StacktraceConfiguration.Context the number of lines to include around a stack frame for context.
• StacktraceConfiguration.InAppPrefixes the prefixes that will be matched against the stack frame to identify it as in_app

Documentation

Index

• Variables
• type SentryHook
  • func NewAsyncSentryHook(DSN string, levels []logrus.Level) (*SentryHook, error)
  • func NewAsyncWithClientSentryHook(client *raven.Client, levels []logrus.Level) (*SentryHook, error)
  • func NewAsyncWithTagsSentryHook(DSN string, tags map[string]string, levels []logrus.Level) (*SentryHook, error)
  • func NewSentryHook(DSN string, levels []logrus.Level) (*SentryHook, error)
  • func NewWithClientSentryHook(client *raven.Client, levels []logrus.Level) (*SentryHook, error)
  • func NewWithTagsSentryHook(DSN string, tags map[string]string, levels []logrus.Level) (*SentryHook, error)
  • func (hook *SentryHook) AddExtraFilter(name string, fn func(interface{}) interface{})
  • func (hook *SentryHook) AddIgnore(name string)
  • func (hook *SentryHook) Fire(entry *logrus.Entry) error
  • func (hook *SentryHook) Flush()
  • func (hook *SentryHook) Levels() []logrus.Level
  • func (hook *SentryHook) SetEnvironment(environment string)
  • func (hook *SentryHook) SetRelease(release string)
• type StackTraceConfiguration
• type Stacktracer

Variables

var BufSize uint = 8192

BufSize controls the number of logs that can be in progress before logging will start blocking. Set logrus_sentry.BufSize = <value> _before_ calling NewAsync*().

Types

type SentryHook

type SentryHook struct {
	// Timeout sets the time to wait for a delivery error from the sentry server.
	// If this is set to zero the server will not wait for any response and will
	// consider the message correctly sent
	Timeout                 time.Duration
	StacktraceConfiguration StackTraceConfiguration
	// contains filtered or unexported fields
}

SentryHook delivers logs to a sentry server.

func NewAsyncSentryHook

func NewAsyncSentryHook(DSN string, levels []logrus.Level) (*SentryHook, error)

NewAsyncSentryHook creates a hook same as NewSentryHook, but in asynchronous mode. This method sets the timeout to 1000 milliseconds.

func NewAsyncWithClientSentryHook

func NewAsyncWithClientSentryHook(client *raven.Client, levels []logrus.Level) (*SentryHook, error)

NewAsyncWithClientSentryHook creates a hook same as NewWithClientSentryHook, but in asynchronous mode. This method sets the timeout to 1000 milliseconds.

func NewAsyncWithTagsSentryHook

func NewAsyncWithTagsSentryHook(DSN string, tags map[string]string, levels []logrus.Level) (*SentryHook, error)

NewAsyncWithTagsSentryHook creates a hook same as NewWithTagsSentryHook, but in asynchronous mode. This method sets the timeout to 1000 milliseconds.

func NewSentryHook

func NewSentryHook(DSN string, levels []logrus.Level) (*SentryHook, error)

NewSentryHook creates a hook to be added to an instance of logger and initializes the raven client. This method sets the timeout to 100 milliseconds.

func NewWithClientSentryHook

func NewWithClientSentryHook(client *raven.Client, levels []logrus.Level) (*SentryHook, error)

NewWithClientSentryHook creates a hook using an initialized raven client. This method sets the timeout to 100 milliseconds.

func NewWithTagsSentryHook

func NewWithTagsSentryHook(DSN string, tags map[string]string, levels []logrus.Level) (*SentryHook, error)

NewWithTagsSentryHook creates a hook with tags to be added to an instance of logger and initializes the raven client. This method sets the timeout to 100 milliseconds.

func (*SentryHook) AddExtraFilter

func (hook *SentryHook) AddExtraFilter(name string, fn func(interface{}) interface{})

AddExtraFilter adds a custom filter function.

func (*SentryHook) AddIgnore

func (hook *SentryHook) AddIgnore(name string)

AddIgnore adds field name to ignore.

func (*SentryHook) Fire

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

Fire is called when an event should be sent to sentry Special fields that sentry uses to give more information to the server are extracted from entry.Data (if they are found) These fields are: error, logger, server_name, http_request, tags

func (*SentryHook) Flush

func (hook *SentryHook) Flush()

Flush waits for the log queue to empty. This function only does anything in asynchronous mode.

func (*SentryHook) Levels

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

Levels returns the available logging levels.

func (*SentryHook) SetEnvironment

func (hook *SentryHook) SetEnvironment(environment string)

SetEnvironment sets environment tag.

func (*SentryHook) SetRelease

func (hook *SentryHook) SetRelease(release string)

SetRelease sets release tag.

type StackTraceConfiguration

type StackTraceConfiguration struct {
	// whether stacktraces should be enabled
	Enable bool
	// the level at which to start capturing stacktraces
	Level logrus.Level
	// how many stack frames to skip before stacktrace starts recording
	Skip int
	// the number of lines to include around a stack frame for context
	Context int
	// the prefixes that will be matched against the stack frame.
	// if the stack frame's package matches one of these prefixes
	// sentry will identify the stack frame as "in_app"
	InAppPrefixes []string
}

StackTraceConfiguration allows for configuring stacktraces

type Stacktracer

type Stacktracer interface {
	GetStacktrace() *raven.Stacktrace
}

The Stacktracer interface allows an error type to return a raven.Stacktrace.