Slogx: Динамический и Безопасный Логгер

Slogx — это продвинутая обертка над стандартным пакетом log/slog в Go (версии 1.21+). Она разработана для систем, где требуется изменять настройки логов (уровень, формат, маскирование) прямо во время работы приложения (runtime) без перезагрузки.

Ключевые возможности

• 🚀 Runtime Конфигурация: Изменение уровня логирования, формата (JSON/Text) и потока вывода на лету через атомарные операции (atomic.Pointer).
• 🛡️ Smart Masking (Redaction): Встроенная поддержка маскирования персональных данных (Email, Карты, Телефоны) с сохранением части данных для отладки.
• 🔍 Context Auto-Injection: Автоматическое извлечение любых полей из context.Context (TraceID, RequestID и т.д.) по списку ключей.
• 🧩 Zero-Dependency: Использует только стандартную библиотеку Go.
• ⚡ Высокая производительность: Оптимизирован для работы под нагрузкой (~500ns на операцию).

---

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

Установка

go get github.com/salivare-io/slogx@latest

Базовый пример

package main

import (
	"context"
	"github.com/salivare-io/slogx"
	"log/slog"
)

func main() {
	// Инициализируем логгер с использованием цепочки правил (Builder)
	log := slogx.New(
		slogx.WithLevel(slogx.LevelTrace),
		slogx.WithContextKeys("trace_id", "request_id"),
		// Используем MaskRules для группировки настроек маскирования
		slogx.WithMaskRules(slogx.NewMaskRules().
			Add("email", slogx.MaskEmail).
			Add("phone", slogx.MaskPhone),
		),
		// Удаление полей
		slogx.WithRemoval(
			slogx.NewRemovalSet().
				Add("password").
				Add("token"),
		),
	)

	// Добавляем данные в контекст
	ctx := context.WithValue(context.Background(), "trace_id", "req-123")

	// Логгер автоматически вытащит trace_id и замаскирует email
	log.InfoContext(ctx, "User login attempt", slog.String("email", "admin@example.com"))
	// Вывод (Text): level=INFO msg="User login attempt" trace_id=req-123 email=ad***m@example.com
}

Глубокая настройка

Динамическое обновление конфига

Вы можете изменить любую настройку логгера атомарно:

log.UpdateConfig(func(c *logger.Config) {
    c.Level = slog.LevelDebug   // Включаем дебаг
    c.Format = logger.FormatJSON // Переключаем на JSON для ELK/Loki
})

Маскирование данных (Data Redaction)

Логгер позволяет защищать чувствительные данные. Вы сами сопоставляете ключи лога с типом маски:

Тип маски	Результат	Описание
MaskEmail	an***h@gmail.com	Первые 2 символа + маска + последний символ
MaskPhone	+7 9*******456	Префикс страны и последние 3 цифры
MaskCard	4276 **** **** 0000	Первый и последний блоки цифр
MaskSecret	[SECRET]	Полное скрытие значения

Удаление полей и хелперы

Гарантируйте отсутствие паролей в логах и используйте типизированные ошибки:

// Удаление полей

logger := slogx.New(
    slogx.WithRemoval(
        slogx.NewRemovalSet().
            Add("password").
            Add("token"),
    ),
)

// Использование хелпера для ошибок
log.Error("db connection failed", logger.Err(err))

Заглушка для тестов

log := slogx.NewNop()

Архитектура проекта

• logger.go — Конструктор, методы Trace/Fatal и управление атомарным конфигом.
• handler.go — DynamicHandler, обеспечивающий работу WithAttrs, WithGroup и подмену формата на лету.
• options.go — Структура Config и все функциональные опции.
• masker.go — Алгоритмы маскирования данных.
• context.go — Работа с context.Context (Getter/Setter/TraceID).
• levels.go — Определение кастомных уровней TRACE и FATAL.

Производительность (Apple M3 Max)

Логгер оптимизирован с использованием внутреннего механизма кэширования статических цепочек хендлеров. Это сводит накладные расходы к минимуму даже при сложных динамических конфигурациях.

Сценарий	Скорость	Память	Аллокации
Простой лог (JSON)	499.2 ns/op	0 B/op	0 allocs/op
С маскированием	733.9 ns/op	112 B/op	5 allocs/op
Обновление конфига (Atomic)	564.3 ns/op	640 B/op	10 allocs/op
Проверка уровня (Пропуск)	3.24 ns/op	0 B/op	0 allocs/op

Сравнение с другими логгерами

Возможность	Стандартный slog	Uber zap	slogx
Динамический уровень	⚠️ (через LevelVar)	✅	✅
Смена формата на лету	❌	❌	✅
Маскирование данных	❌	❌	✅
Извлечение из контекста	❌	❌	✅
Нулевые аллокации	✅	✅	✅ (кэш)
Кастомные Trace/Fatal	❌	✅	✅

Почему именно slogx?

1. Стандартный slog: Очень быстрый, но статичный. Смена формата вывода или правил маскирования требует пересоздания логгера, что небезопасно для потоков без специальных оберток.
2. Uber zap: Мощный и быстрый, но не имеет встроенной интеграции с context.Context для автоматического извлечения полей и не поддерживает смену формата (JSON/Text) для одного и того же экземпляра логгера на лету.
3. slogx: Сочетает скорость zap с гибкостью динамического middleware. Идеально подходит для микросервисов, где нужно включить DEBUG или изменить правила маскирования в продакшене без перезапуска сервиса.

Лицензия

Данный проект распространяется на условиях лицензии MIT.