ペルソナ: あなたはGoログアーキテクトです。すべてのレコードが正しいハンドラーを通過するログパイプラインを設計します — サンプリングが早期にノイズをドロップし、フォーマッターがプロセスを離れる前にPIIを削除し、ルーターがエラーをSentryに、情報をLokiに送信します。

samber/slog-**** — Go用構造化ログパイプライン

Go 1.21以上向けの20以上の組み合わせ可能なslog.Handlerパッケージ。3つのコアパイプラインライブラリに加えて、HTTPミドルウェアとバックエンドシンク（すべて標準slog.Handlerインターフェースを実装）があります。

公式リソース:

• github.com/samber/slog-multi — ハンドラー合成
• github.com/samber/slog-sampling — スループット制御
• github.com/samber/slog-formatter — 属性変換

このスキルは完全ではありません。詳細についてはライブラリドキュメントとコード例を参照してください。Context7は発見可能性プラットフォームとしてサポートできます。

パイプラインモデル

すべてのsamber/slogパイプラインは標準的な順序に従います。レコードは左から右へフローします — サンプリングを最初に配置して早期にドロップし、到達しないレコードのためにCPUを無駄にしないようにします。

record → [Sampling] → [Pipe: trace/PII] → [Router] → [Sinks]

順序が重要です：サンプリングをフォーマッティング前に行うとCPUを節約します。フォーマッティングをルーティング前に行うと、すべてのシンクがクリーンな属性を受け取ります。この順序を逆にするとドロップされるレコードに対して無駄な作業が生じます。

コアライブラリ

ライブラリ	用途	主なコンストラクタ
slog-multi	ハンドラー合成	Fanout, Router, FirstMatch, Failover, Pool, Pipe
slog-sampling	スループット制御	UniformSamplingOption, ThresholdSamplingOption, AbsoluteSamplingOption, CustomSamplingOption
slog-formatter	属性変換	PIIFormatter, ErrorFormatter, FormatByType[T], FormatByKey, FlattenFormatterMiddleware

slog-multi — ハンドラー合成

異なるルーティングニーズ向けの6つの合成パターン：

パターン	動作	レイテンシ影響
Fanout(handlers...)	すべてのハンドラーに順序立てて放送	すべてのハンドラーレイテンシの合計
Router().Add(h, predicate).Handler()	マッチするすべてのハンドラーへルーティング	マッチするハンドラーの合計
Router().Add(...).FirstMatch().Handler()	最初にマッチしたハンドラーのみにルーティング	単一ハンドラーレイテンシ
Failover()(handlers...)	成功するまで順序立てて試行	プライマリハンドラーレイテンシ（成功時）
Pool()(handlers...)	すべてのハンドラーに並行放送	すべてのハンドラーレイテンシの最大値
Pipe(middlewares...).Handler(sink)	シンク前のミドルウェアチェーン	ミドルウェアオーバーヘッド+シンク

// エラーをSentryにルーティング、すべてのログを標準出力に
logger := slog.New(
    slogmulti.Router().
        Add(sentryHandler, slogmulti.LevelIs(slog.LevelError)).
        Add(slog.NewJSONHandler(os.Stdout, nil)).
        Handler(),
)

組み込みプレディケート：LevelIs, LevelIsNot, MessageIs, MessageIsNot, MessageContains, MessageNotContains, AttrValueIs, AttrKindIs。

すべてのパターンの完全なコード例については、Pipeline Patternsを参照してください。

slog-sampling — スループット制御

戦略	動作	最適用途
Uniform	すべてのレコードの固定%をドロップ	開発/ステージングノイズ削減
Threshold	間隔あたり最初のN件をログ、その後レートRでサンプリング	本番環境 — 初期可視性を保持
Absolute	間隔あたり全体でNレコードにキャップ	ハードコスト管理
Custom	ユーザー関数がレコードごとのサンプリングレートを返す	レベル対応またはタイム対応ルール

サンプリングはパイプラインの最も外側のハンドラーである必要があります — フォーマッティング後に配置するとドロップされるレコードのためにCPUを無駄にします。

// Threshold: 5秒あたり最初の10件、その後10% — エラーはルーターを介して常に通過
logger := slog.New(
    slogmulti.
        Pipe(slogsampling.ThresholdSamplingOption{
            Tick: 5 * time.Second, Threshold: 10, Rate: 0.1,
        }.NewMiddleware()).
        Handler(innerHandler),
)

マッチャーは重複排除のための類似レコードをグループ化します：MatchByLevel(), MatchByMessage(), MatchByLevelAndMessage()（デフォルト）, MatchBySource(), MatchByAttribute(groups, key)。

戦略比較と設定詳細については、Sampling Strategiesを参照してください。

slog-formatter — 属性変換

Pipeミドルウェアとして適用して、すべての下流ハンドラーがクリーンな属性を受け取るようにします。

logger := slog.New(
    slogmulti.Pipe(slogformatter.NewFormatterMiddleware(
        slogformatter.PIIFormatter("user"),          // PIIフィールドをマスク
        slogformatter.ErrorFormatter("error"),       // 構造化エラー情報
        slogformatter.IPAddressFormatter("client"),  // IPアドレスをマスク
    )).Handler(slog.NewJSONHandler(os.Stdout, nil)),
)

主なフォーマッター：PIIFormatter, ErrorFormatter, TimeFormatter, UnixTimestampFormatter, IPAddressFormatter, HTTPRequestFormatter, HTTPResponseFormatter。汎用フォーマッター：FormatByType[T], FormatByKey, FormatByKind, FormatByGroup, FormatByGroupKey。ネストされた属性をフラット化するにはFlattenFormatterMiddlewareを使用します。

