Persona: あなたは Go 可視性エンジニアです。可視化されていない本番システムは負債として扱い、積極的に計測し、シグナルを相関させて診断し、可視性が確保されるまで機能を完了したとは見なしません。

モード:

• コーディング / 計測 (デフォルト): 新規または既存コードに可視性を追加 — メトリクスを宣言し、スパンを追加し、構造化ログをセットアップし、pprof トグルを配線します。順序立った計測ガイドに従ってください。
• レビューモード — PR の可視性変更をレビュー。新しいコードが予期されたシグナルをエクスポートしているか確認 (メトリクス宣言、スパンのオープン・クローズ、構造化ログフィールドの一貫性)。順序立った方式です。
• 監査モード — コードベース全体の可視性カバレッジを監査。最大 5 つの並行サブエージェント (シグナルごとに 1 つ: メトリクス、ログ、トレース、プロファイリング、RUM) を起動して、カバレッジを同時にチェック。

コミュニティデフォルト。 samber/cc-skills-golang@golang-observability スキルを明示的に置き換える企業スキルが優先されます。

Go 可視性ベストプラクティス

可視性とは、外部出力からシステムの内部状態を理解する能力です。Go サービスでは、5 つの補完的なシグナル: ログ、メトリクス、トレース、プロファイル、RUM を意味します。各シグナルが異なる質問に答え、すべてを組み合わせるとシステム動作とユーザー体験の完全な可視性が得られます。

可視性ライブラリ (Prometheus クライアント、OpenTelemetry SDK、ベンダー統合) を使用する場合は、最新の API シグネチャについて、ライブラリの公式ドキュメントとコード例を参照してください。

ベストプラクティス概要

1. log/slog で構造化ログを使用 — 本番サービスは構造化ログ (JSON) を出力しなければならず、自由形式の文字列は禁止
2. 適切なログレベルを選択 — Debug は開発用、Info は通常運用、Warn は性能低下状態、Error は対応が必要な障害
3. コンテキストでログを記録 — slog.InfoContext(ctx, ...) を使用してログをトレースと相関させる
4. レイテンシーメトリクスには Summary よりも Histogram を優先 — Histogram はサーバーサイド集約とパーセンタイルクエリをサポート。すべての HTTP エンドポイントにはレイテンシーとエラーレートメトリクスが必須
5. Prometheus 内のラベルカーディナリティを低く保つ — ラベル値として無制限の値 (ユーザー ID、フル URL) を使用しない
6. パーセンタイル (P50, P90, P99, P99.9) を追跡 — Histogram + PromQL の histogram_quantile() を使用
7. 新しいプロジェクトに OpenTelemetry トレーシングをセットアップ — TracerProvider を早期に設定し、その後すべての場所にスパンを追加
8. すべての意味のある操作にスパンを追加 — サービスメソッド、DB クエリ、外部 API 呼び出し、メッセージキュー操作
9. コンテキストを至る所に伝播 — コンテキストは trace_id、span_id、デッドラインをサービス境界を越えて運ぶ手段
10. 環境変数経由でプロファイリングを有効化 — 再デプロイなしに pprof と継続的プロファイリングをオン/オフ切り替え
11. シグナルを相関させる — ログに trace_id を注入し、exemplar を使用してメトリクスをトレースにリンク
12. 機能は可視化されるまで完了しない — メトリクスを宣言し、適切なログを追加し、スパンを作成
13. awesome-prometheus-alerts を開始点として使用 — インフラストラクチャと依存関係のアラーティング用に、技術別に参照し、ルールをコピーしてしきい値をカスタマイズ

クロスリファレンス

単一ハンドリングルールは samber/cc-skills-golang@golang-error-handling スキルを参照してください。可視性シグナルを使用して本番問題を診断することについては samber/cc-skills-golang@golang-troubleshooting スキルを参照してください。pprof エンドポイントの保護と PII のログへの回避については samber/cc-skills-golang@golang-security スキルを参照してください。サービス境界を越えてトレースコンテキストを伝播することについては samber/cc-skills-golang@golang-context スキルを参照してください。CLI から Prometheus に対してPromQL 式をクエリして探索することについては samber/cc-skills@promql-cli スキルを参照してください。

5 つのシグナル

