sentry-go-sdk by getsentry/sentry-for-ai
npx skills add https://github.com/getsentry/sentry-for-ai --skill sentry-go-sdk一个智能向导,用于扫描您的 Go 项目并指导您完成完整的 Sentry 设置。
sentry-go、github.com/getsentry/sentry-go 或 Go Sentry SDK注意: 下面的 SDK 版本和 API 反映了撰写时的 Sentry 文档(sentry-go v0.43.0)。在实施前,请务必对照 docs.sentry.io/platforms/go/ 进行验证。
在提出任何建议之前,运行以下命令来了解项目:
# 检查现有的 Sentry 依赖
grep -i sentry go.mod 2>/dev/null
# 检测 Web 框架
grep -E "gin-gonic/gin|labstack/echo|gofiber/fiber|valyala/fasthttp|kataras/iris|urfave/negroni" go.mod 2>/dev/null
# 检测日志库
grep -E "sirupsen/logrus|go.uber.org/zap|rs/zerolog|log/slog" go.mod go.sum 2>/dev/null
# 检测定时任务 / 调度器模式
grep -E "robfig/cron|go-co-op/gocron|jasonlvhit/gocron" go.mod 2>/dev/null
# 检测 OpenTelemetry 使用情况
grep "go.opentelemetry.io" go.mod 2>/dev/null
# 检查配套的前端目录
ls frontend/ web/ client/ ui/ 2>/dev/null
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
需要注意的事项:
go.mod 中是否已存在 sentry-go?如果是,则跳转到阶段 2(配置功能)。根据您的发现,提出具体的建议。不要问开放式问题——直接给出方案:
推荐(核心覆盖范围):
可选(增强可观测性):
references/profiling.md推荐逻辑:
| 功能 | 推荐时机... |
|---|---|
| 错误监控 | 始终 — 不可或缺的基线 |
| 追踪 | 检测到 net/http、gin、echo、fiber 或 gRPC 导入 |
| 日志记录 | 检测到 logrus、zap、zerolog 或 log/slog 导入 |
| 指标 | 需要业务事件、SLO 跟踪或计数器时 |
| 定时任务 | 检测到 robfig/cron、gocron 或计划任务模式 |
| 性能分析 | ⚠️ 已在 v0.31.0 中移除 — 不要推荐;请参见 references/profiling.md |
建议措辞:"我建议设置错误监控 + 追踪 [+ 如果适用,加上日志记录]。您还想添加指标或定时任务监控吗?"
# 核心 SDK(始终需要)
go get github.com/getsentry/sentry-go
# 框架子包 — 仅安装与检测到的框架匹配的包:
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
# 日志记录子包 — 仅安装与检测到的日志库匹配的包:
go get github.com/getsentry/sentry-go/logrus # Logrus
go get github.com/getsentry/sentry-go/slog # slog(标准库,Go 1.21+)
go get github.com/getsentry/sentry-go/zap # Zap
go get github.com/getsentry/sentry-go/zerolog # Zerolog
# OpenTelemetry 桥接器(仅在已使用 OTel 时):
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" 等
Release: release, // 在构建时通过 -ldflags 注入
SendDefaultPII: true,
AttachStacktrace: true,
// 追踪(为生产环境调整采样率)
EnableTracing: true,
TracesSampleRate: 1.0, // 在高流量生产环境中降低到 0.1–0.2
// 日志
EnableLogs: true,
})
if err != nil {
log.Fatalf("sentry.Init: %s", err)
}
defer sentry.Flush(2 * time.Second)
在构建时注入 Release(推荐):
var release string // 由 -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 | 检测到调度器 / 定时任务模式 |
对于每个功能:Read ${SKILL_ROOT}/references/<feature>.md,严格按照步骤操作,验证其是否有效。
ClientOptions 字段| 选项 | 类型 | 默认值 | 用途 |
|---|---|---|---|
Dsn | string | "" | 如果为空则禁用 SDK;环境变量:SENTRY_DSN |
Environment | string | "" | 例如,"production";环境变量:SENTRY_ENVIRONMENT |
Release | string | "" | 例如,"my-app@1.0.0";环境变量: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 日志功能 |
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 | 应用版本(例如,my-app@1.0.0) |
SENTRY_ENVIRONMENT | Environment | 部署环境 |
HTTP_PROXY / HTTPS_PROXY | HTTPProxy / HTTPSProxy | 出站代理 |
在 ClientOptions 中设置的选项会覆盖环境变量。
测试 Sentry 是否正在接收事件:
// 在处理器或测试中 — 触发一个真实的错误事件:
sentry.CaptureMessage("Sentry Go SDK test")
// 或者触发一个被捕获的 panic(在恢复中间件就位的情况下):
panic("sentry test panic")
在几秒钟内检查 Sentry 仪表板。如果没有出现任何内容:
ClientOptions 中设置 Debug: true — 将 SDK 内部信息打印到 stdoutsentry.Flush(2 * time.Second)(事件默认是异步发送的)完成 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: "" |
每周安装量
154
代码仓库
GitHub 星标数
82
首次出现
2026年3月1日
安全审计
安装于
gemini-cli153
cursor153
codex153
github-copilot152
kimi-cli152
opencode152
All Skills > SDK Setup > Go SDK
Opinionated wizard that scans your Go project and guides you through complete Sentry setup.
sentry-go, github.com/getsentry/sentry-go, or Go Sentry SDKNote: SDK versions and APIs below reflect Sentry docs at time of writing (sentry-go v0.43.0). Always verify against docs.sentry.io/platforms/go/ before implementing.
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 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:
sentry-go already in go.mod? If yes, skip to Phase 2 (configure features).Based on what you found, present a concrete recommendation. Don't ask open-ended questions — lead with a proposal:
Recommended (core coverage):
Optional (enhanced observability):
references/profiling.md for alternativesRecommendation logic:
| Feature | Recommend when... |
|---|---|
| Error Monitoring | Always — non-negotiable baseline |
| Tracing | net/http, gin, echo, fiber, or gRPC imports 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?"
# 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
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)
InjectingRelease at build time (recommended):
var release string // set by -ldflags
// go build -ldflags="-X main.release=my-app@$(git describe --tags)"
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 |
Note: Fiber and FastHTTP are built on
valyala/fasthttpwhich has no built-in recovery. UseRepanic: false, WaitForDelivery: truefor 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)
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 |
For each feature: Read ${SKILL_ROOT}/references/<feature>.md, follow steps exactly, verify it works.
ClientOptions Fields| Option | Type | Default | Purpose |
|---|---|---|---|
Dsn | string | "" | SDK disabled if empty; env: SENTRY_DSN |
Environment | string | "" | e.g., "production"; env: |
| Variable | Maps to | Purpose |
|---|---|---|
SENTRY_DSN | Dsn | Data Source Name |
SENTRY_RELEASE | Release | App version (e.g., my-app@1.0.0) |
SENTRY_ENVIRONMENT | Environment | Deployment environment |
Options set in ClientOptions override environment variables.
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:
Debug: true in ClientOptions — prints SDK internals to stdoutsentry.Flush(2 * time.Second) is called (events are async by default)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) |
| 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 explicitly before |
Weekly Installs
154
Repository
GitHub Stars
82
First Seen
Mar 1, 2026
Security Audits
Gen Agent Trust HubPassSocketPassSnykPass
Installed on
gemini-cli153
cursor153
codex153
github-copilot152
kimi-cli152
opencode152
Azure 升级评估与自动化工具 - 轻松迁移 Functions 计划、托管层级和 SKU
104,900 周安装
.../sentry-go/ginrouter.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 |
| Business KPIs / SLO tracking |
| Crons | ${SKILL_ROOT}/references/crons.md | Scheduler / cron job patterns detected |
SENTRY_ENVIRONMENTRelease | string | "" | e.g., "my-app@1.0.0"; 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 |
HTTP_PROXY / HTTPS_PROXY | HTTPProxy / HTTPSProxy | Outbound proxy |
sentry.Flush()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 |