sentry-go-sdk

所有技能 > SDK 配置 > Go SDK

Sentry Go SDK

一个注重实践的向导，可扫描你的 Go 项目并引导你完成完整的 Sentry 配置。

在以下情况下调用此技能

• 用户要求在 Go 应用中“添加 Sentry”或“配置 Sentry”
• 用户希望在 Go 中进行错误监控、追踪、日志记录、指标监控或 Crons
• 用户提到 sentry-go、github.com/getsentry/sentry-go 或 Go Sentry SDK
• 用户希望监控 Go 中的 panic、HTTP 处理程序或计划任务

注意： 以下 SDK 版本和 API 以撰写本文时的 Sentry 文档为准（sentry-go v0.43.0+）。 从 v0.33.0+ 开始，SDK 要求使用 Go 1.25 或更高版本（支持最新的两个 Go 主版本）。 实施前，请务必参阅 docs.sentry.io/platforms/go/ 进行核实。

---

第 1 阶段：检测

在提出任何建议前，运行以下命令了解项目：

# 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

需要注意的事项：

• sentry-go 是否已在 go.mod 中？如果是，跳到第 2 阶段（配置功能）。
• 项目使用了哪个框架？（这决定了要安装哪个子包和中间件。）
• 使用了哪个日志库？（用于启用自动日志捕获。）
• 是否存在 cron／调度器模式？（这会触发 Crons 建议。）
• 是否有配套的前端目录？（这会触发第 4 阶段的交叉链接。）

---

第 2 阶段：提出建议

根据你发现的情况，给出具体建议。不要提出开放式问题，而要先给出方案：

推荐（核心覆盖）：

• ✅ 错误监控 — 始终启用；捕获 panic 和未处理的错误
• ✅ 追踪 — 检测到 HTTP 处理程序、gRPC 或数据库调用时启用
• ✅ 日志记录 — 检测到 logrus、zap、zerolog 或 slog 时启用

可选（增强可观测性）：

• ⚡ 指标监控 — 用于业务 KPI／SLO 的自定义计数器和仪表
• ⚡ Crons — 检测计划任务中的静默故障
• ⚠️ 性能分析 — 已在 sentry-go v0.31.0 中移除；请参阅 references/profiling.md 了解替代方案

建议逻辑：

功能	建议条件
错误监控	始终 — 不可妥协的基础功能
追踪	检测到 net/http、gin、echo、fiber、gRPC 或数据库调用
日志记录	检测到 logrus、zap、zerolog 或 log/slog 导入
指标监控	需要业务事件、SLO 跟踪或计数器
Crons	检测到 robfig/cron、gocron 或计划任务模式
性能分析	⚠️ 已在 v0.31.0 中移除 — 不要推荐；请参阅 references/profiling.md

提出建议：“我建议配置错误监控 + 追踪［+ 适用时添加日志记录］。要我也添加指标监控或 Crons 吗？”

---

第 3 阶段：引导配置

安装

# 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

快速开始 — 推荐初始化方式

在 main() 中、任何其他代码之前添加。此配置启用了最多的功能，并采用合理的默认值：

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)

在构建时注入 Release（推荐）：

var release string // set by -ldflags

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

框架中间件

调用 sentry.Init 后，为你的框架注册 Sentry 中间件：

框架	导入路径	中间件调用	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

注意： Fiber 和 FastHTTP 基于 valyala/fasthttp 构建，后者没有内置恢复机制。对于这两种框架，请使用 Repanic: false, WaitForDelivery: true。

在处理程序中访问 Hub：

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

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

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

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

gRPC 集成

对于 gRPC 服务端和客户端，请改用 sentrygrpc 拦截器：

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)

对每项已达成共识的功能

逐项处理功能。为每项功能加载参考文件，按其中的步骤操作，并在继续下一项之前进行验证：

功能	参考文件	在以下情况下加载……
错误监控	${SKILL_ROOT}/references/error-monitoring.md	始终加载（基线）
追踪	${SKILL_ROOT}/references/tracing.md	涉及 HTTP 处理程序／分布式追踪时
性能分析	${SKILL_ROOT}/references/profiling.md	涉及对性能敏感的生产应用时
日志记录	${SKILL_ROOT}/references/logging.md	检测到 logrus / zap / zerolog / slog 时
指标	${SKILL_ROOT}/references/metrics.md	涉及业务 KPI／SLO 跟踪时
定时任务	${SKILL_ROOT}/references/crons.md	检测到调度器／cron 作业模式时