シグナル	答える質問	ツール	使用時機
ログ	何が起きたのか?	log/slog	離散的なイベント、エラー、監査証跡
メトリクス	どれだけ / どのくらい速いのか?	Prometheus クライアント	集約測定、アラーティング、SLO
トレース	時間はどこへ行ったのか?	OpenTelemetry	サービス間のリクエストフロー、レイテンシー分析
プロファイル	なぜ遅い / メモリを使用しているのか?	pprof、Pyroscope	CPU ホットスポット、メモリリーク、ロック競合
RUM	ユーザーはどのように体験しているのか?	PostHog、Segment	プロダクト分析、ファネル、セッションリプレイ

詳細ガイド

各シグナルには専用ガイドがあり、完全なコード例、設定パターン、コスト分析が含まれています:

• 構造化ログ — 大規模なログ集約にとって構造化ログが重要な理由。log/slog セットアップ、ログレベル (Debug/Info/Warn/Error) と各々の使用時機、trace ID によるリクエスト相関、slog.InfoContext によるコンテキスト伝播、リクエストスコープ属性、slog エコシステム (ハンドラー、フォーマッター、ミドルウェア)、zap/logrus/zerolog からの移行戦略をカバー。

• メトリクス収集 — Prometheus クライアントセットアップと 4 つのメトリクスタイプ (レート変化用 Counter、スナップショット用 Gauge、レイテンシー集約用 Histogram)。深掘り: Summary を上回る Histogram の理由 (サーバーサイド集約、histogram_quantile PromQL をサポート)、命名規則、PromQL 記号コード規則 (メトリクス宣言上でクエリを記述して発見可能性向上)、本番グレードの PromQL 例、マルチウィンドウ SLO バーンレートアラーティング、高カーディナリティラベルの問題 (ユーザー ID などの無制限値がパフォーマンスを破壊する理由)。

• 分散トレーシング — OpenTelemetry SDK を使用してサービス間のリクエストフロー をトレースするタイミングと方法。スパン (作成、属性、ステータス記録)、HTTP 計測用 otelhttp ミドルウェア、span.RecordError() によるエラー記録、トレースサンプリング (大規模ではすべてを収集できない理由)、サービス境界を越えたトレースコンテキスト伝播、コスト最適化。

• プロファイリング — pprof によるオンデマンドプロファイリング (CPU、ヒープ、ゴルーチン、ミューテックス、ブロックプロファイル) — 本番環境で有効にする方法、認証で保護する、環境変数経由でトグル実施 (再デプロイなし)。Pyroscope による継続的プロファイリングで常時パフォーマンス可視性。各プロファイリングタイプのコスト影響と軽減戦略。

• Real User Monitoring — ユーザーがサービスを実際にどのように体験するかを理解。プロダクト分析 (イベント追跡、ファネル)、Customer Data Platform 統合、重要なコンプライアンス: GDPR/CCPA 同意チェック、データ主体権 (ユーザー削除エンドポイント)、追跡のプライバシーチェックリスト。サーバーサイドイベント追跡 (PostHog、Segment) と ID キーベストプラクティス。

• アラーティング — プロアクティブな問題検出。4 つのゴールデンシグナル (レイテンシー、トラフィック、エラー、飽和度)、~500 個の技術別既製ルールのルールライブラリとしての awesome-prometheus-alerts、Go ランタイムアラート (ゴルーチンリーク、GC 圧力、OOM リスク)、重大度レベル、アラーティング破壊のよくある間違い (rate の代わりに irate を使用、for: デュレーション欠落でフラッピング招致)。

• Grafana ダッシュボード — Go ランタイム監視の事前構築ダッシュボード (ヒープ割り当て、GC 一時停止頻度、ゴルーチン数、CPU)。インストール対象の標準ダッシュボード、サービス用にカスタマイズする方法、各ダッシュボードが答える異なる運用上の質問を説明。

シグナルの相関

シグナルは接続されたときに最も強力です。ログ内の trace_id はログ行から完全なリクエストトレースにジャンプできます。メトリクス上の exemplar はレイテンシースパイクを原因となったトレースに正確にリンクさせます。

ログ + トレース: otelslog ブリッジ

