Go ロギング

基本原則

ログはオペレーターのためのものであり、開発者のためではありません。すべてのログ行は、本番環境の問題を診断するのに役立つべきです。その目的を果たさないなら、それはノイズです。

---

ロガーの選択

規範的: 新しい Go コードには log/slog を使用してください。

slog は構造化され、レベル付けされ、標準ライブラリに含まれています (Go 1.21+)。本番ロギングのニーズの大多数をカバーします。

どのロガーを使う?
├─ 新しい本番コード      → log/slog
├─ 簡単な CLI / 一度限り  → log (標準)
└─ 測定で確認されたパフォーマンスボトルネック → zerolog または zap (まずベンチマーク)

プロファイリングで slog がホットパスのボトルネックであることが示されない限り、サードパーティのロギングライブラリを導入しないでください。導入する場合は、同じ構造化キー値スタイルを維持してください。

slog ハンドラの設定、JSON/テキスト出力の構成、または log.Printf から slog への移行を行う場合は、references/LOGGING-PATTERNS.md を参照してください。

---

構造化ロギング

規範的: 常にキー値ペアを使用してください。メッセージ文字列に値を挿入しないでください。

メッセージは、何が起こったかの静的な説明です。動的データはキー値属性に入ります:

// 良い例: 静的なメッセージ、構造化フィールド
slog.Info("order placed", "order_id", orderID, "total", total)

// 悪い例: メッセージ文字列に焼き込まれた動的データ
slog.Info(fmt.Sprintf("order %d placed for $%.2f", orderID, total))

キー命名

助言的: ログ属性キーには snake_case を使用してください。

キーは小文字でアンダースコア区切りであり、コードベース全体で一貫していることが必要です: user_id, request_id, elapsed_ms。

型付き属性

パフォーマンスクリティカルなパスの場合は、型付きコンストラクタを使用してアロケーションを回避します:

slog.LogAttrs(ctx, slog.LevelInfo, "request handled",
    slog.String("method", r.Method),
    slog.Int("status", code),
    slog.Duration("elapsed", elapsed),
)

ログパフォーマンスの最適化や Enabled() での事前チェック時は、references/LEVELS-AND-CONTEXT.md を参照してください。

---

ログレベル

助言的: これらのレベルセマンティクスに一貫して従ってください。

レベル	使用するとき	本番環境デフォルト
Debug	開発者のみの診断、内部状態のトレーシング	無効
Info	注目すべきライフサイクルイベント: 起動、シャットダウン、設定読み込み	有効
Warn	予期しないが復旧可能: 非推奨機能の使用、リトライ成功	有効
Error	操作失敗、オペレーター対応が必要	有効

経験則:

• 誰も対応する必要がなければ、Error ではなく Warn または Info を使用してください
• デバッガを接続した場合のみ有用な場合は、Debug を使用してください
• slog.Error には常に "err" 属性が含まれるべきです

slog.Error("payment failed", "err", err, "order_id", id)
slog.Warn("retry succeeded", "attempt", n, "endpoint", url)
slog.Info("server started", "addr", addr)
slog.Debug("cache lookup", "key", key, "hit", hit)

Warn と Error の区別やカスタム詳細度レベルの定義については、references/LEVELS-AND-CONTEXT.md を参照してください。

---

リクエストスコープログ

助言的: コンテキストからロガーを派生させて、リクエストスコープフィールドを保持します。

ミドルウェアを使用してロガーをリクエスト ID、ユーザー ID、またはトレース ID で充実させ、充実されたロガーをコンテキストまたは明示的なパラメータを通じて下流に渡します:

func middleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        logger := slog.With("request_id", requestID(r))
        ctx := context.WithValue(r.Context(), loggerKey, logger)
        next.ServeHTTP(w, r.WithContext(ctx))
    })
}

そのリクエスト内の後続のすべてのログ呼び出しは request_id を自動的に保持します。

ロギングミドルウェアの実装またはコンテキストを通じたロガーの受け渡しについては、references/LOGGING-PATTERNS.md を参照してください。

---

ログまたは返却、両方ではなく

規範的: 各エラーを正確に 1 回処理します — ログするか返却するか、どちらかです。

エラーをログしてからそれを返却すると、呼び出し元がスタック上で同様に処理するため、重複ノイズが生じます。

// 悪い例: ここでログされ、スタック上のすべての呼び出し元でもログされる
if err != nil {
    slog.Error("query failed", "err", err)
    return fmt.Errorf("query: %w", err)
}

// 良い例: ラップして返却 — 呼び出し元が判断させる
if err != nil {
    return fmt.Errorf("query: %w", err)
}

例外: HTTP ハンドラおよびその他のスタック上位の境界は、詳細なエラーをサーバー側でログしながら、サニタイズされたメッセージをクライアントに返却することができます:

if err != nil {
    slog.Error("checkout failed", "err", err, "user_id", uid)
    http.Error(w, "internal error", http.StatusInternalServerError)
    return
}

ハンドル一度パターンとエラーラッピングガイダンスの完全については、go-error-handling を参照してください。

---

ログを取らないもの

規範的: シークレット、認証情報、PII、または高カーディナリティ無制限データを決してログに取らないでください。

• パスワード、API キー、トークン、セッション ID
• クレジットカード番号全体、SSN
• ユーザーデータを含むリクエスト/レスポンスボディ
• 無制限サイズのスライスまたはマップ全体

ログ属性に含めるのが安全なデータを決定する場合は、references/LEVELS-AND-CONTEXT.md を参照してください。

---

クイックリファレンス

する	しない
slog.Info("msg", "key", val)	log.Printf("msg %v", val)
静的メッセージ + 構造化フィールド	メッセージ内の fmt.Sprintf
snake_case キー	camelCase または一貫性のないキー
エラーをログするか返却する	同じエラーをログしかつ返却する
コンテキストからロガーを派生させる	呼び出しごとに新しいロガーを作成する
"err" 属性を使用して slog.Error を使用する	エラーに対して slog.Info を使用する
ホットパス上で Enabled() を事前チェックする	常にログ引数を割り当てる

---

関連スキル

• エラーハンドリング: エラーをログするか返却するかの判断、またはハンドル一度パターンについては、go-error-handling を参照してください
• コンテキスト伝播: コンテキストを通じてリクエストスコープ値 (ロガーを含む) を渡すときは、go-context を参照してください
• パフォーマンス: ホットパスロギングの最適化またはログ呼び出しのアロケーション削減については、go-performance を参照してください
• コードレビュー: Go PR でのロギング慣行のレビュー時は、go-code-review を参照してください