sentry-go-sdk

All Skills > SDK Setup > Go SDK

Sentry Go SDK

Opinionated wizard that scans your Go project and guides you through complete Sentry setup.

Invoke This Skill When

• User asks to "add Sentry to Go" or "setup Sentry" in a Go app
• User wants error monitoring, tracing, logging, metrics, or crons in Go
• User mentions sentry-go, github.com/getsentry/sentry-go, or Go Sentry SDK
• User wants to monitor panics, HTTP handlers, or scheduled jobs in Go

Note: SDK versions and APIs below reflect Sentry docs at time of writing (sentry-go v0.43.0+). As of v0.33.0+, the SDK requires Go 1.25 or later (supports the two most recent Go major versions). Always verify against docs.sentry.io/platforms/go/ before implementing.

---

Phase 1: Detect

Run these commands to understand the project before making any recommendations:

# Check existing Sentry dependency
grep -i sentry go.mod 2>/dev/null

# Detect web framework
grep -E "gin-gonic/gin|labstack/echo|gofiber/fiber|valyala/fasthttp|kataras/iris|urfave/negroni" go.mod 2>/dev/null

# Detect gRPC
grep "google.golang.org/grpc" go.mod 2>/dev/null

# Detect logging libraries
grep -E "sirupsen/logrus|go.uber.org/zap|rs/zerolog|log/slog" go.mod go.sum 2>/dev/null

# Detect cron / scheduler patterns
grep -E "robfig/cron|go-co-op/gocron|jasonlvhit/gocron" go.mod 2>/dev/null

# Detect OpenTelemetry usage
grep "go.opentelemetry.io" go.mod 2>/dev/null

# Check for companion frontend
ls frontend/ web/ client/ ui/ 2>/dev/null

What to note:

• Is sentry-go already in go.mod? If yes, skip to Phase 2 (configure features).
• Which framework is used? (Determines which sub-package and middleware to install.)
• Which logging library? (Enables automatic log capture.)
• Are cron/scheduler patterns present? (Triggers Crons recommendation.)
• Is there a companion frontend directory? (Triggers Phase 4 cross-link.)

---

Phase 2: Recommend

Based on what you found, present a concrete recommendation. Don't ask open-ended questions — lead with a proposal:

Recommended (core coverage):

• ✅ Error Monitoring — always; captures panics and unhandled errors
• ✅ Tracing — if HTTP handlers, gRPC, or DB calls are detected
• ✅ Logging — if logrus, zap, zerolog, or slog is detected

Optional (enhanced observability):

• ⚡ Metrics — custom counters and gauges for business KPIs / SLOs
• ⚡ Crons — detect silent failures in scheduled jobs
• ⚠️ Profiling — removed in sentry-go v0.31.0; see references/profiling.md for alternatives

Recommendation logic:

Feature	Recommend when...
Error Monitoring	Always — non-negotiable baseline
Tracing	net/http, gin, echo, fiber, gRPC, or DB calls detected
Logging	logrus, zap, zerolog, or log/slog imports detected
Metrics	Business events, SLO tracking, or counters needed
Crons	robfig/cron, gocron, or scheduled job patterns detected
Profiling	⚠️ Removed in v0.31.0 — do not recommend; see references/profiling.md

Propose: "I recommend setting up Error Monitoring + Tracing [+ Logging if applicable]. Want me to also add Metrics or Crons?"

---

Phase 3: Guide

Install

# Core SDK (always required)
go get github.com/getsentry/sentry-go

# Framework sub-package — install only what matches detected framework:
go get github.com/getsentry/sentry-go/http      # net/http
go get github.com/getsentry/sentry-go/gin       # Gin
go get github.com/getsentry/sentry-go/echo      # Echo
go get github.com/getsentry/sentry-go/fiber     # Fiber
go get github.com/getsentry/sentry-go/fasthttp  # FastHTTP

# Logging sub-packages — install only what matches detected logging lib:
go get github.com/getsentry/sentry-go/logrus    # Logrus
go get github.com/getsentry/sentry-go/slog      # slog (stdlib, Go 1.21+)
go get github.com/getsentry/sentry-go/zap       # Zap
go get github.com/getsentry/sentry-go/zerolog   # Zerolog