对于每项功能：Read ${SKILL_ROOT}/references/<feature>.md，严格按照步骤操作，并验证其是否正常运行。

---

配置参考

ClientOptions 的主要字段

选项	类型	默认值	用途
Dsn	string	""	为空时禁用 SDK；环境变量：SENTRY_DSN
Environment	string	""	例如 "production"；环境变量：SENTRY_ENVIRONMENT
Release	string	""	例如 "[email protected]"；环境变量：SENTRY_RELEASE
SendDefaultPII	bool	false	包含 IP、请求标头
AttachStacktrace	bool	false	在 CaptureMessage 调用中附加堆栈跟踪
SampleRate	float64	1.0	错误事件采样率（0.0 会按 1.0 处理）
EnableTracing	bool	false	启用性能追踪
TracesSampleRate	float64	0.0	事务采样率
TracesSampler	TracesSampler	nil	自定义逐事务采样（优先于采样率）
EnableLogs	bool	false	启用 Sentry Logs 功能
MaxBreadcrumbs	int	100	每个事件的面包屑上限
MaxErrorDepth	int	100	解包错误链的最大深度
Debug	bool	false	输出详细的 SDK 调试信息
BeforeSend	func	nil	用于修改／丢弃错误事件的钩子
BeforeSendTransaction	func	nil	用于修改／丢弃事务事件的钩子
IgnoreErrors	[]string	nil	要丢弃的错误的正则表达式模式
IgnoreTransactions	[]string	nil	要丢弃的事务的正则表达式模式

环境变量

变量	映射到	用途
SENTRY_DSN	Dsn	数据源名称
SENTRY_RELEASE	Release	应用版本（例如 [email protected]）
SENTRY_ENVIRONMENT	Environment	部署环境
HTTP_PROXY / HTTPS_PROXY	HTTPProxy / HTTPSProxy	出站代理

在 ClientOptions 中设置的选项会覆盖环境变量。

---

验证

测试 Sentry 是否正在接收事件：

// 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")

几秒钟后检查 Sentry 控制面板。如果没有任何内容显示：

1. 在 ClientOptions 中设置 Debug: true——SDK 内部信息会输出到标准输出
2. 确认 DSN 正确，且项目存在
3. 确保调用了 sentry.Flush(2 * time.Second)（默认情况下事件为异步发送）

---

阶段 4：交叉链接

完成 Go 设置后，检查是否存在尚未接入 Sentry 的配套前端：

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

如果存在尚未配置 Sentry 的前端目录，请推荐相应的技能：

检测到的前端	推荐技能
React / Next.js	sentry-react-sdk
Svelte / SvelteKit	sentry-svelte-sdk
Vue	使用 @sentry/vue——参阅 docs.sentry.io/platforms/javascript/guides/vue/
其他 JS/TS	sentry-react-sdk（涵盖通用浏览器 JS 模式）

---

故障排除

问题	解决方案
未显示事件	设置 Debug: true，检查 DSN，确认已调用 sentry.Flush()
sentry.Init 返回错误	DSN 格式错误 — 检查格式：https://<key>@o<org>.ingest.sentry.io/<project>
未捕获 Panic	确保在处理程序之前注册框架中间件
defer sentry.Flush 未运行	os.Exit() 会跳过 defer — 在调用 os.Exit() 之前显式调用 sentry.Flush()
缺少堆栈跟踪	为 CaptureMessage 设置 AttachStacktrace: true；CaptureException 会自动启用
Goroutine 事件缺少上下文	在启动 Goroutine 之前克隆 hub：hub := sentry.CurrentHub().Clone()
事务过多	降低 TracesSampleRate，或使用 TracesSampler 丢弃健康检查／指标端点
Fiber/FastHTTP 未恢复	对于基于 fasthttp 的框架，使用 Repanic: false, WaitForDelivery: true
SampleRate: 0.0 仍发送所有事件	0.0 会被视为 1.0；要全部丢弃，请改为设置 Dsn: ""