sentry.go

package sentry

import (
	"context"
	"time"

	"github.com/getsentry/sentry-go/internal/debuglog"
)

// The version of the SDK.
const SDKVersion = "1.0.0-alpha.1"

// DefaultFlushTimeout is the default timeout used for flushing events.
const DefaultFlushTimeout = 2 * time.Second

// Init initializes the SDK with options. The returned error is non-nil if
// options is invalid, for instance if a malformed DSN is provided.
func Init(options ClientOptions) error {
	client, err := NewClient(options)
	if err != nil {
		return err
	}
	setGlobalClient(client)
	return nil
}

// AddBreadcrumb records a new breadcrumb using the scope and client carried
// by ctx. The breadcrumb is dropped when ctx carries no scope.
//
// The total number of breadcrumbs that can be recorded are limited by the
// configuration on the client.
func AddBreadcrumb(ctx context.Context, breadcrumb *Breadcrumb, options ...BreadcrumbOption) {
	scope := ScopeFromContext(ctx)
	if scope == nil {
		debuglog.Println("breadcrumb dropped: ctx carries no scope. Use WithScope to start one.")
		return
	}
	client := ClientFromContext(ctx)
	limit := client.options.MaxBreadcrumbs
	switch {
	case limit < 0:
		return
	case limit == 0:
		limit = defaultMaxBreadcrumbs
	}
	if client.options.BeforeBreadcrumb != nil {
		resolved := breadcrumbOptions{}
		for _, option := range options {
			if option != nil {
				option(&resolved)
			}
		}
		if resolved.hint == nil {
			resolved.hint = &BreadcrumbHint{}
		}
		if breadcrumb = client.options.BeforeBreadcrumb(breadcrumb, resolved.hint); breadcrumb == nil {
			debuglog.Println("breadcrumb dropped due to BeforeBreadcrumb callback.")
			return
		}
	}
	scope.AddBreadcrumb(breadcrumb, limit)
}

// CaptureMessage captures an arbitrary message using the scope and client
// carried by ctx.
func CaptureMessage(ctx context.Context, message string, options ...CaptureOption) *EventID {
	return ClientFromContext(ctx).CaptureMessage(ctx, message, options...)
}

// CaptureException captures an error using the scope and client carried by
// ctx.
func CaptureException(ctx context.Context, exception error, options ...CaptureOption) *EventID {
	return ClientFromContext(ctx).CaptureException(ctx, exception, options...)
}

// CaptureCheckIn captures a (cron) monitor check-in using the scope and client
// carried by ctx.
func CaptureCheckIn(
	ctx context.Context,
	checkIn *CheckIn,
	monitorConfig *MonitorConfig,
	options ...CaptureOption,
) *EventID {
	return ClientFromContext(ctx).CaptureCheckIn(ctx, checkIn, monitorConfig, options...)
}

// WithMonitor runs fn and reports its outcome as check-ins for the cron
// monitor identified by monitorSlug, using the scope and client carried by ctx.
//
// An in_progress check-in carrying monitorConfig is sent before fn runs. When
// monitorConfig is not nil, Sentry creates the monitor if it does not exist,
// or updates its configuration. After fn returns, an ok check-in is sent if
// it returned nil, or an error check-in otherwise, along with the measured
// duration. If fn panics, an error check-in is sent and the panic continues.
//
// The error returned by fn is returned unchanged.
func WithMonitor(ctx context.Context, monitorSlug string, monitorConfig *MonitorConfig, fn func() error) error {
	ctx, _ = WithScope(ctx)
	checkInID := CaptureCheckIn(ctx, &CheckIn{
		MonitorSlug: monitorSlug,
		Status:      CheckInStatusInProgress,
	}, monitorConfig)
	start := time.Now()

	status := CheckInStatusError
	defer func() {
		checkIn := &CheckIn{
			MonitorSlug: monitorSlug,
			Status:      status,
			Duration:    time.Since(start),
		}
		if checkInID != nil {
			checkIn.ID = *checkInID
		}
		CaptureCheckIn(ctx, checkIn, nil)
	}()

	err := fn()
	if err == nil {
		status = CheckInStatusOK
	}
	return err
}

// CaptureEvent captures an event using the scope and client carried by ctx.
//
// The event must already be assembled. Typically code would instead use
// the utility methods like CaptureException. The return value is the
// event ID. In case Sentry is disabled or event was dropped, the return value will be nil.
func CaptureEvent(ctx context.Context, event *Event, options ...CaptureOption) *EventID {
	return ClientFromContext(ctx).CaptureEvent(ctx, event, options...)
}

// Recover captures a recovered panic value using the scope and client carried
// by ctx. When recovered is nil, Recover invokes Go's built-in recover and must
// itself be deferred.
func Recover(ctx context.Context, recovered any, options ...CaptureOption) *EventID {
	if recovered == nil {
		recovered = recover()
	}
	if recovered == nil {
		return nil
	}
	return ClientFromContext(ctx).capturePanic(ctx, recovered, options...)
}

// Flush waits until the underlying Transport sends any buffered events to the
// Sentry server, blocking for at most the given timeout. It returns false if
// capture is disabled or the timeout was reached. In the latter case, some
// events may not have been sent.
//
// Flush should be called before terminating the program to avoid
// unintentionally dropping events.
//
// Do not call Flush indiscriminately after every call to CaptureEvent,
// CaptureException or CaptureMessage. Instead, to have the SDK send events over
// the network synchronously, configure it to use the HTTPSyncTransport in the
// call to Init.
func Flush(timeout time.Duration) bool {
	return ClientFromContext(context.Background()).Flush(timeout)
}

// FlushWithContext waits until the underlying Transport sends any buffered events
// to the Sentry server, blocking for at most the duration specified by the
// context. It returns false if capture is disabled or the context is canceled
// before the events are sent. In the latter case, some events may not be
// delivered.
//
// FlushWithContext should be called before terminating the program to ensure no
// events are unintentionally dropped.
//
// Avoid calling FlushWithContext indiscriminately after each call to CaptureEvent,
// CaptureException, or CaptureMessage. To send events synchronously over the network,
// configure the SDK to use HTTPSyncTransport during initialization with Init.

func FlushWithContext(ctx context.Context) bool {
	return ClientFromContext(ctx).FlushWithContext(ctx)
}

// LastEventID returns the last event ID captured in ctx's scope, or an empty
// ID when ctx does not carry one.
func LastEventID(ctx context.Context) EventID {
	scope := ScopeFromContext(ctx)
	if scope == nil {
		return ""
	}
	return scope.lastEventIDSnapshot()
}