# gRPC interceptors (only if google.golang.org/grpc is detected):
go get github.com/getsentry/sentry-go/grpc

# OpenTelemetry bridge (only if OTel is already in use):
go get github.com/getsentry/sentry-go/otel

Quick Start — Recommended Init

Add to main() before any other code. This config enables the most features with sensible defaults:

import (
    "log"
    "os"
    "time"
    "github.com/getsentry/sentry-go"
)

err := sentry.Init(sentry.ClientOptions{
    Dsn:              os.Getenv("SENTRY_DSN"),
    Environment:      os.Getenv("SENTRY_ENVIRONMENT"), // "production", "staging", etc.
    Release:          release,                          // inject via -ldflags at build time
    SendDefaultPII:   true,
    AttachStacktrace: true,

    // Tracing (adjust sample rate for production)
    EnableTracing:    true,
    TracesSampleRate: 1.0, // lower to 0.1–0.2 in high-traffic production

    // Logs
    EnableLogs: true,
})
if err != nil {
    log.Fatalf("sentry.Init: %s", err)
}
defer sentry.Flush(2 * time.Second)

Injecting Release at build time (recommended):

var release string // set by -ldflags

// go build -ldflags="-X main.release=my-app@$(git describe --tags)"

Framework Middleware

After sentry.Init, register the Sentry middleware for your framework:

Framework	Import path	Middleware call	Repanic	WaitForDelivery
net/http	.../sentry-go/http	sentryhttp.New(opts).Handle(h)	true	false
Gin	.../sentry-go/gin	router.Use(sentrygin.New(opts))	true	false
Echo	.../sentry-go/echo	e.Use(sentryecho.New(opts))	true	false
Fiber	.../sentry-go/fiber	app.Use(sentryfiber.New(opts))	false	true
FastHTTP	.../sentry-go/fasthttp	sentryfasthttp.New(opts).Handle(h)	false	true
Iris	.../sentry-go/iris	app.Use(sentryiris.New(opts))	true	false
Negroni	.../sentry-go/negroni	n.Use(sentrynegroni.New(opts))	true	false

Note: Fiber and FastHTTP are built on valyala/fasthttp which has no built-in recovery. Use Repanic: false, WaitForDelivery: true for those.

Hub access in handlers:

// net/http, Negroni:
hub := sentry.GetHubFromContext(r.Context())

// Gin:
hub := sentrygin.GetHubFromContext(c)

// Echo:
hub := sentryecho.GetHubFromContext(c)

// Fiber:
hub := sentryfiber.GetHubFromContext(c)

gRPC Integration

For gRPC servers and clients, use the sentrygrpc interceptors instead:

import sentrygrpc "github.com/getsentry/sentry-go/grpc"

// Server: register interceptors when creating the gRPC server
server := grpc.NewServer(
    grpc.UnaryInterceptor(sentrygrpc.UnaryServerInterceptor()),
    grpc.StreamInterceptor(sentrygrpc.StreamServerInterceptor()),
)

// Client: register interceptors when dialing
conn, err := grpc.NewClient(
    address,
    grpc.WithUnaryInterceptor(sentrygrpc.UnaryClientInterceptor()),
    grpc.WithStreamInterceptor(sentrygrpc.StreamClientInterceptor()),
)

// Hub access inside a gRPC handler:
hub := sentry.GetHubFromContext(ctx)

For Each Agreed Feature

Walk through features one at a time. Load the reference file for each, follow its steps, and verify before moving to the next:

Feature	Reference file	Load when...
Error Monitoring	${SKILL_ROOT}/references/error-monitoring.md	Always (baseline)
Tracing	${SKILL_ROOT}/references/tracing.md	HTTP handlers / distributed tracing
Profiling	${SKILL_ROOT}/references/profiling.md	Performance-sensitive production apps
Logging	${SKILL_ROOT}/references/logging.md	logrus / zap / zerolog / slog detected
Metrics	${SKILL_ROOT}/references/metrics.md	Business KPIs / SLO tracking
Crons	${SKILL_ROOT}/references/crons.md	Scheduler / cron job patterns detected

