PrimaLogger 1.1.0

PrimaLogger

Обёртка над Serilog для упрощения конфигурации логирования с поддержкой файлов, консоли и Elasticsearch.

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

Значения по умолчанию

ConsoleLoggerOptions

new ConsoleLoggerOptions()

FileLoggerOptions

new FileLoggerOptions()

ElasticsearchLoggerOptions

new ElasticsearchLoggerOptions()

ElasticsearchBufferOptions

new ElasticsearchBufferOptions()

ElasticsearchSinkOptions

new ElasticsearchSinkOptions()

PrimaLoggerConfig

new PrimaLoggerConfig()

Важно: При new PrimaLoggerConfig() все синки отключены по умолчанию. Нужно явно настроить нужные синки или использовать presets:

// Все синки отключены
services.AddPrimaLogger(config => { });

// Включить только консоль с настройками по умолчанию
services.AddPrimaLogger(config => 
{
    config.Console = new ConsoleLoggerOptions(); // Enabled=true, Information, стандартный template
});

// Или использовать готовые presets
services.AddPrimaLogger(config => PrimaLoggerConfig.Development("MyApp"));

Минимальная конфигурация

Через код:

services.AddPrimaLogger(config =>
{
    config.Console = new ConsoleLoggerOptions();
});

Через appsettings.json:

{
  "Logging": {
    "PrimaLogger": {
      "Console": {
        "Enabled": true,
        "MinimumLevel": "Information"
      }
    }
  }
}

Полная конфигурация

Через код:

services.AddPrimaLogger(config =>
{
    config.ApplicationName = "MyWebApp";
    
    // Консоль - только важные сообщения
    config.Console = new ConsoleLoggerOptions
    {
        MinimumLevel = LogLevel.Information,
        OutputTemplate = "[{Timestamp:HH:mm:ss} {Level:u3}] {Message:lj}{NewLine}{Exception}"
    };
    
    // Файл - детальное логирование
    config.File = new FileLoggerOptions
    {
        Path = "logs/app-.log",
        MinimumLevel = LogLevel.Debug,
        OutputTemplate = "{Timestamp:yyyy-MM-dd HH:mm:ss.fff zzz} [{Level:u3}] [{ThreadId}] {SourceContext}: {Message:lj}{NewLine}{Exception}",
        RollingInterval = RollingInterval.Day,
        FileSizeLimitBytes = 100 * 1024 * 1024, // 100MB
        RetainedFileCountLimit = 30
    };
    
    // Отдельный файл для ошибок
    config.ErrorFile = new FileLoggerOptions
    {
        Path = "logs/errors-.log",
        MinimumLevel = LogLevel.Error,
        RollingInterval = RollingInterval.Day,
        RetainedFileCountLimit = 90
    };
    
    // Elasticsearch - все логи
    config.Elasticsearch = new ElasticsearchSinkOptions
    {
        MinimumLevel = LogLevel.Verbose,
        Options = new ElasticsearchLoggerOptions
        {
            Nodes = { new Uri("http://localhost:9200") },
            DataStreamName = "logs-mywebapp-prod",
            ApiKey = "your-api-key",
            BootstrapMethod = BootstrapMethod.Silent,
            BufferOptions = ElasticsearchBufferOptions.HighThroughput()
        }
    };
    
    // Дополнительные свойства для всех логов
    config.CustomProperties.Add("Environment", "Production");
    config.CustomProperties.Add("Version", "1.0.0");
});

Через appsettings.json:

{
  "Logging": {
    "PrimaLogger": {
      "ApplicationName": "MyWebApp",
      "CustomProperties": {
        "Environment": "Production",
        "Version": "1.0.0"
      },
      "Console": {
        "Enabled": true,
        "MinimumLevel": "Information",
        "OutputTemplate": "[{Timestamp:HH:mm:ss} {Level:u3}] {Message:lj}{NewLine}{Exception}"
      },
      "File": {
        "Path": "logs/app-.log",
        "MinimumLevel": "Debug",
        "OutputTemplate": "{Timestamp:yyyy-MM-dd HH:mm:ss.fff zzz} [{Level:u3}] [{ThreadId}] {SourceContext}: {Message:lj}{NewLine}{Exception}",
        "RollingInterval": "Day",
        "FileSizeLimitBytes": 104857600,
        "RetainedFileCountLimit": 30,
        "RollOnFileSizeLimit": true,
        "Shared": false
      },
      "ErrorFile": {
        "Path": "logs/errors-.log",
        "MinimumLevel": "Error",
        "RollingInterval": "Day",
        "RetainedFileCountLimit": 90
      },
      "Elasticsearch": {
        "MinimumLevel": "Verbose",
        "Options": {
          "Nodes": ["http://localhost:9200"],
          "DataStreamName": "logs-mywebapp-prod",
          "ApiKey": "your-api-key",
          "BootstrapMethod": "Silent",
          "BufferOptions": {
            "ConcurrentConsumers": 4,
            "InboundBufferMaxSize": 500000,
            "OutboundBufferMaxSize": 5000
          }
        }
      }
    }
  }
}

