sentry-go-sdk

Sentry Go SDK

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

在以下情况下调用此技能

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

注意： 以下 SDK 版本和 API 反映了本文撰写时的 Sentry 文档（sentry-go v0.43.0）。 实施前，请务必对照 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 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

需要记录的信息：

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

---

阶段 2：建议

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

推荐（核心覆盖）：

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

可选（增强可观测性）：

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

建议逻辑：

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

建议这样说：“我建议配置错误监控 + 追踪［+ 适用时添加日志记录］。要我也添加指标监控或定时任务监控吗？”

---

阶段 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

# 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)

对每项已商定的功能

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

功能	参考文件	在以下情况下加载……
错误监控	${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: ""