For each feature: Read ${SKILL_ROOT}/references/<feature>.md, follow steps exactly, verify it works.

---

Configuration Reference

Key ClientOptions Fields

Option	Type	Default	Purpose
Dsn	string	""	SDK disabled if empty; env: SENTRY_DSN
Environment	string	""	e.g., "production"; env: SENTRY_ENVIRONMENT
Release	string	""	e.g., "[email protected]"; env: SENTRY_RELEASE
SendDefaultPII	bool	false	Include IP, request headers
AttachStacktrace	bool	false	Stack traces on CaptureMessage calls
SampleRate	float64	1.0	Error event sample rate (0.0 treated as 1.0)
EnableTracing	bool	false	Enable performance tracing
TracesSampleRate	float64	0.0	Transaction sample rate
TracesSampler	TracesSampler	nil	Custom per-transaction sampling (overrides rate)
EnableLogs	bool	false	Enable Sentry Logs feature
MaxBreadcrumbs	int	100	Max breadcrumbs per event
MaxErrorDepth	int	100	Max depth for unwrapping error chains
Debug	bool	false	Verbose SDK debug output
BeforeSend	func	nil	Hook to mutate/drop error events
BeforeSendTransaction	func	nil	Hook to mutate/drop transaction events
IgnoreErrors	[]string	nil	Regex patterns for errors to drop
IgnoreTransactions	[]string	nil	Regex patterns for transactions to drop

Environment Variables

Variable	Maps to	Purpose
SENTRY_DSN	Dsn	Data Source Name
SENTRY_RELEASE	Release	App version (e.g., [email protected])
SENTRY_ENVIRONMENT	Environment	Deployment environment
HTTP_PROXY / HTTPS_PROXY	HTTPProxy / HTTPSProxy	Outbound proxy

Options set in ClientOptions override environment variables.

---

Verification

Test that Sentry is receiving events:

// In a handler or test — triggers a real error event:
sentry.CaptureMessage("Sentry Go SDK test")

// Or trigger a captured panic (with recovery middleware in place):
panic("sentry test panic")

Check the Sentry dashboard within a few seconds. If nothing appears:

1. Set Debug: true in ClientOptions — prints SDK internals to stdout
2. Verify the DSN is correct and the project exists
3. Ensure sentry.Flush(2 * time.Second) is called (events are async by default)

---

Phase 4: Cross-Link

After completing Go setup, check for a companion frontend missing Sentry coverage:

ls frontend/ web/ client/ ui/ 2>/dev/null
cat frontend/package.json web/package.json 2>/dev/null | grep -E '"react"|"svelte"|"vue"|"next"'

If a frontend directory exists without Sentry configured, suggest the matching skill:

Frontend detected	Suggest skill
React / Next.js	sentry-react-sdk
Svelte / SvelteKit	sentry-svelte-sdk
Vue	Use @sentry/vue — see docs.sentry.io/platforms/javascript/guides/vue/
Other JS/TS	sentry-react-sdk (covers generic browser JS patterns)

---

Troubleshooting

Issue	Solution
Events not appearing	Set Debug: true, check DSN, verify sentry.Flush() is called
sentry.Init returns error	Malformed DSN — check format: https://<key>@o<org>.ingest.sentry.io/<project>
Panics not captured	Ensure framework middleware is registered before handlers
defer sentry.Flush not running	os.Exit() skips defer — call sentry.Flush() explicitly before os.Exit()
Missing stack traces	Set AttachStacktrace: true for CaptureMessage; works automatically for CaptureException
Goroutine events missing context	Clone hub before spawning goroutine: hub := sentry.CurrentHub().Clone()
Too many transactions	Lower TracesSampleRate or use TracesSampler to drop health checks / metrics endpoints
Fiber/FastHTTP not recovering	Use Repanic: false, WaitForDelivery: true for fasthttp-based frameworks
SampleRate: 0.0 sending all events	0.0 is treated as 1.0; to drop all, set Dsn: "" instead