Output Template - Форматирование вывода

Основные переменные

Форматирование переменных

Timestamp - Время

{Timestamp:yyyy-MM-dd HH:mm:ss}     // 2024-01-15 14:30:25
{Timestamp:HH:mm:ss.fff}            // 14:30:25.123
{Timestamp:dd/MM/yyyy}              // 15/01/2024
{Timestamp:yyyy-MM-dd HH:mm:ss.fff zzz}  // 2024-01-15 14:30:25.123 +03:00

Level - Уровень логирования

{Level}           // Information
{Level:u3}        // INF (верхний регистр, 3 символа)
{Level:w3}        // Inf (первая заглавная, 3 символа)
{Level:t3}        // inf (нижний регистр, 3 символа)
{Level:u4}        // INFO (верхний регистр, 4 символа)

Message - Сообщение

{Message}         // Обычный вывод
{Message:lj}      // Literal JSON (безопасный для JSON)
{Message:j}       // JSON escaping

Готовые шаблоны

Консоль - простой

"[{Level:u3}] {Message:lj}{NewLine}{Exception}"

Вывод:

[INF] User logged in successfully
[ERR] Database connection failed

Консоль - подробный

"[{Timestamp:HH:mm:ss} {Level:u3}] {Message:lj}{NewLine}{Exception}"

Вывод:

[14:30:25 INF] User logged in successfully
[14:30:26 ERR] Database connection failed

Файл - стандартный

"{Timestamp:yyyy-MM-dd HH:mm:ss.fff zzz} [{Level:u3}] {Message:lj}{NewLine}{Exception}"

Вывод:

2024-01-15 14:30:25.123 +03:00 [INF] User logged in successfully
2024-01-15 14:30:26.456 +03:00 [ERR] Database connection failed

Файл - с контекстом

"{Timestamp:yyyy-MM-dd HH:mm:ss.fff zzz} [{Level:u3}] [{ThreadId}] {SourceContext}: {Message:lj}{NewLine}{Exception}"

Вывод:

2024-01-15 14:30:25.123 +03:00 [INF] [1] MyApp.Controllers.UserController: User logged in successfully
2024-01-15 14:30:26.456 +03:00 [ERR] [5] MyApp.Services.DatabaseService: Database connection failed

Файл - максимальный контекст

"{Timestamp:yyyy-MM-dd HH:mm:ss.fff zzz} [{Level:u3}] [{Application}] [{Environment}] [{ThreadId}] [{ProcessId}] {SourceContext}: {Message:lj}{NewLine}{Exception}"

Вывод:

2024-01-15 14:30:25.123 +03:00 [INF] [MyWebApp] [Production] [1] [1234] MyApp.Controllers.UserController: User logged in successfully

Примеры конфигураций

Разработка - только консоль и файл

services.AddPrimaLogger(config =>
{
    config.Console = new ConsoleLoggerOptions
    {
        MinimumLevel = LogLevel.Debug,
        OutputTemplate = "{Timestamp:HH:mm:ss.fff} [{Level:u3}] {SourceContext}: {Message:lj}{NewLine}{Exception}"
    };
    
    config.File = new FileLoggerOptions
    {
        Path = "logs/debug-.log",
        MinimumLevel = LogLevel.Debug,
        RollingInterval = RollingInterval.Hour,
        FileSizeLimitBytes = 50 * 1024 * 1024,
        RetainedFileCountLimit = 48
    };
});

Продакшн - все синки с разными уровнями

