Golang错误日志接入Sentry监控指南

初始化 Sentry 必须检查 sentry.Init 返回错误并配置 Environment 和 Release，否则错误将静默丢失或无法按环境过滤；DSN 需完整协议和域名，panic 捕获须用 recover + CurrentHub().Recover，error 应保持原始类型和 stack trace。

初始化 Sentry 客户端时必须调用 sentry.Init 且不能忽略返回错误

很多人直接写 sentry.Init(...) 就完事，但这个函数会返回 error，比如 DSN 格式错误、网络不通、Sentry 服务端拒绝连接时都会失败。一旦初始化失败，后续所有 sentry.CaptureException 都静默丢弃，日志看起来“没报错”，实则根本没发出去。

• 务必检查返回值：if err := sentry.Init(...); err != nil { log.Fatal(err) }
• DSN 必须带协议（https://）、公钥、项目 ID 和域名，形如 https://abc123@o123456.ingest.sentry.io/1234567；少一个斜杠或拼错域名都失败
• 本地开发建议加 Debug: true 参数，它会让 Sentry 在控制台打印发送状态和错误原因，比盲猜快得多

捕获 panic 要用 recover + sentry.CurrentHub().Recover，不是直接 sentry.CaptureException

Go 的 panic 不是普通 error，sentry.CaptureException 只接受 error 类型。如果在 defer 里直接传 panic 值（通常是 interface{}），Sentry 收到的是空堆栈或无法解析的结构。

• 标准做法是在 defer 中 recover()，然后用 sentry.CurrentHub().Recover(r) —— 它能自动提取 panic 值、生成完整堆栈、关联当前 trace
• 别自己转成 errors.New(fmt.Sprint(r))，会丢失原始类型和 stack trace
• 注意：如果用了 sentry.Flush 做优雅退出，recover 后必须等 flush 完再 exit，否则 panic 日志可能被截断

sentry.CaptureException 的 error 必须是原始 error，不要包装多次

Sentry 的 Go SDK 对 error 包装链敏感。用 fmt.Errorf("xxx: %w", err) 没问题，但若混用 errors.Wrap（来自 github.com/pkg/errors）或自定义 error 类型，可能导致堆栈解析失败或 message 被截断。

• 优先用 Go 1.13+ 原生 %w 语法包装，Sentry 能正确展开嵌套 error 的 message 和 stack
• 避免在中间层把 error 转成字符串再包成新 error（如 errors.New("failed: " + err.Error())），这会砍掉所有 stack 和 cause 链
• HTTP handler 中常见错误：用 sentry.CaptureException(err) 前，确认 err 不是 nil；nil 传进去不会报错，但 Sentry 后台收不到任何内容

设置 Environment 和 Release 才能在 Sentry 控制台有效过滤

默认所有事件都打到 production 环境、无 release 版本，结果就是 dev、staging、prod 的错误混在一起，根本分不清哪个环境出的问题，也无法关联 source map 或 commit。

• 初始化时必须显式设：Environment: os.Getenv("ENV")（值建议用 dev/staging/production）
• Release 推荐用 Git commit SHA（git rev-parse --short HEAD），不要用 v1.2.3 这类 tag —— tag 可能对应多个 commit，Sentry 无法精准匹配
• 如果用 Docker 部署，确保构建时把 RELEASE 和 ENV 注入为环境变量，而不是硬编码在代码里

最常被跳过的其实是 sentry.Init 的返回值检查和 Environment 配置 —— 其他都可能“看起来工作”，但这俩一漏，你就在 Sentry 里永远找不到自己的错误。