sentry-go-sdk

Sentry Go SDK

Go プロジェクトをスキャンし、Sentry の完全なセットアップを案内する、意見を反映したウィザードです。

このスキルを使用するタイミング

• ユーザーが Go アプリへの「Sentry の追加」や「Sentry のセットアップ」を依頼した場合
• ユーザーが Go でエラー監視、トレーシング、ログ記録、メトリクス、または Crons を利用したい場合
• ユーザーが sentry-go、github.com/getsentry/sentry-go、または Go Sentry SDK に言及した場合
• ユーザーが Go でパニック、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

確認する項目：

• sentry-go がすでに go.mod に含まれていますか？含まれている場合は、フェーズ 2（機能の設定）に進みます。
• 使用しているフレームワークは何ですか？（インストールするサブパッケージとミドルウェアが決まります。）
• 使用しているログライブラリは何ですか？（ログの自動キャプチャが有効になります。）
• cron／スケジューラーのパターンはありますか？（Crons の推奨につながります。）
• 併設されたフロントエンドのディレクトリはありますか？（フェーズ 4 の相互リンクにつながります。）

---

フェーズ 2：推奨

確認した内容に基づき、具体的な推奨事項を提示します。自由回答式の質問は避け、提案を先に示します。

推奨（基本的なカバレッジ）：

• ✅ エラー監視 — 常に推奨します。パニックと未処理のエラーをキャプチャします。
• ✅ トレーシング — HTTP ハンドラー、gRPC、または DB 呼び出しが検出された場合に推奨します。
• ✅ ログ記録 — 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

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

合意した各機能について

機能を1つずつ順に確認します。それぞれの参照ファイルを読み込み、記載された手順に従って、次に進む前に動作を確認してください。

機能	参照ファイル	読み込む条件
エラーモニタリング	${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>
パニックが捕捉されない	ハンドラーより前にフレームワークのミドルウェアが登録されていることを確認します
defer sentry.Flush が実行されない	os.Exit() は defer をスキップします。os.Exit() の前に sentry.Flush() を明示的に呼び出してください
スタックトレースがない	CaptureMessage では AttachStacktrace: true を設定します。CaptureException では自動的に機能します
Goroutine イベントにコンテキストがない	Goroutine を起動する前にハブを複製します：hub := sentry.CurrentHub().Clone()
トランザクションが多すぎる	TracesSampleRate を下げるか、TracesSampler を使用してヘルスチェック／メトリクスのエンドポイントを除外します
Fiber/FastHTTP が復旧しない	fasthttp ベースのフレームワークでは Repanic: false, WaitForDelivery: true を使用します
SampleRate: 0.0 を設定してもすべてのイベントが送信される	0.0 は 1.0 として扱われます。すべてを除外するには、代わりに Dsn: "" を設定します