services.AddPrimaLogger(config =>
{
    config.Console = new ConsoleLoggerOptions
    {
        MinimumLevel = LogLevel.Warning, // Только предупреждения и ошибки
        OutputTemplate = "[{Level:u3}] {Message:lj}{NewLine}{Exception}"
    };
    
    config.File = new FileLoggerOptions
    {
        MinimumLevel = LogLevel.Information, // Общие логи
        Path = "logs/app-.log"
    };
    
    config.ErrorFile = new FileLoggerOptions
    {
        Path = "logs/errors-.log",
        MinimumLevel = LogLevel.Error,
        RollingInterval = RollingInterval.Day,
        RetainedFileCountLimit = 90
    };
    
    config.Elasticsearch = new ElasticsearchSinkOptions
    {
        MinimumLevel = LogLevel.Verbose, // Все в Elasticsearch
        Options = new ElasticsearchLoggerOptions()
            .WithApiKey("your-key")
    };
});

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

Использование в коде

using PrimaLogger;

// Через статический класс
Log.Information("User {UserId} logged in", userId);
Log.Error(exception, "Failed to process order {OrderId}", orderId);
Log.Debug("Processing started at {Timestamp}", DateTime.Now);

// Через ILogger<T> (DI)
public class UserController : ControllerBase
{
    private readonly ILogger<UserController> _logger;
    
    public UserController(ILogger<UserController> logger)
    {
        _logger = logger;
    }
    
    public IActionResult Login(string userId)
    {
        _logger.LogInformation("User {UserId} attempting login", userId);
        // ...
    }
}

Готовые Presets

// FullStack preset - консоль + файл + файл ошибок + Elasticsearch
services.AddPrimaLogger("MyApp", "http://localhost:9200", "api-key");

// Используя конфигурационные presets
services.AddPrimaLogger(config => PrimaLoggerConfig.Development("MyApp"));
services.AddPrimaLogger(config => PrimaLoggerConfig.Production("MyApp", "http://es:9200", "key"));

// Используя LoggerPresets напрямую (без DI)
var logger = LoggerPresets.Development();
var logger = LoggerPresets.WithElasticsearch("http://es:9200", "myapp");
var logger = LoggerPresets.FullStack("myapp", "http://es:9200", "api-key");

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

По времени

config.File = new FileLoggerOptions
{
    RollingInterval = RollingInterval.Hour,   // Каждый час
    RetainedFileCountLimit = 48               // Хранить 48 файлов (2 дня)
};

По размеру

config.File = new FileLoggerOptions
{
    RollingInterval = RollingInterval.Infinite,
    FileSizeLimitBytes = 50 * 1024 * 1024,    // 50MB
    RollOnFileSizeLimit = true,
    RetainedFileCountLimit = 10
};

Elasticsearch настройки

Производительность

config.Elasticsearch = new ElasticsearchSinkOptions
{
    Options = new ElasticsearchLoggerOptions
    {
        BufferOptions = new ElasticsearchBufferOptions
        {
            ConcurrentConsumers = 4,        // 4 потока отправки
            InboundBufferMaxSize = 500000,  // Буфер входящих
            OutboundBufferMaxSize = 5000    // Размер пакета отправки
        }
    }
};

Аутентификация

// API Key
.WithApiKey("your-api-key")

// Basic Auth
.WithBasicAuth("username", "password")

Готовые методы для Elasticsearch

ElasticsearchLoggerOptions

// Базовые настройки
ElasticsearchLoggerOptions.Default()

// Настройки буферизации
ElasticsearchBufferOptions.Default()
ElasticsearchBufferOptions.HighThroughput()  // 4 consumer, 500k/5k buffers
ElasticsearchBufferOptions.LowThroughput()   // 1 consumer, 10k/100 buffers

ElasticsearchSinkOptions

// Обертка с MinimumLevel
ElasticsearchSinkOptions.Default()           // Information уровень
ElasticsearchSinkOptions.Verbose(url)        // Verbose уровень

Пример использования:

config.Elasticsearch = ElasticsearchSinkOptions.Verbose("http://localhost:9200");

// Или с настройкой буферизации
config.Elasticsearch = new ElasticsearchSinkOptions
{
    MinimumLevel = LogLevel.Debug,
    Options = ElasticsearchLoggerOptions.Default()
        .WithApiKey("key")
        .WithBuffering(buf => buf = ElasticsearchBufferOptions.HighThroughput())
};