Go 项目接入 Sentry SDK：按框架…

适用于为 Go 应用安装和配置 Sentry SDK，覆盖 net/http、Gin、Echo、Fiber、FastHTTP、Iris、Negroni、gRPC 及常见日志库、OpenTelemetry 和定时任务。

适用场景

解决思路

1. 检测项目：运行 `grep -i sentry go.mod 2>/dev/null` 检查是否已有 Sentry 依赖；若已有 sentry-go，跳到配置功能阶段。
2. 检测 Web 框架：运行 `grep -E "gin-gonic/gin|labstack/echo|gofiber/fiber|valyala/fasthttp|kataras/iris|urfave/negroni" go.mod 2>/dev/null`。
3. 检测 gRPC：运行 `grep "google.golang.org/grpc" go.mod 2>/dev/null`。
4. 检测日志库：运行 `grep -E "sirupsen/logrus|go.uber.org/zap|rs/zerolog|log/slog" go.mod go.sum 2>/dev/null`。
5. 检测 cron / 调度器：运行 `grep -E "robfig/cron|go-co-op/gocron|jasonlvhit/gocron" go.mod 2>/dev/null`。
6. 检测 OpenTelemetry：运行 `grep "go.opentelemetry.io" go.mod 2>/dev/null`。
7. 检查配套前端：运行 `ls frontend/ web/ client/ ui/ 2>/dev/null`。
8. 记录检测结论：是否已存在 sentry-go、使用哪个 Web 框架、使用哪个日志库、是否有 cron / 调度器、是否有配套前端目录。
9. 注意版本：sentry-go v0.43.0+；v0.33.0+ 要求 Go 1.25 或更高，并支持最近两个 Go 大版本；实现前始终对照 docs.sentry.io/platforms/go/ 验证。
10. 推荐核心覆盖：Error Monitoring 总是推荐，用于捕获 panic 和未处理错误。
11. 推荐核心覆盖：若检测到 HTTP handlers、gRPC 或 DB 调用，推荐 Tracing。
12. 推荐核心覆盖：若检测到 logrus、zap、zerolog 或 slog，推荐 Logging。
13. 推荐可选增强：若有业务 KPI / SLO 或自定义计数器需求，推荐 Metrics。
14. 推荐可选增强：若检测到调度器 / 定时任务模式，推荐 Crons 以发现静默失败。
15. 不要推荐 Profiling：它在 sentry-go v0.31.0 中已移除；查看 references/profiling.md 了解替代方案。
16. 推荐话术：提出“我建议配置 Error Monitoring + Tracing [+ 如适用 Logging]。是否还要添加 Metrics 或 Crons？”
17. 安装核心 SDK：运行 `go get github.com/getsentry/sentry-go`。
18. 安装匹配的框架子包：net/http 用 `go get github.com/getsentry/sentry-go/http`。
19. 安装匹配的框架子包：Gin 用 `go get github.com/getsentry/sentry-go/gin`。
20. 安装匹配的框架子包：Echo 用 `go get github.com/getsentry/sentry-go/echo`。
21. 安装匹配的框架子包：Fiber 用 `go get github.com/getsentry/sentry-go/fiber`。
22. 安装匹配的框架子包：FastHTTP 用 `go get github.com/getsentry/sentry-go/fasthttp`。
23. 安装匹配的日志子包：Logrus 用 `go get github.com/getsentry/sentry-go/logrus`。
24. 安装匹配的日志子包：slog 用 `go get github.com/getsentry/sentry-go/slog`。
25. 安装匹配的日志子包：Zap 用 `go get github.com/getsentry/sentry-go/zap`。
26. 安装匹配的日志子包：Zerolog 用 `go get github.com/getsentry/sentry-go/zerolog`。
27. 若检测到 `google.golang.org/grpc`，安装 gRPC interceptors：`go get github.com/getsentry/sentry-go/grpc`。
28. 若已使用 OpenTelemetry，安装 OTel bridge：`go get github.com/getsentry/sentry-go/otel`。
29. Quick Start：在 `main()` 中、其他代码之前调用 `sentry.Init`。
30. 初始化配置：Dsn 取 `SENTRY_DSN`，Environment 取 `SENTRY_ENVIRONMENT`，Release 取 `release`；设置 SendDefaultPII: true、AttachStacktrace: true、EnableTracing: true、TracesSampleRate: 1.0、EnableLogs: true；生产高流量将 TracesSampleRate 降到 0.1–0.2。
31. 处理 Init 错误：若 `sentry.Init` 返回错误，用 `log.Fatalf` 记录并退出。
32. 确保刷新：调用 `defer sentry.Flush(2 * time.Second)`。
33. 构建时注入 Release：声明 `var release string // set by -ldflags`，用 `go build -ldflags="-X main.release=my-app@$(git describe --tags)"`。
34. 框架中间件：net/http 使用 `sentryhttp.New(opts).Handle(h)`，Repanic=true，WaitForDelivery=false。
35. 框架中间件：Gin 使用 `router.Use(sentrygin.New(opts))`，Repanic=true，WaitForDelivery=false。
36. 框架中间件：Echo 使用 `e.Use(sentryecho.New(opts))`，Repanic=true，WaitForDelivery=false。
37. 框架中间件：Fiber 使用 `app.Use(sentryfiber.New(opts))`，Repanic=false，WaitForDelivery=true。
38. 框架中间件：FastHTTP 使用 `sentryfasthttp.New(opts).Handle(h)`，Repanic=false，WaitForDelivery=true。
39. 框架中间件：Iris 使用 `app.Use(sentryiris.New(opts))`，Repanic=true，WaitForDelivery=false。
40. 框架中间件：Negroni 使用 `n.Use(sentrynegroni.New(opts))`，Repanic=true，WaitForDelivery=false。
41. Fiber / FastHTTP 注意：它们基于 valyala/fasthttp 且无内置 recovery，所以使用 `Repanic: false, WaitForDelivery: true`。
42. 在 handler 中获取 Hub：net/http、Negroni 用 `hub := sentry.GetHubFromContext(r.Context())`。
43. 在 handler 中获取 Hub：Gin 用 `hub := sentrygin.GetHubFromContext(c)`。
44. 在 handler 中获取 Hub：Echo 用 `hub := sentryecho.GetHubFromContext(c)`。
45. 在 handler 中获取 Hub：Fiber 用 `hub := sentryfiber.GetHubFromContext(c)`。
46. gRPC 集成：导入路径为 `github.com/getsentry/sentry-go/grpc`，别名为 `sentrygrpc`。
47. gRPC 服务端：创建 server 时注册 `grpc.UnaryInterceptor(sentrygrpc.UnaryServerInterceptor())` 和 `grpc.StreamInterceptor(sentrygrpc.StreamServerInterceptor())`。
48. gRPC 客户端：调用 `grpc.NewClient(address, grpc.WithUnaryInterceptor(sentrygrpc.UnaryClientInterceptor()), grpc.WithStreamInterceptor(sentrygrpc.StreamClientInterceptor()))`。
49. gRPC handler 中获取 Hub：`hub := sentry.GetHubFromContext(ctx)`。
50. 逐项处理已同意的功能：一次只处理一个功能，加载对应 reference 文件，按步骤执行，并在下一个功能前验证。
51. 加载 Error Monitoring 参考：始终读取 `${SKILL_ROOT}/references/error-monitoring.md` 并遵循步骤。
52. 加载 Tracing 参考：HTTP handlers / 分布式追踪时读取 `${SKILL_ROOT}/references/tracing.md`。
53. 加载 Profiling 参考：性能敏感生产应用读取 `${SKILL_ROOT}/references/profiling.md`。
54. 加载 Logging 参考：检测到 logrus / zap / zerolog / slog 时读取 `${SKILL_ROOT}/references/logging.md`。
55. 加载 Metrics 参考：业务 KPI / SLO 追踪时读取 `${SKILL_ROOT}/references/metrics.md`。
56. 加载 Crons 参考：检测到 scheduler / cron job 模式时读取 `${SKILL_ROOT}/references/crons.md`。
57. 对每个功能：执行 `Read ${SKILL_ROOT}/references/<feature>.md`，严格遵循步骤并验证。
58. 配置 ClientOptions：`Dsn` 默认空字符串，为空则 SDK 禁用，环境变量 `SENTRY_DSN`。
59. 配置 ClientOptions：`Environment` 默认空字符串，例如 production，环境变量 `SENTRY_ENVIRONMENT`。
60. 配置 ClientOptions：`Release` 默认空字符串，例如 `my-app@1.0.0`，环境变量 `SENTRY_RELEASE`。
61. 配置 ClientOptions：`SendDefaultPII` 默认 false，是否包含 IP、请求头。
62. 配置 ClientOptions：`AttachStacktrace` 默认 false，为 `CaptureMessage` 附加堆栈。
63. 配置 ClientOptions：`SampleRate` 默认 1.0，错误事件采样率，0.0 会被当作 1.0。
64. 配置 ClientOptions：`EnableTracing` 默认 false，启用性能追踪。
65. 配置 ClientOptions：`TracesSampleRate` 默认 0.0，事务采样率。
66. 配置 ClientOptions：`TracesSampler` 默认 nil，自定义每事务采样，覆盖 rate。
67. 配置 ClientOptions：`EnableLogs` 默认 false，启用 Sentry Logs。
68. 配置 ClientOptions：`MaxBreadcrumbs` 默认 100，每事件最大 breadcrumbs。
69. 配置 ClientOptions：`MaxErrorDepth` 默认 100，展开错误链最大深度。
70. 配置 ClientOptions：`Debug` 默认 false，输出 SDK 详细调试信息。
71. 配置 ClientOptions：`BeforeSend` 默认 nil，用于修改 / 丢弃错误事件。
72. 配置 ClientOptions：`BeforeSendTransaction` 默认 nil，用于修改 / 丢弃事务事件。
73. 配置 ClientOptions：`IgnoreErrors` 默认 nil，正则匹配要丢弃的错误。
74. 配置 ClientOptions：`IgnoreTransactions` 默认 nil，正则匹配要丢弃的事务。
75. 环境变量映射：`SENTRY_DSN` -> `Dsn`。
76. 环境变量映射：`SENTRY_RELEASE` -> `Release`。
77. 环境变量映射：`SENTRY_ENVIRONMENT` -> `Environment`。
78. 环境变量映射：`HTTP_PROXY` / `HTTPS_PROXY` -> `HTTPProxy` / `HTTPSProxy`。
79. 注意：`ClientOptions` 中设置的选项会覆盖环境变量。
80. 验证：在 handler 或测试中调用 `sentry.CaptureMessage` 传入 `Sentry Go SDK test` 触发真实错误事件。
81. 验证：或在已启用 recovery 中间件时触发 `panic` 并传入 `sentry test panic`。
82. 验证：数秒内检查 Sentry dashboard；若没有事件，设置 `Debug: true` 查看 SDK 内部输出。
83. 验证：检查 DSN 正确且项目存在。
84. 验证：确保调用了 `sentry.Flush(2 * time.Second)`，因为事件默认异步。
85. Phase 4 交叉链接：Go 设置完成后检查配套前端是否缺少 Sentry 覆盖：运行 `ls frontend/ web/ client/ ui/ 2>/dev/null`。
86. Phase 4 交叉链接：运行 `cat frontend/package.json web/package.json 2>/dev/null | grep -E '"react"|"svelte"|"vue"|"next"'`。
87. 若存在前端目录但未配置 Sentry，建议匹配技能：React / Next.js 用 `sentry-react-sdk`。
88. 若 Svelte / SvelteKit，建议 `sentry-svelte-sdk`。
89. 若 Vue，使用 `@sentry/vue`，参见 docs.sentry.io/platforms/javascript/guides/vue/。
90. 若其他 JS / TS，建议 `sentry-react-sdk`（覆盖通用浏览器 JS 模式）。
91. 排错：事件不出现 -> 设置 `Debug: true`，检查 DSN，验证调用了 `sentry.Flush()`。
92. 排错：`sentry.Init` 返回错误 -> DSN 格式错误，检查格式 `https://<key>@o<org>.ingest.sentry.io/<project>`。
93. 排错：panic 未被捕获 -> 确保框架中间件在 handler 之前注册。
94. 排错：`defer sentry.Flush` 未运行 -> `os.Exit()` 会跳过 defer，在 `os.Exit()` 前显式调用 `sentry.Flush()`。
95. 排错：缺少堆栈跟踪 -> 为 `CaptureMessage` 设置 `AttachStacktrace: true`；`CaptureException` 自动可用。
96. 排错：goroutine 事件缺少上下文 -> 启动 goroutine 前克隆 hub：`hub := sentry.CurrentHub().Clone()`。
97. 排错：事务过多 -> 降低 `TracesSampleRate` 或使用 `TracesSampler` 丢弃 health checks / metrics endpoints。
98. 排错：Fiber / FastHTTP 未恢复 -> 对基于 fasthttp 的框架使用 `Repanic: false, WaitForDelivery: true`。
99. 排错：`SampleRate: 0.0` 发送所有事件 -> 0.0 被视为 1.0；要全部丢弃，改设 Dsn 为空字符串。

适用边界 · 注意事项

• 没有 Sentry 项目、DSN 或不允许把数据发送到 Sentry 时不要使用。
• Go 版本不满足 sentry-go v0.33.0+ 要求（Go 1.25 或更高）时先升级或核实兼容性。
• 需要 Sentry Profiling 时不适用，因为它在 sentry-go v0.31.0 已移除，需查看替代方案。