Быстрый старт

1. Создание логгера

DD предоставляет множество удобных конструкторов для различных сценариев:

package main

import (
    "log"

    "github.com/cybergodev/dd"
)

func main() {
    // Способ 1: Глобальный логгер по умолчанию (нулевая конфигурация)
    dd.Info("Использование глобального логгера")

    // Способ 2: Режим разработки (уровень DEBUG, с caller)
    dev, err := dd.New(dd.DevelopmentConfig())
    if err != nil {
        log.Fatal(err)
    }
    defer dev.Close()
    dev.Info("Вывод в режиме разработки")

    // Способ 3: Вывод в файл
    file, err := dd.New(dd.Config{
        Targets: []dd.OutputTarget{dd.FileOutput("logs/app.log")},
    })
    if err != nil {
        log.Fatal(err)
    }
    defer file.Close()
    file.Info("Вывод в файл")

    // Способ 4: Одновременный вывод в консоль и файл
    all, err := dd.New(dd.Config{
        Targets: []dd.OutputTarget{
            dd.ConsoleOutput(),
            dd.FileOutput("logs/app.log"),
        },
    })
    if err != nil {
        log.Fatal(err)
    }
    defer all.Close()
    all.Info("Вывод в две цели")

    // Способ 5: Двойной вывод в формате JSON
    jsonLogger, err := dd.New(dd.Config{
        Format: dd.FormatJSON,
        Targets: []dd.OutputTarget{
            dd.ConsoleOutput(),
            dd.FileOutput("logs/app.json"),
        },
    })
    if err != nil {
        log.Fatal(err)
    }
    defer jsonLogger.Close()
    jsonLogger.Info("Вывод в формате JSON")
}

Ловушка нулевого Config

Выше способы 3/4/5 используют литерал dd.Config{...} напрямую, явно задавая только Targets/Format, остальные поля остаются нулевыми: Level=Debug (без фильтрации), IncludeTime=false (без временной метки), IncludeLevel=false (без уровня), DynamicCaller=false (без caller), Security=nil (откатывается к DefaultSecurityConfig() — базовая фильтрация остаётся включённой, около 36 категорий маскирования; чтобы отключить, явно укажите &dd.SecurityConfig{} или SecurityLevelDevelopment). В выводе будут отсутствовать временная метка, уровень и другая ключевая информация.

Рекомендация для production: используйте dd.DefaultConfig() как основу и изменяйте нужные поля — это сразу даёт временную метку, уровень, caller и фильтрацию безопасности по умолчанию:

cfg := dd.DefaultConfig()                 // Level=Info, Format=Text, со временем/уровнем/caller/Security
cfg.Targets = []dd.OutputTarget{dd.FileOutput("logs/app.log")}
logger, err := dd.New(cfg)

Аналогично dd.DevelopmentConfig() (DEBUG+caller) и dd.JSONConfig() (DEBUG+JSON+RFC3339) — готовые отправные точки с полным набором полей.

2. Уровни логирования

DD поддерживает 5 уровней логирования, от низшего к высшему:

dd.Debug("Отладочная информация")   // LevelDebug
dd.Info("Общая информация")    // LevelInfo (по умолчанию)
dd.Warn("Предупреждение")    // LevelWarn
dd.Error("Ошибка")   // LevelError
dd.Fatal("Фатальная ошибка")   // LevelFatal (вызывает os.Exit)

Форматированные версии:

dd.Debugf("Пользователь %s вошёл, затрачено %dмс", name, elapsed)
dd.Infof("Запрос обработан: status=%d", status)
dd.Warnf("Использование пула соединений %d%%", usage)
dd.Errorf("Ошибка запроса к БД: %v", err)

3. Структурированное логирование

Используйте типобезопасные конструкторы полей:

dd.InfoWith("Запрос обработан",
    dd.String("method", "GET"),
    dd.String("path", "/api/users"),
    dd.Int("status", 200),
    dd.Duration("elapsed", 150*time.Millisecond),
)

Пример вывода (текстовый формат по умолчанию):

[2026-04-16T21:16:48+08:00   INFO] main.go:13 Запрос обработан method=GET path=/api/users status=200 elapsed=150ms

Подсказка

Вывод в формате JSON Глобальный логгер по умолчанию использует текстовый формат. Для вывода в формате JSON используйте dd.New(dd.JSONConfig()) для создания логгера с форматом JSON.

4. Цепочная передача полей

// Создание Entry с предустановленными полями
requestLogger := dd.WithFields(
    dd.String("service", "api-gateway"),
    dd.String("version", "1.0.0"),
)

// Каждый лог автоматически несёт предустановленные поля
requestLogger.Info("Сервис запущен")
requestLogger.InfoWith("Маршруты зарегистрированы",
    dd.Int("routes", 42),
)

5. Ротация файлов

Настройка стратегии ротации через FileWriter:

// По умолчанию 100МБ, 30 дней, 10 резервных копий
fwCfg := dd.DefaultFileWriterConfig()
fwCfg.MaxBackups = 3
fwCfg.MaxSizeMB = 1
fwCfg.Compress = true

fw, err := dd.NewFileWriter("logs/app.log", fwCfg)
if err != nil {
    log.Fatal(err)
}
logger, err := dd.New(dd.Config{
    Level: dd.LevelInfo,
    Targets: []dd.OutputTarget{dd.CustomOutput(fw)},
})
if err != nil {
    log.Fatal(err)
}
defer logger.Close()

logger.Info("hello world")

6. Фильтрация конфиденциальных данных

DD по умолчанию включает базовую фильтрацию конфиденциальных данных (автоматическое маскирование паролей, API-ключей, номеров кредитных карт и т.д.):

// Конфигурация по умолчанию уже включает базовую фильтрацию безопасности
logger, err := dd.New(dd.DefaultConfig())
if err != nil {
    log.Fatal(err)
}
defer logger.Close()

// Поле password автоматически маскируется
logger.InfoWith("Пользователь вошёл",
    dd.String("username", "admin"),
    dd.String("password", "s3cr3t"),  // Вывод: [REDACTED]
)

Следующие шаги

• Основные концепции -- понимание архитектуры Logger и конвейера обработки
• Структурированное логирование -- подробное описание использования полей
• Вывод в файл и ротация -- подробное описание FileWriter
• Фильтрация конфиденциальных данных -- практикум по фильтрации безопасности
• Шпаргалка -- краткий справочник по API