sentry-go-sdk

すべてのスキル > SDK のセットアップ > Go SDK

Sentry Go SDK

Go プロジェクトをスキャンし、Sentry のセットアップを最後まで案内する、推奨設定を備えたウィザードです。

このスキルを使う場面

• ユーザーが Go アプリへの「Sentry の追加」や「Sentry のセットアップ」を依頼した場合
• ユーザーが Go でのエラー監視、トレース、ログ記録、メトリクス、またはクロンを求めている場合
• ユーザーが sentry-go、github.com/getsentry/sentry-go、または Go Sentry SDK に言及した場合
• ユーザーが Go でパニック、HTTP ハンドラー、またはスケジュールされたジョブを監視したい場合

注： 以下の SDK バージョンと API は、執筆時点の Sentry ドキュメント（sentry-go v0.43.0 以降）に基づいています。 v0.33.0 以降、SDK には Go 1.25 以降が必要です（直近 2 つの Go メジャーバージョンをサポートしています）。 実装前に必ず 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 gRPC
grep "google.golang.org/grpc" 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、または DB 呼び出しが検出された場合
ログ記録	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

# gRPC interceptors (only if google.golang.org/grpc is detected):
go get github.com/getsentry/sentry-go/grpc

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

gRPC の統合

gRPC サーバーとクライアントには、代わりに sentrygrpc インターセプターを使用します。

import sentrygrpc "github.com/getsentry/sentry-go/grpc"

// Server: register interceptors when creating the gRPC server
server := grpc.NewServer(
    grpc.UnaryInterceptor(sentrygrpc.UnaryServerInterceptor()),
    grpc.StreamInterceptor(sentrygrpc.StreamServerInterceptor()),
)

// Client: register interceptors when dialing
conn, err := grpc.NewClient(
    address,
    grpc.WithUnaryInterceptor(sentrygrpc.UnaryClientInterceptor()),
    grpc.WithStreamInterceptor(sentrygrpc.StreamClientInterceptor()),
)

// Hub access inside a gRPC handler:
hub := sentry.GetHubFromContext(ctx)

合意した各機能について

機能を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 の追跡
Cron	${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 の内部情報が stdout に出力されます
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: "" を設定します