zapsentry

README

Sentry client for zap logger

Installation

go get github.com/TheZeroSlave/zapsentry

Integration using Sentry Client

Integration of sentry client into zap.Logger is pretty simple:

func modifyToSentryLogger(log *zap.Logger, client *sentry.Client) *zap.Logger {
	cfg := zapsentry.Configuration{
		Level: zapcore.ErrorLevel, //when to send message to sentry
		EnableBreadcrumbs: true, // enable sending breadcrumbs to Sentry 
		BreadcrumbLevel: zapcore.InfoLevel, // at what level should we sent breadcrumbs to sentry, this level can't be higher than `Level`
		Tags: map[string]string{
			"component": "system",
		},
	}
	core, err := zapsentry.NewCore(cfg, zapsentry.NewSentryClientFromClient(client))
	
	// don't use value if error was returned. Noop core will be replaced to nil soon.
	if err != nil {
		panic(err)
	}
	
	log = zapsentry.AttachCoreToLogger(core, log)

	// if you have web service, create a new scope somewhere in middleware to have valid breadcrumbs.
	return log.With(zapsentry.NewScope())
}

Please note that wrapper does not guarantee that all your events will be sent before the app exits. Flush called internally only in case of writing message with severity level > zapcore.ErrorLevel (i.e. Fatal, Panic, ...). If you want to ensure your messages come to sentry - call the flush on native sentry client at defer. Example:

func main() {
	sentryClient, err := sentry.NewClient(sentry.ClientOptions{
		Dsn: "Sentry DSN",
	})
	if err != nil {
		// Handle the error here
	}
	// Flush buffered events before the program terminates.
	// Set the timeout to the maximum duration the program can afford to wait.
	defer sentryClient.Flush(2 * time.Second)
	
	// create zap log and wrapper...
	
	// create and run your app here...
}

Documentation

Index

• Variables
• func AttachCoreToLogger(sentryCore zapcore.Core, l *zap.Logger) *zap.Logger
• func Context(ctx context.Context) zap.Field
• func NewCore(cfg Configuration, factory SentryClientFactory) (zapcore.Core, error)
• func NewScope() zapcore.Field
• func NewScopeFromScope(scope *sentry.Scope) zapcore.Field
• func Tag(key string, value string) zap.Field
• type ClientGetter
• type Configuration
• type FrameMatcher
  • func CombineFrameMatchers(matcher ...FrameMatcher) FrameMatcher
• type FrameMatcherFunc
  • func (f FrameMatcherFunc) Matches(frame sentry.Frame) bool
• type FrameMatchers
  • func (ff FrameMatchers) Matches(frame sentry.Frame) bool
• type LevelEnabler
  • func (l *LevelEnabler) Enabled(lvl zapcore.Level) bool
• type SentryClientFactory
  • func NewSentryClientFromClient(client *sentry.Client) SentryClientFactory
  • func NewSentryClientFromDSN(DSN string) SentryClientFactory
• type SkipFunctionPrefixFrameMatcher
  • func (f SkipFunctionPrefixFrameMatcher) Matches(frame sentry.Frame) bool
• type SkipModulePrefixFrameMatcher
  • func (f SkipModulePrefixFrameMatcher) Matches(frame sentry.Frame) bool

Examples

• AttachCoreToLogger

Variables

var (
	ErrInvalidBreadcrumbLevel = errors.New("breadcrumb level must be lower than or equal to error level")
)

Functions

func AttachCoreToLogger

func AttachCoreToLogger(sentryCore zapcore.Core, l *zap.Logger) *zap.Logger

Example

package main

import (
	"fmt"
	"log"
	"time"

	"github.com/getsentry/sentry-go"
	"go.uber.org/zap"
	"go.uber.org/zap/zapcore"
	"go.uber.org/zap/zaptest/observer"

	"github.com/feral-file/zapsentry"
)

func main() {
	// Setup zap with observer (for testing), originally we use
	// 		config = zap.NewDevelopmentConfig()
	//  	logger, err := config.Build()
	// to build zap logger, here we use zap/zaptest/observer for testing
	core, recordedLogs := observer.New(zapcore.DebugLevel)
	logger := zap.New(core, zap.AddStacktrace(zap.DebugLevel))

	// Setup mock sentry client for testing, in general we use sentry.NewClient
	var recordedSentryEvent *sentry.Event
	sentryClient := mockSentryClient(func(event *sentry.Event) {
		recordedSentryEvent = event
	})

	// Setup zapsentry
	core, err := zapsentry.NewCore(zapsentry.Configuration{
		Level:             zapcore.ErrorLevel, // when to send message to sentry
		EnableBreadcrumbs: true,               // enable sending breadcrumbs to Sentry
		BreadcrumbLevel:   zapcore.InfoLevel,  // at what level should we sent breadcrumbs to sentry
		Tags: map[string]string{
			"component": "system",
		},
		FrameMatcher: zapsentry.CombineFrameMatchers(
			// skip all frames having a prefix of 'go.uber.org/zap'
			// this can be used to exclude e.g. logging adapters from the stacktrace
			zapsentry.SkipFunctionPrefixFrameMatcher("go.uber.org/zap"),
		),
	}, zapsentry.NewSentryClientFromClient(sentryClient))
	if err != nil {
		log.Fatal(err)
	}
	newLogger := zapsentry.AttachCoreToLogger(core, logger)

	// Send error log
	newLogger.
		With(zapsentry.NewScope()).
		Error("[error] something went wrong!", zap.String("method", "unknown"), zapsentry.Tag("service", "app"))

	// Check output
	fmt.Println(recordedLogs.All()[0].Message)
	fmt.Println(recordedSentryEvent.Message)
	fmt.Println(recordedSentryEvent.Extra)
	fmt.Println(recordedSentryEvent.Tags)
}

