Конфигурация

DD использует конфигурацию на основе структур (Config) с поддержкой автодополнения в IDE — не нужны цепочки билдеров или функции-опции. Это руководство охватывает все поля конфигурации и распространённые комбинации.

Справочник по API: см. Config для полного списка полей.

Три пресета

Пресет	Уровень	Формат	Фильтр безопасности	Типичное использование
`DefaultConfig()`	Info	Текст	✅ Базовый	По умолчанию для production
`DevelopmentConfig()`	Debug	Текст (короткое время)	✅ Базовый	Локальная разработка
`JSONConfig()`	Debug	JSON (RFC3339)	✅ Базовый	Системы агрегации логов

Предупреждение Фильтр безопасности включён по умолчанию

Все три пресета включают базовую фильтрацию конфиденциальных данных (пароли, API-ключи, номера кредитных карт и т.д.). Даже в режиме разработки она остаётся включённой — чтобы своевременно выявлять случайные утечки конфиденциальных данных. Для отключения явно установите Security: &dd.SecurityConfig{} или используйте SecurityLevelDevelopment.

Обзор полей Config

type Config struct {
    // ─── Базовое ───
    Level         LogLevel     // Уровень логирования (LevelDebug ~ LevelFatal)
    Format        LogFormat    // Формат вывода (FormatText / FormatJSON)
    TimeFormat    string       // Формат времени (по умолчанию ISO 8601)
    IncludeTime   bool         // Включать временную метку
    IncludeLevel  bool         // Включать уровень логирования

    // ─── Информация о вызывающем ───
    DynamicCaller bool         // Динамическое определение вызывающего (file:line)
    FullPath      bool         // Использовать полный путь к файлу (по умолчанию: только имя файла)

    // ─── Целевые назначения вывода ───
    Targets       []OutputTarget // Целевые назначения вывода (ConsoleOutput/FileOutput/CustomOutput)

    // ─── Настройка формата ───
    JSON          *JSONOptions // Настройки JSON-формата (имена полей, отступы и т.д.)

    // ─── Безопасность ───
    Security      *SecurityConfig       // Конфигурация безопасности (фильтрация, ограничение частоты)
    FieldValidation *FieldValidationConfig // Проверка именования ключей Field

    // ─── Жизненный цикл ───
    FatalHandler      FatalHandler      // Пользовательский обработчик Fatal
    WriteErrorHandler WriteErrorHandler // Callback при ошибке записи

    // ─── Расширения ───
    ContextExtractors []ContextExtractor // Экстракторы Field из контекста
    Hooks             *HookRegistry      // Хуки жизненного цикла
    Sampling          *SamplingConfig    // Сэмплирование логов

    // ─── Аудит ───
    Audit             *AuditConfig       // Логирование аудита безопасности
}

Настройка целевых назначений вывода

Используйте ConsoleOutput(), FileOutput(), CustomOutput() для создания целевых назначений вывода:

package main

import (
    "log"
    "os"

    "github.com/cybergodev/dd"
)

func main() {
    cfg := dd.DefaultConfig()
    cfg.Targets = []dd.OutputTarget{
        dd.ConsoleOutput(),                          // Консоль
        dd.FileOutput("logs/app.log"),               // Файл (по умолчанию 100МБ/10 резервных копий/30 дней)
        dd.CustomOutput(os.Stderr),                  // Пользовательский Writer
    }

    // Пользовательские параметры ротации файлов
    fileTarget := dd.FileOutput("logs/app.log")
    fileTarget.MaxSizeMB = 50     // Ротация при 50МБ
    fileTarget.MaxBackups = 5     // Хранить 5 резервных копий
    fileTarget.MaxAge = 7 * 24    // Хранить 7 дней

    logger, err := dd.New(cfg)
    if err != nil {
        log.Fatal(err)
    }
    defer logger.Close()
}

Подсказка Подводный камень нулевого значения Config

Использование dd.Config{Targets: ...} напрямую пропускает временные метки, уровень и информацию о вызывающем. Всегда начинайте с dd.DefaultConfig() и изменяйте нужные поля.

Настройка JSON-формата

cfg := dd.JSONConfig()

// Пользовательские имена полей JSON
cfg.JSON = &dd.JSONOptions{
    PrettyPrint: true,
    Indent:      "  ",
    FieldNames: &dd.JSONFieldNames{
        Timestamp: "@timestamp",
        Level:     "severity",
        Message:   "msg",
        Caller:    "source",
        Fields:    "ctx",
    },
}