設定

DD は Config 構造体でロガーの動作を設定し、複数のプリセット設定ファクトリ関数を提供します。

プリセット設定ファクトリ

// デフォルト設定：INFO レベル、テキストフォーマット
cfg := dd.DefaultConfig()

// 開発設定：DEBUG レベル、動的 caller 検出
cfgDev := dd.DevelopmentConfig()

// JSON 設定：JSON フォーマット出力
cfgJSON := dd.JSONConfig()

ファクトリ関数	戻り値の型	レベル	フォーマット	適用シナリオ
DefaultConfig()	Config	Info	Text	本番環境
DevelopmentConfig()	Config	Debug	Text	開発環境
JSONConfig()	Config	Debug	JSON	ログ収集

セキュリティフィルタリングはデフォルトで有効

全てのプリセット設定（DefaultConfig、DevelopmentConfig、JSONConfig）はデフォルトでセキュリティフィルタリングが有効で、パスワード、API Key、クレジットカード番号などの機密データを自動マスキングします。

Config 構造体

type Config struct {
    // ログレベル
    Level          LogLevel         // ログレベル（デフォルト LevelInfo）
    Format         LogFormat        // 出力フォーマット（FormatText / FormatJSON）

    // 時間設定
    TimeFormat     string           // 時間フォーマット（デフォルト ISO 8601）
    IncludeTime    bool             // 時間を含むか（デフォルト true）
    IncludeLevel   bool             // レベルを含むか（デフォルト true）

    // 呼び出し元情報
    DynamicCaller  bool             // 動的呼び出し元検出（デフォルト true）
    FullPath       bool             // フルパスを表示するか（デフォルト false）

    // 出力先
    Targets        []OutputTarget   // 出力先リスト

    // JSON 設定
    JSON           *JSONOptions     // JSON 出力オプション

    // セキュリティ設定
    Security       *SecurityConfig  // セキュリティ設定

    // フィールド検証
    FieldValidation *FieldValidationConfig

    // ライフサイクルハンドラー
    FatalHandler      FatalHandler       // Fatal レベル カスタム処理関数
    WriteErrorHandler WriteErrorHandler  // 書き込みエラーコールバック

    // 拡張性
    ContextExtractors []ContextExtractor // コンテキストエクストラクタリスト
    Hooks             *HookRegistry      // フックレジストリ
    Sampling          *SamplingConfig    // サンプリング設定

    // 監査設定
    Audit             *AuditConfig       // 監査ログ設定（セキュリティイベント）
}

Audit フィールド

Audit を設定すると、機密データのマスキング、レート制限イベント、セキュリティ違反が AuditLogger 経由で監査イベントとして記録されます。監査ログ を参照してください。

Clone

func (c *Config) Clone() Config

設定のコピーを作成し、元の設定に影響を与えずに安全に変更できます。nil レシーバに対してはゼロ値 Config{} を返します。

コピーストラテジ（ソースコード Clone コメントと一致）：

• ディープコピー：Targets（スライス）、JSON（JSONFieldNames を含む）、Security、Hooks、Sampling、Audit
• シャローコピー：FatalHandler、WriteErrorHandler、FieldValidation（関数/ポインタを共有）
• ハイブリッド：ContextExtractors スライスはコピーされるが、エクストラクタインスタンス自体は共有

base := dd.DefaultConfig()
custom := base.Clone()
custom.Level = dd.LevelDebug

Validate

func (c Config) Validate() error

設定の妥当性を検証し、最初に遭遇したエラーを返します。dd.New(cfg) 内部で自動的に呼び出されます；New に渡す前に手動で呼び出して問題を早期発見することもできます。

検証項目：

• Level は [LevelDebug, LevelFatal] の範囲内でなければなりません
• Format は FormatText または FormatJSON でなければなりません
• IncludeTime=true かつ TimeFormat が空でない場合、Go 時間リファレンスレイアウト（time.RFC3339 など）を検証します
• Targets 総数は 100 を超えてはなりません（超過時は ErrMaxWritersExceeded を返します）
• 各 Targets 要素：OutputCustom は nil でない Writer を持つ必要があり、OutputFile は空でない Path を持つ必要があります