func mockSentryClient(f func(event *sentry.Event)) *sentry.Client {
	client, _ := sentry.NewClient(sentry.ClientOptions{
		Dsn:       "",
		Transport: &transport{MockSendEvent: f},
	})
	return client
}

type transport struct {
	MockSendEvent func(event *sentry.Event)
}

// Flush waits until any buffered events are sent to the Sentry server, blocking
// for at most the given timeout. It returns false if the timeout was reached.
func (f *transport) Flush(_ time.Duration) bool { return true }

// Configure is called by the Client itself, providing it it's own ClientOptions.
func (f *transport) Configure(_ sentry.ClientOptions) {}

// SendEvent assembles a new packet out of Event and sends it to remote server.
// We use this method to capture the event for testing
func (f *transport) SendEvent(event *sentry.Event) {
	f.MockSendEvent(event)
}

Output:
[error] something went wrong!
[error] something went wrong!
map[method:unknown]
map[component:system service:app]

func Context

func Context(ctx context.Context) zap.Field

Context adds a context to the logger. This can be used e.g. to pass trace information to sentry and allow linking events to their respective traces.

See also https://docs.sentry.io/platforms/go/performance/instrumentation/opentelemetry/#linking-errors-to-transactions

func NewCore

func NewCore(cfg Configuration, factory SentryClientFactory) (zapcore.Core, error)

func NewScope

func NewScope() zapcore.Field

func NewScopeFromScope

func NewScopeFromScope(scope *sentry.Scope) zapcore.Field

func Tag

func Tag(key string, value string) zap.Field

Types

type ClientGetter

type ClientGetter interface {
	GetClient() *sentry.Client
}

type Configuration

type Configuration struct {
	// Tags are passed as is to the corresponding sentry.Event field.
	Tags map[string]string

	// LoggerNameKey is the key for zap logger name.
	// If not empty, the name is added to the rest of zapcore.Field(s),
	// so that be careful with key duplicates.
	// Leave LoggerNameKey empty to disable the feature.
	LoggerNameKey string

	// DisableStacktrace disables adding stacktrace to sentry.Event, if set.
	DisableStacktrace bool

	// Level is the minimal level of sentry.Event(s).
	Level zapcore.LevelEnabler

	// EnableBreadcrumbs enables use of sentry.Breadcrumb(s).
	// This feature works only when you explicitly passed new scope.
	EnableBreadcrumbs bool

	// BreadcrumbLevel is the minimal level of sentry.Breadcrumb(s).
	// Breadcrumb specifies an application event that occurred before a Sentry event.
	// NewCore fails if BreadcrumbLevel is greater than Level.
	// The field is ignored, if EnableBreadcrumbs is not set.
	BreadcrumbLevel zapcore.LevelEnabler

	// MaxBreadcrumbs is the maximum number of breadcrumb events to keep.
	// Leave it zero or set to negative for a reasonable default value.
	// The field is ignored, if EnableBreadcrumbs is not set.
	MaxBreadcrumbs int

	// FlushTimeout is the timeout for flushing events to Sentry.
	FlushTimeout time.Duration

	// Hub overrides the sentry.CurrentHub value.
	// See sentry.Hub docs for more detail.
	Hub *sentry.Hub

	// FrameMatcher allows to ignore some frames of the stack trace.
	// this is particularly useful when you want to ignore for instances frames from convenience wrappers
	FrameMatcher FrameMatcher
}

Configuration is a minimal set of parameters for Sentry integration.

type FrameMatcher

type FrameMatcher interface {
	Matches(f sentry.Frame) bool
}

func CombineFrameMatchers

func CombineFrameMatchers(matcher ...FrameMatcher) FrameMatcher

type FrameMatcherFunc

type FrameMatcherFunc func(f sentry.Frame) bool

func (FrameMatcherFunc) Matches

func (f FrameMatcherFunc) Matches(frame sentry.Frame) bool

type FrameMatchers

type FrameMatchers []FrameMatcher

func (FrameMatchers) Matches

func (ff FrameMatchers) Matches(frame sentry.Frame) bool

type LevelEnabler

type LevelEnabler struct {
	zapcore.LevelEnabler
	// contains filtered or unexported fields
}

func (*LevelEnabler) Enabled

func (l *LevelEnabler) Enabled(lvl zapcore.Level) bool

type SentryClientFactory

type SentryClientFactory func() (*sentry.Client, error)

func NewSentryClientFromClient

func NewSentryClientFromClient(client *sentry.Client) SentryClientFactory

func NewSentryClientFromDSN

func NewSentryClientFromDSN(DSN string) SentryClientFactory

type SkipFunctionPrefixFrameMatcher

type SkipFunctionPrefixFrameMatcher string

func (SkipFunctionPrefixFrameMatcher) Matches

func (f SkipFunctionPrefixFrameMatcher) Matches(frame sentry.Frame) bool

type SkipModulePrefixFrameMatcher

type SkipModulePrefixFrameMatcher string

func (SkipModulePrefixFrameMatcher) Matches

func (f SkipModulePrefixFrameMatcher) Matches(frame sentry.Frame) bool