Documentation
¶
Overview ¶
Package sentrycore is the framework-agnostic Sentry error/crash reporting engine behind the sentryfiber (Fiber v2) and sentryfiberv3 (Fiber v3) adapters and the logcore zap hook.
Scope: Sentry here does ERROR and CRASH reporting only. Tracing and metrics remain the responsibility of the sibling apmcore package (Elastic APM + OpenTelemetry). To keep a captured error linkable back to its trace in Kibana, CaptureFields/CaptureException attach the active APM trace.id / transaction.id as Sentry tags.
It exposes:
- SetupSentry: initialize the Sentry SDK from Options. An empty DSN yields a silent no-op — every capture becomes a cheap no-op and the application runs unchanged. This is the "does not interfere with the running app" guarantee.
- CaptureException / CaptureFields: report an error (optionally with the active APM trace tags) through the current or a fresh hub.
- WrapHTTPTransport: wrap an http.RoundTripper so outgoing requests are recorded as Sentry breadcrumbs, giving errors HTTP context.
- RegisterWithManager: register the flushing ShutdownFunc as a gscore closer so buffered events are flushed before the process exits.
The package is intentionally Fiber-agnostic. HTTP middleware lives in the sentryfiber/sentryfiberv3 adapter packages.
Index ¶
- func CaptureException(ctx context.Context, err error)
- func CaptureFields(ctx context.Context) map[string]string
- func Enabled() bool
- func RegisterWithManager(fn ShutdownFunc, mgr CloserRegistrar, phase int, timeout time.Duration)
- func WrapHTTPTransport(base http.RoundTripper) http.RoundTripper
- type CloserRegistrar
- type Options
- type ShutdownFunc
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CaptureException ¶
CaptureException reports err through the hub bound to ctx (or the current hub when ctx carries none), attaching the active APM trace tags so the event links back to its Kibana trace. It is a no-op when err is nil or Sentry is disabled.
func CaptureFields ¶
CaptureFields returns the APM trace correlation tags (trace_id, transaction_id) for ctx, suitable for attaching to a Sentry scope. It is exported so the Fiber adapters can enrich their per-request scope without re-deriving the mapping.
func Enabled ¶
func Enabled() bool
Enabled reports whether SetupSentry initialized a live Sentry client. When false, all capture helpers are no-ops.
func RegisterWithManager ¶
func RegisterWithManager(fn ShutdownFunc, mgr CloserRegistrar, phase int, timeout time.Duration)
RegisterWithManager registers the Sentry flush ShutdownFunc as a PhasePostDB closer so buffered events are flushed before the process exits. Call it immediately after SetupSentry.
A nil fn (e.g. the no-op returned when Sentry is disabled) is still registered but does nothing, keeping the closer list stable across enabled/disabled configurations.
phase must be gscore.PhasePostDB (value 4). Pass 0 to use PhasePostDB. timeout=0 defaults to 5s.
shutdown, err := sentrycore.SetupSentry(ctx, opts) sentrycore.RegisterWithManager(shutdown, mgr, gscore.PhasePostDB, 0)
func WrapHTTPTransport ¶
func WrapHTTPTransport(base http.RoundTripper) http.RoundTripper
WrapHTTPTransport wraps base so every outgoing request built with http.NewRequestWithContext leaves an "http" breadcrumb (method, URL, status code) on the request's Sentry hub. It mirrors apmcore.WrapHTTPTransport and is meant to compose with it:
rt := apmcore.WrapHTTPTransport(nil) // APM spans + traceparent
rt = sentrycore.WrapHTTPTransport(rt) // + Sentry breadcrumbs
client := &http.Client{Transport: rt}
If base is nil, http.DefaultTransport is wrapped. When Sentry is disabled the wrapper still forwards the request; recording a breadcrumb on a no-op hub is harmless and cheap.
Types ¶
type CloserRegistrar ¶
type CloserRegistrar = gscore.CloserRegistrar
CloserRegistrar is the subset of gscore.Manager used by sentrycore helpers. It is a type alias for gscore.CloserRegistrar; *gscore.Manager satisfies it directly.
type Options ¶
type Options struct {
// DSN is the Sentry project DSN. Empty (and no SENTRY_DSN in the
// environment) disables Sentry entirely: SetupSentry returns a no-op
// ShutdownFunc and every capture is a no-op. Nothing about the
// running application changes.
DSN string
// Environment tags events (e.g. "production", "staging"). Empty falls
// back to SENTRY_ENVIRONMENT.
Environment string
// Release identifies the deployed build (e.g. a version or git sha).
// Empty falls back to SENTRY_RELEASE.
Release string
// ServerName overrides the reported server/host name. Empty lets the
// SDK resolve it.
ServerName string
// SampleRate is the error-event sample rate in [0,1]. Zero is treated
// as 1.0 (report every error) so a zero-value Options stays useful.
SampleRate float64
// Debug turns on the Sentry SDK debug logging.
Debug bool
// Tags are attached to every event as global tags. Useful for
// service.name / service.version so events are filterable alongside
// the logcore log fields.
Tags map[string]string
// FlushTimeout bounds how long the ShutdownFunc waits for buffered
// events to be sent. Zero defaults to 2s.
FlushTimeout time.Duration
// Extra is merged onto the sentry.ClientOptions built from the fields
// above, letting callers set anything the struct does not expose
// (BeforeSend, integrations, transport, …). It runs last and wins.
Extra func(*sentry.ClientOptions)
}
Options tunes SetupSentry. All fields are optional; when a field is zero the Sentry SDK falls back to its own environment-variable lookup (SENTRY_DSN, SENTRY_ENVIRONMENT, SENTRY_RELEASE), matching the convention used by the Elastic APM agent in apmcore.
type ShutdownFunc ¶
ShutdownFunc flushes buffered Sentry events. It is safe to call multiple times; subsequent calls are no-ops. It mirrors apmcore.ShutdownFunc so both can be registered through the same gscore closer machinery.
func SetupSentry ¶
func SetupSentry(_ context.Context, opts Options) (ShutdownFunc, error)
SetupSentry initializes the global Sentry client from opts.
If opts.DSN is empty and no SENTRY_DSN is set in the environment, Sentry stays disabled: this returns a no-op ShutdownFunc and nil error, and Enabled() reports false. This is deliberate so a service can ship the wiring unconditionally and turn Sentry on purely via configuration.
The returned ShutdownFunc calls sentry.Flush; register it with RegisterWithManager so events are flushed during graceful shutdown.
Source Files