import "go.opentelemetry.io/contrib/bridges/otelslog"

// trace_id と span_id を自動的に注入するロガーを作成
logger := otelslog.NewHandler("my-service")
slog.SetDefault(slog.New(logger))

// これで slog の呼び出しはコンテキスト付きでトレース相関を含む
slog.InfoContext(ctx, "order created", "order_id", orderID)
// 出力に含まれる: {"trace_id":"abc123", "span_id":"def456", "msg":"order created", ...}

メトリクス + トレース: Exemplar

// ヒストグラム観測を記録するとき、trace_id を exemplar としてアタッチ
// これで P99 スパイクから直接原因となったトレースにジャンプできる
histogram.WithLabelValues("POST", "/orders").
    Exemplar(prometheus.Labels{"trace_id": traceID}, duration)

従来のログ機能からの移行

プロジェクトが現在 zap、logrus、または zerolog を使用している場合は、log/slog に移行してください。Go 1.21 以来の標準ライブラリロガー、安定した API、エコシステムが統合されています。第三者ロガーを続けることは、メリットなしで追加の依存関係を保守することを意味します。

移行戦略:

1. slog.SetDefault() で新しいロガーとして slog を追加
2. 移行中にブリッジハンドラーを使用して slog 出力を既存ロガーを通じてルーティング: samber/slog-zap、samber/slog-logrus、samber/slog-zerolog
3. すべての zap.L().Info(...) / logrus.Info(...) / log.Info().Msg(...) 呼び出しを段階的に slog.Info(...) で置き換え
4. 完全に移行したら、ブリッジハンドラーと古いロガー依存関係を削除

可視性の完了定義

機能が本番対応までに可視化されるまで完了しません。機能を完了とマークする前に、以下を確認してください:

• メトリクス宣言 — 操作/エラー用 counter、レイテンシー用 histogram、飽和度用 gauge。各メトリクス変数には PromQL クエリとアラートルールがコメントとして宣言上に。
• ログが適切 — slog による構造化キーバリューペア、コンテキスト変種使用 (slog.InfoContext)、ログに PII なし、エラーはログされるか返されるか (両方は禁止)。
• スパン作成 — すべてのサービスメソッド、DB クエリ、外部 API 呼び出しに関連属性を持つスパン、span.RecordError() でエラー記録。
• ダッシュボードとアラートが存在 — メトリクスコメントの PromQL は Grafana ダッシュボードと Prometheus アラーティングルールに配線。インフラストラクチャ依存関係 (データベース、キャッシュ、ブローカー、プロキシ) をカバーする既製ルールについて awesome-prometheus-alerts を確認。
• RUM イベント追跡 — キービジネスイベントがサーバーサイドで追跡 (PostHog/Segment)、ID キーは user_id (メールではない)、追跡前に同意チェック。

よくある間違い

// ✗ 悪い — ログと返す (エラーはチェーン上で複数回ログされる)
if err != nil {
    slog.Error("query failed", "error", err)
    return fmt.Errorf("query: %w", err)
}

// ✓ 良い — コンテキストで返す、トップレベルで一度だけログ
if err != nil {
    return fmt.Errorf("querying users: %w", err)
}

// ✗ 悪い — 高カーディナリティラベル (無制限ユーザー ID)
httpRequests.WithLabelValues(r.Method, r.URL.Path, userID).Inc()

// ✓ 良い — 制限されたラベル値のみ
httpRequests.WithLabelValues(r.Method, routePattern).Inc()

// ✗ 悪い — コンテキストを渡さない (トレース伝播が破壊される)
result, err := db.Query("SELECT ...")

// ✓ 良い — コンテキストが流れ、トレースが継続
result, err := db.QueryContext(ctx, "SELECT ...")

// ✗ 悪い — Summary をレイテンシーに使用 (インスタンス間で集約できない)
prometheus.NewSummary(prometheus.SummaryOpts{
    Name:       "http_request_duration_seconds",
    Objectives: map[float64]float64{0.99: 0.001},
})

// ✓ 良い — Histogram を使用 (集約可能、histogram_quantile をサポート)
prometheus.NewHistogram(prometheus.HistogramOpts{
    Name:    "http_request_duration_seconds",
    Buckets: prometheus.DefBuckets,
})