HTTPミドルウェア

フレームワーク全体での一貫したパターン：router.Use(slogXXX.New(logger))。

利用可能：slog-gin, slog-echo, slog-fiber, slog-chi, slog-http（net/http）。

すべてConfig構造体を共有：DefaultLevel, ClientErrorLevel, ServerErrorLevel, WithRequestBody, WithResponseBody, WithUserAgent, WithRequestID, WithTraceID, WithSpanID, Filters。

// フィルター付きGin — ヘルスチェックをスキップ
router.Use(sloggin.NewWithConfig(logger, sloggin.Config{
    DefaultLevel:     slog.LevelInfo,
    ClientErrorLevel: slog.LevelWarn,
    ServerErrorLevel: slog.LevelError,
    WithRequestBody:  true,
    Filters: []sloggin.Filter{
        sloggin.IgnorePath("/health", "/metrics"),
    },
}))

フレームワーク固有のセットアップについては、HTTP Middlewaresを参照してください。

バックエンドシンク

すべてがOption{}.NewXxxHandler()コンストラクタパターンに従います。

カテゴリ	パッケージ
Cloud	slog-datadog, slog-sentry, slog-loki, slog-graylog
Messaging	slog-kafka, slog-fluentd, slog-logstash, slog-nats
Notification	slog-slack, slog-telegram, slog-webhook
Storage	slog-parquet
Bridges	slog-zap, slog-zerolog, slog-logrus

バッチハンドラーは適切なシャットダウンが必要です — slog-datadog, slog-loki, slog-kafka, slog-parquetは内部でレコードをバッファリングします。シャットダウン時にフラッシュしてください（例：Datadogのhandler.Stop(ctx)、LokiのlokiClient.Stop()、Kafkaのwriter.Close()）またはバッファリングされたログが失われます。

設定例とシャットダウンパターンについては、Backend Handlersを参照してください。

よくある間違い

間違い	失敗理由	修正
フォーマッティング後のサンプリング	ドロップされるレコードをフォーマッティングするCPUを無駄にする	サンプリングを最も外側のハンドラーとして配置
多くの同期ハンドラーへのFanout	呼び出し元をブロック — レイテンシはすべてのハンドラーの合計	並行ディスパッチにPool()を使用
バッチハンドラーでのシャットダウンフラッシュの欠落	バッファリングされたログはシャットダウンで失われる	defer handler.Stop(ctx)（Datadog）、defer lokiClient.Stop()（Loki）、defer writer.Close()（Kafka）
デフォルト/キャッチオールハンドラーなしのRouter	マッチしないレコードは暗黙的にドロップ	プレディケートなしのハンドラーをキャッチオールとして追加
HTTPミドルウェアなしのAttrFromContext	コンテキストに抽出するリクエスト属性がない	まずslog-gin/echo/fiber/chiミドルウェアをインストール
ミドルウェアなしのPipeの使用	ノーオップラッパーがレコードごとのオーバーヘッドを追加	ミドルウェアが不要な場合はPipe()を削除

パフォーマンス警告

• Fanoutレイテンシ = すべてのハンドラーレイテンシの合計（順序立て）。それぞれ10msの5つのハンドラーでは、すべてのログ呼び出しに50msかかります。レイテンシを最大値に削減するにはPool()を使用してください
• Pipeミドルウェアはレコードごとの関数呼び出しオーバーヘッドを追加します — チェーンは短く保ってください（2-4ミドルウェア）
• slog-formatterは属性を順序立てて処理します — 多くのフォーマッターが複合します。ホットパス属性フォーマッティングの場合、代わりにあなたのタイプにslog.LogValuerを実装することを好みます
• ベンチマーク本番展開前にgo test -benchでパイプラインを測定してください

診断: パイプラインのレコードごとの割り当てとレイテンシを測定し、チェーン内のどのハンドラーが最も割り当てるかを特定してください。

ベストプラクティス

1. 最初にサンプリング、次にフォーマッティング、最後にルーティング — この標準的な順序は無駄な作業を最小化し、すべてのシンクがクリーンなデータを見ることを保証します
2. 横断的な関心事にはPipeを使用 — トレースID挿入とPIIスクラビングはハンドラーごとのロジックではなくミドルウェアに属します
3. slogmulti.NewHandleInlineHandlerでパイプラインをテスト — 実際のシンクなしで各段階に到達するレコードをアサート
4. AttrFromContextを使用してリクエストスコープの属性をHTTPミドルウェアからすべてのハンドラーに伝播
5. FanoutよりもRouterを優先ハンドラーが異なるレコードサブセットを必要とする場合 — ルーターはプレディケートを評価し、マッチしないハンドラーをスキップします

クロスリファレンス

• → slog基礎（レベル、コンテキスト、ハンドラーセットアップ、マイグレーション）についてsamber/cc-skills-golang@golang-observabilityスキルを参照
• → ログリターンルールについてsamber/cc-skills-golang@golang-error-handlingスキルを参照
• → ログのPIIハンドリングについてsamber/cc-skills-golang@golang-securityスキルを参照
• → samber/oopsを使用した構造化エラーコンテキストについてsamber/cc-skills-golang@golang-samber-oopsスキルを参照

samber/slog-* パッケージのバグまたは予期しない動作に遭遇した場合、関連するリポジトリでissueを作成してください（例：slog-multi/issues, slog-sampling/issues）。