sentryslog

README

Official Sentry Integration for slog

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

---

Installation

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

Usage

package main

import (
	"context"
	"log/slog"

	"github.com/getsentry/sentry-go"
	sentryslog "github.com/getsentry/sentry-go/slog"
)

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

	ctx := context.Background()
	handler := sentryslog.Option{
		EventLevel: []slog.Level{slog.LevelError, sentryslog.LevelFatal}, // Only Error and Fatal as events
		LogLevel:   []slog.Level{slog.LevelWarn, slog.LevelInfo},         // Only Warn and Info as logs
	}.NewSentryHandler(ctx)
    logger := slog.New(handler)

	// Example logging
	logger.Info("This will be sent to sentry as a Log entry")
	logger.Error("An error occurred", "user", "test-user") // this will be sent as an Event
	// These will be ignored
	logger.Debug("This will be ignored")
}

Configuration

The slog-sentry package offers several options to customize how logs are handled and sent to Sentry. These are specified through the Option struct:

• EventLevel: Slice of specific levels to send Events to Sentry. Defaults to []slog.Level{slog.LevelError, LevelFatal}.

• LogLevel: Slice of specific levels to send Log entries to Sentry. Defaults to []slog.Level{slog.LevelDebug, slog.LevelInfo, slog.LevelWarn, slog.LevelError, LevelFatal}.

• Hub: Custom Sentry hub to use; defaults to the current Sentry hub if not set.

• Converter: Custom function to transform logs into Sentry events (default is DefaultConverter).

• AttrFromContext: Functions to extract additional attributes from the context.

• AddSource: Include file/line source info in Sentry events. Defaults to false.

• ReplaceAttr: Allows modification or filtering of attributes before sending to Sentry.

Example Customization

handler := slogSentry.Option{
	EventLevel: slog.LevelWarn,
	Converter: func(addSource bool, replaceAttr func([]string, slog.Attr) slog.Attr, attrs []slog.Attr, groups []string, record *slog.Record, hub *sentry.Hub) *sentry.Event {
		// Custom conversion logic
		return &sentry.Event{
			Message: record.Message,
		}
	},
	AddSource: true,
}.NewSentryHandler()

Backwards Compatibility

The old Level field is Deprecated but still works and will be converted to a slice of all levels starting from the minimum level:

// Old way (still works)
handler := sentryslog.Option{
    Level: slog.LevelWarn, // Will be converted to EventLevel: [Warn, Error, Fatal]
}.NewSentryHandler(ctx)

// New way (preferred)
handler := sentryslog.Option{
    EventLevel: []slog.Level{slog.LevelWarn, slog.LevelError, sentryslog.LevelFatal},
    LogLevel:   []slog.Level{slog.LevelDebug, slog.LevelInfo, slog.LevelWarn, slog.LevelError, sentryslog.LevelFatal},
}.NewSentryHandler(ctx)

Notes

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

Documentation

Index

• Constants
• Variables
• func DefaultConverter(addSource bool, replaceAttr func(groups []string, a slog.Attr) slog.Attr, ...) *sentry.Event
• type Converter
• type Option
  • func (o Option) NewSentryHandler(ctx context.Context) slog.Handler
• type SentryHandler
  • func (h *SentryHandler) Enabled(ctx context.Context, level slog.Level) bool
  • func (h *SentryHandler) Handle(ctx context.Context, record slog.Record) error
  • func (h *SentryHandler) WithAttrs(attrs []slog.Attr) slog.Handler
  • func (h *SentryHandler) WithGroup(name string) slog.Handler

Constants

const LevelFatal = slog.Level(12)

LevelFatal is a custom slog.Level that maps to sentry.LevelFatal.

const SlogOrigin = "auto.log.slog"

Variables

var (

	// Deprecated: LogLevels is only used by the deprecated event capture functionality.
	// Will be removed in 0.48.0.
	LogLevels = map[slog.Level]sentry.Level{
		slog.LevelDebug: sentry.LevelDebug,
		slog.LevelInfo:  sentry.LevelInfo,
		slog.LevelWarn:  sentry.LevelWarning,
		slog.LevelError: sentry.LevelError,
		LevelFatal:      sentry.LevelFatal,
	}
)

Functions

func DefaultConverter

func DefaultConverter(addSource bool, replaceAttr func(groups []string, a slog.Attr) slog.Attr, loggerAttr []slog.Attr, groups []string, record *slog.Record, hub *sentry.Hub) *sentry.Event

Deprecated: DefaultConverter is only used by the deprecated event capture functionality. Errors should only be captured using sentry.CaptureException instead of being converted from log entries. Will be removed in 0.48.0.

Types

type Converter

type Converter func(addSource bool, replaceAttr func(groups []string, a slog.Attr) slog.Attr, loggerAttr []slog.Attr, groups []string, record *slog.Record, hub *sentry.Hub) *sentry.Event

Deprecated: Converter is only used by the deprecated event capture functionality. Errors should only be captured using sentry.CaptureException instead of being converted from log entries. Will be removed in 0.48.0.

type Option

type Option struct {
	// Deprecated: Use EventLevel instead. Level is kept for backwards compatibility and defaults to EventLevel.
	Level slog.Leveler

	// Deprecated: EventLevel creates issues/events from log entries. Errors should only be
	// captured using sentry.CaptureException instead of being converted from log entries.
	// Use LogLevel for structured logging. Will be removed in 0.48.0.
	EventLevel []slog.Level

	// LogLevel specifies the exact log levels to capture and send to Sentry as Log entries.
	// Only logs at these specific levels will be processed as log entries.
	// Defaults to []slog.Level{slog.LevelDebug, slog.LevelInfo, slog.LevelWarn, slog.LevelError, LevelFatal}.
	LogLevel []slog.Level

	// Deprecated: Hub is only used by the deprecated event capture functionality. Errors
	// should only be captured using sentry.CaptureException instead of being converted
	// from log entries. Will be removed in 0.48.0.
	Hub *sentry.Hub

	// Deprecated: Converter is only used by the deprecated event capture functionality.
	// Errors should only be captured using sentry.CaptureException instead of being
	// converted from log entries. Will be removed in 0.48.0.
	Converter Converter

	// AttrFromContext is an optional slice of functions that extract attributes
	// from the context. These functions can add additional metadata to the log entry.
	AttrFromContext []func(ctx context.Context) []slog.Attr

	// AddSource is an optional flag that, when set to true, includes the source
	// information (such as file and line number) in the Sentry event.
	// This can be useful for debugging purposes.
	AddSource bool

	// ReplaceAttr is an optional function that allows for the modification or
	// replacement of attributes in the log record. This can be used to filter
	// or transform attributes before they are sent to Sentry.
	ReplaceAttr func(groups []string, a slog.Attr) slog.Attr
}

func (Option) NewSentryHandler

func (o Option) NewSentryHandler(ctx context.Context) slog.Handler

type SentryHandler

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

func (*SentryHandler) Enabled

func (h *SentryHandler) Enabled(ctx context.Context, level slog.Level) bool

func (*SentryHandler) Handle

func (h *SentryHandler) Handle(ctx context.Context, record slog.Record) error

func (*SentryHandler) WithAttrs

func (h *SentryHandler) WithAttrs(attrs []slog.Attr) slog.Handler

func (*SentryHandler) WithGroup

func (h *SentryHandler) WithGroup(name string) slog.Handler