sentry-go

sentry-go is the official Go client for Sentry, the error-tracking and performance-monitoring platform. It captures unhandled panics and errors, attaches breadcrumbs and contextual scope data, and reports them to Sentry with stack traces resolved from Go’s runtime. Beyond error capture, it implements distributed tracing (transactions and spans), structured logging, and metrics, all configurable through a single ClientOptions struct passed to Init.

The SDK ships first-class middleware for a wide range of Go web frameworks and HTTP libraries — net/http, Gin, Echo, Fiber, Iris, fasthttp, gRPC, Negroni — plus adapters for popular loggers (logrus, slog, zap, zerolog) and an OpenTelemetry bridge, so most Go services can wire up error and performance monitoring with a few lines of setup code.

What You Get

• Panic and error capture with resolved Go stack traces via CaptureException and Recover/RecoverWithContext
• Distributed tracing with StartTransaction/StartSpan, trace propagation headers, and configurable sampling
• Framework middleware for net/http, Gin, Echo, Fiber, Iris, fasthttp, gRPC, and Negroni
• Logger integrations for logrus, slog, zap, and zerolog that forward log entries as breadcrumbs or events
• Structured logging and metrics APIs alongside error/performance reporting
• Configurable HTTP transports (async batching or HTTPSyncTransport for serverless) with rate-limit handling

Common Use Cases

• Reporting unhandled panics from production HTTP servers with full stack traces and request context
• Instrumenting distributed traces across microservices using StartTransaction and ContinueTrace
• Correlating structured logs from logrus/zap/zerolog with Sentry events via breadcrumbs
• Monitoring scheduled/cron jobs with CaptureCheckIn and MonitorConfig
• Attaching custom user, tag, and extra-data context to errors via Scope

Under The Hood

Architecture The SDK centers on a Hub/Scope/Client pattern (hub.go, scope.go, client.go): a Hub holds a stack of Scopes and a bound Client, and package-level functions in sentry.go (Init, CaptureException, Recover, WithScope) delegate to CurrentHub(). Context-based hub retrieval (GetHubFromContext/SetHubOnContext) enables per-request isolation — the http/sentryhttp.go middleware clones a fresh hub per request, starts a transaction, and defers panic recovery against that hub. The transport layer (transport.go) implements batching and rate-limit handling independently of capture logic, so swapping HTTPTransport for HTTPSyncTransport requires no changes elsewhere. Tracing (tracing.go) is a parallel subsystem built on Span/Transaction structs threaded through context.Context and consumed uniformly by the 13+ framework-integration packages. Wire-format, rate-limiting, and telemetry concerns are isolated under internal/, keeping the public API surface small; changing the Hub/Scope contract would require touching every framework integration and both context helpers.

Tech Stack The root module (github.com/getsentry/sentry-go, go.mod, Go 1.25) carries minimal dependencies — go-errors/errors, pingcap/errors, and pkg/errors for compatibility across different error-wrapping styles, plus stretchr/testify, google/go-cmp, and uber-go/goleak for testing. Framework integrations (gin/, echo/, fiber/, grpc/, and others) live as separate Go modules coordinated through a root go.work file, so consumers only pull in the framework dependency they actually use rather than the full integration matrix. CI runs golangci-lint, govulncheck, and CodeQL across a Go version matrix.

Code Quality 307 test functions across 34 test files in the root package alone, with additional suites inside each framework-integration submodule. Tests use testify for assertions, go-cmp for deep-equal diffs, and goleak to catch goroutine leaks in the concurrency-heavy batch processor and telemetry code. Errors are returned rather than swallowed in the reviewed core files (client.go, sentry.go, http/sentryhttp.go), and CI enforces linting, dependency vulnerability scanning, and static analysis on every pull request.

API Design The public API is a small set of package-level functions (Init, CaptureException, CaptureMessage, Recover, WithScope) that delegate to a hidden global Hub, so a minimal integration is a single Init call plus a deferred Recover. Power users can reach the same functionality through an explicit context-scoped Hub for goroutine-safe, multi-tenant use. Configuration uses a declarative ClientOptions struct rather than functional options, and every framework integration follows the same New(Options) *Handler plus Handle/HandleFunc middleware shape, so moving between frameworks doesn’t require relearning the integration surface. Extensive godoc comments and 26 runnable examples under _examples/ shorten the path to a working integration.