cfg := dd.DefaultConfig()
cfg.Level = dd.LevelDebug
if err := cfg.Validate(); err != nil {
    log.Fatal(err)
}

出力先

OutputType

出力先タイプの列挙型。

type OutputType int

定数	値	説明
OutputConsole	0	コンソール出力（stdout）
OutputFile	1	ファイル出力
OutputCustom	2	カスタム Writer

OutputTarget

出力先設定。単一出力先を記述します。

type OutputTarget struct {
    Type       OutputType     // 出力タイプ
    Path       string         // ファイルパス（OutputFile 時に有効）
    MaxSizeMB  int            // ファイルサイズ上限 MB（OutputFile 時に有効）
    MaxBackups int            // バックアップ保持数（OutputFile 時に有効）
    MaxAge     time.Duration  // 古いファイルの保持期間（OutputFile 時に有効）
    Compress   bool           // gzip 圧縮するか（OutputFile 時に有効）
    Writer     io.Writer      // カスタム Writer（OutputCustom 時に有効）
}

出力先コンストラクタ

func ConsoleOutput() OutputTarget
func FileOutput(path string) OutputTarget
func CustomOutput(w io.Writer) OutputTarget

FileOutput のデフォルトローテーションパラメータ

FileOutput が返す OutputTarget にはデフォルトのローテーション値が事前入力されています：MaxSizeMB=100、MaxBackups=10、MaxAge=30 * 24 * time.Hour（30 日）、Compress=false。カスタマイズが必要な場合は戻り値の対応フィールドを直接変更します：

target := dd.FileOutput("logs/app.log")
target.MaxSizeMB = 50               // 50 MB で分割
target.MaxBackups = 5               // 5 個のバックアップを保持
target.MaxAge = 7 * 24 * time.Hour  // 7 日間保持
target.Compress = true              // 古いログを gzip 圧縮

// コンソール出力
cfg.Targets = []dd.OutputTarget{dd.ConsoleOutput()}

// ファイル出力
cfg.Targets = []dd.OutputTarget{dd.FileOutput("logs/app.log")}

// カスタム Writer
cfg.Targets = []dd.OutputTarget{dd.CustomOutput(customWriter)}

// マルチ出力先
cfg.Targets = []dd.OutputTarget{
    dd.ConsoleOutput(),
    dd.FileOutput("logs/app.log"),
}

JSON 設定オプション

JSONOptions

JSON 出力フォーマット設定。

type JSONOptions struct {
    PrettyPrint bool           // 出力を整形するか（デフォルト false）
    Indent      string         // インデント文字列（デフォルト "  "）
    FieldNames  *JSONFieldNames // カスタム JSON フィールド名
}

JSONFieldNames

JSON 出力のフィールド名をカスタマイズ。異なるログ収集システムへの適応に使用します。

type JSONFieldNames struct {
    Timestamp string  // タイムスタンプフィールド名（デフォルト "timestamp"）
    Level     string  // レベルフィールド名（デフォルト "level"）
    Caller    string  // 呼び出し元フィールド名（デフォルト "caller"）
    Message   string  // メッセージフィールド名（デフォルト "message"）
    Fields    string  // フィールドコンテナ名（デフォルト "fields"）
}

ポインタレシーバメソッド (*JSONFieldNames).IsComplete() bool を実装しています。5 つのフィールド名がすべて空でない場合に true を返し、すべてのフィールド名が完全にカスタマイズされているかを検証するために使用できます。

使用例：

cfg := dd.DefaultJSONOptions()
cfg.FieldNames = &dd.JSONFieldNames{
    Timestamp: "ts",
    Level:     "lvl",
    Message:   "msg",
}

DefaultJSONOptions

func DefaultJSONOptions() *JSONOptions

デフォルトの JSONOptions 出力オプションを返します：デフォルトでは整形出力せず（インデントは 2 つのスペース）、フィールド名はデフォルト値を使用します。

opts := dd.DefaultJSONOptions()
opts.PrettyPrint = true

