sentryzerolog

README

Official Sentry Zerolog Writer for Sentry-Go SDK

Go.dev Documentation: https://pkg.go.dev/github.com/getsentry/sentryzerolog
Example Usage: https://github.com/getsentry/sentry-go/tree/master/_examples/zerolog

Overview

This package provides a writer for the Zerolog logger, enabling seamless integration with Sentry. With this writer, logs at specific levels can be captured as Sentry events, while others can be added as breadcrumbs for enhanced context.

Installation

go get github.com/getsentry/sentry-go/zerolog

Usage

package main

import (
	"time"

	"github.com/rs/zerolog"
	"github.com/getsentry/sentry-go"
	sentryzerolog "github.com/getsentry/sentry-go/zerolog"
)

func main() {
	// Initialize Sentry
	err := sentry.Init(sentry.ClientOptions{
		Dsn: "your-public-dsn",
	})
	if err != nil {
		panic(err)
	}
	defer sentry.Flush(2 * time.Second)

	// Configure Sentry Zerolog Writer
	writer, err := sentryzerolog.New(sentryzerolog.Config{
		ClientOptions: sentry.ClientOptions{
			Dsn:   "your-public-dsn",
			Debug: true,
		},
		Options: sentryzerolog.Options{
			Levels:         []zerolog.Level{zerolog.ErrorLevel, zerolog.FatalLevel},
			FlushTimeout:   3 * time.Second,
			WithBreadcrumbs: true,
		},
	})
	if err != nil {
		panic(err)
	}
	defer writer.Close()

	// Initialize Zerolog
	logger := zerolog.New(writer).With().Timestamp().Logger()

	// Example Logs
	logger.Info().Msg("This is an info message")           // Breadcrumb
	logger.Error().Msg("This is an error message")         // Captured as an event
	logger.Fatal().Msg("This is a fatal message")          // Captured as an event and flushes
}

Configuration

The sentryzerolog.New function accepts a sentryzerolog.Config struct, which allows for the following configuration options:

• ClientOptions: A struct of sentry.ClientOptions that allows you to configure how the Sentry client will behave.
• Options: A struct of sentryzerolog.Options that allows you to configure how the Sentry Zerolog writer will behave.

The sentryzerolog.Options struct allows you to configure the following:

• Levels: An array of zerolog.Level that defines which log levels should be sent to Sentry.
• FlushTimeout: A time.Duration that defines how long to wait before flushing events.
• WithBreadcrumbs: A bool that enables or disables adding logs as breadcrumbs for contextual logging. Non-event logs will appear as breadcrumbs in Sentry.

Notes

• Always call Flush to ensure all events are sent to Sentry before program termination

Documentation

Index

• Constants
• Variables
• type Config
• type Options
  • func (o *Options) SetDefaults()
• type Writer
  • func New(cfg Config) (*Writer, error)
  • func NewWithHub(hub *sentry.Hub, opts Options) (*Writer, error)
  • func (w *Writer) Close() error
  • func (w *Writer) Write(data []byte) (int, error)
  • func (w *Writer) WriteLevel(level zerolog.Level, p []byte) (int, error)

Constants

const (
	// FieldRequest holds an *http.Request.
	FieldRequest = "request"
	// FieldUser holds a User or *User value.
	FieldUser = "user"
	// FieldTransaction holds a transaction ID as a string.
	FieldTransaction = "transaction"
	// FieldFingerprint holds a string slice ([]string), used to dictate the
	// grouping of this event.
	FieldFingerprint = "fingerprint"

	// These fields are simply omitted, as they are duplicated by the Sentry SDK.
	FieldGoVersion = "go_version"
	FieldMaxProcs  = "go_maxprocs"
)

These default log field keys are used to pass specific metadata in a way that Sentry understands. If they are found in the log fields, and the value is of the expected datatype, it will be converted from a generic field, into Sentry metadata.

Variables

var (
	// ErrFlushTimeout is returned when the flush operation times out.
	ErrFlushTimeout = errors.New("sentryzerolog flush timeout")
)

Types

type Config

type Config struct {
	sentry.ClientOptions
	Options
}

type Options

type Options struct {
	// Levels specifies the log levels that will trigger event sending to Sentry.
	// Only log messages at these levels will be sent. By default, the levels are
	// Error, Fatal, and Panic.
	Levels []zerolog.Level

	// WithBreadcrumbs, when enabled, adds log entries as breadcrumbs in Sentry.
	// Breadcrumbs provide a trail of events leading up to an error, which can
	// be invaluable for understanding the context of issues.
	WithBreadcrumbs bool

	// FlushTimeout sets the maximum duration allowed for flushing events to Sentry.
	// This is the time limit within which all pending events must be sent to Sentry
	// before the application exits. A typical use is ensuring all logs are sent before
	// application shutdown. The default timeout is usually 3 seconds.
	FlushTimeout time.Duration
}

func (*Options) SetDefaults

func (o *Options) SetDefaults()

type Writer

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

Writer is a sentry events writer with std io.Writer interface.

func New

func New(cfg Config) (*Writer, error)

New creates writer with provided DSN and options.

func NewWithHub

func NewWithHub(hub *sentry.Hub, opts Options) (*Writer, error)

NewWithHub creates a writer using an existing sentry Hub and options.

func (*Writer) Close

func (w *Writer) Close() error

Close forces client to flush all pending events. Can be useful before application exits.

func (*Writer) Write

func (w *Writer) Write(data []byte) (int, error)

Write handles zerolog's json and sends events to sentry.

func (*Writer) WriteLevel

func (w *Writer) WriteLevel(level zerolog.Level, p []byte) (int, error)