logger, _ := dd.New(dd.Config{
    Format: dd.FormatJSON,
    JSON:   opts,
})

SamplingConfig

サンプリング設定。高スループット環境でログ量を削減するために使用します。

type SamplingConfig struct {
    Enabled    bool          // サンプリングを有効にするか
    Initial    int           // サンプリング前に常に記録するメッセージ数
    Thereafter int           // サンプリング率（値が 10 の場合、10 件に 1 件を記録）
    Tick       time.Duration // カウンターのリセット間隔（0 はリセットなし）
}

cfg := dd.DefaultConfig()
cfg.Sampling = &dd.SamplingConfig{
    Enabled:    true,
    Initial:    100,
    Thereafter: 10,
    Tick:       time.Minute,
}
logger, _ := dd.New(cfg)

FieldValidationConfig

フィールド検証設定。フィールドキー名の命名規則を制御します。

type FieldValidationConfig struct {
    Mode                     FieldValidationMode      // 検証モード
    Convention               FieldNamingConvention    // 命名規則
    AllowCommonAbbreviations bool                      // 一般的な略語（ID、URL など）を許可
    EnableSecurityValidation bool                      // セキュリティ検証を有効化（Log4Shell、ホモグラフ攻撃など）
}

FieldValidationMode

定数	説明
FieldValidationNone	検証を無効化（デフォルト）
FieldValidationWarn	非準拠フィールドを警告するが受け付ける
FieldValidationStrict	非準拠時は stderr にエラーを出力（ログエントリは拒否されずそのまま書き込まれます）

String() メソッドを実装し、モード名を返します。

FieldNamingConvention

定数	説明	例
NamingConventionAny	任意のフォーマットを受け付け（デフォルト）	-
NamingConventionSnakeCase	snake_case	user_id, created_at
NamingConventionCamelCase	camelCase	userId, createdAt
NamingConventionPascalCase	PascalCase	UserId, CreatedAt
NamingConventionKebabCase	kebab-case	user-id, created-at

String() メソッドを実装し、命名規則名を返します。

ValidateFieldKey

func (c *FieldValidationConfig) ValidateFieldKey(key string) error

フィールドキー名が設定された命名規則に準拠しているか検証します。

フィールド検証設定

DefaultFieldValidationConfig

func DefaultFieldValidationConfig() *FieldValidationConfig

デフォルト設定：検証は無効。

StrictSnakeCaseConfig

func StrictSnakeCaseConfig() *FieldValidationConfig

厳格 snake_case 検証。フィールド名は snake_case フォーマットでなければなりません。

StrictCamelCaseConfig

func StrictCamelCaseConfig() *FieldValidationConfig

厳格 camelCase 検証。フィールド名は camelCase フォーマットでなければなりません。

使用方法

logger, _ := dd.New(dd.Config{
    Level:           dd.LevelInfo,
    FieldValidation: dd.StrictSnakeCaseConfig(),
})

// 有効
logger.InfoWith("ok", dd.String("user_name", "admin"))

// 命名非準拠（snake_case ではない、ログは依然書き込まれ、エラーは stderr に出力）
logger.InfoWith("fail", dd.String("userName", "admin"))

設定例

本番環境

logger, _ := dd.New(dd.Config{
    Level:  dd.LevelInfo,
    Format: dd.FormatJSON,
    Targets: []dd.OutputTarget{
        dd.ConsoleOutput(),
        dd.FileOutput("logs/app.log"),
    },
    Security: dd.DefaultSecurityConfig(),
})

開発環境

logger, _ := dd.New(dd.DevelopmentConfig())

マルチ出力先

logger, _ := dd.New(dd.Config{
    Level: dd.LevelInfo,
    Targets: []dd.OutputTarget{
        dd.ConsoleOutput(),
        dd.FileOutput("logs/app.log"),
    },
})

次のステップ

• Logger -- 設定を使用してロガーを作成
• 出力先 -- FileWriter、BufferedWriter、MultiWriter
• セキュリティフィルタ -- SecurityConfig 詳解
• フックシステム -- HooksConfig 詳解
• 監査ログ -- AuditConfig 詳解