EasyElasticLogger

🚀🚀🚀 A lightweight, easy-to-use .NET logging library specifically designed for writing structured logs to Elasticsearch. Supports multiple .NET platforms, including .NET Framework and .NET Core/.NET 5+

Features

Feature Category	Description
✅ Multi-Platform Support	Compatible with .NET Framework 4.7.2+, .NET Framework 4.8, .NET Standard 2.0, .NET Standard 2.1
✅ Structured Logging	Write logs to Elasticsearch in structured format for easy querying and analysis
✅ High Performance	Built-in log buffering mechanism with batch sending for improved performance
✅ Flexible Configuration	Supports multiple configuration methods including code configuration and JSON file configuration
✅ Rich Log Levels	Supports Debug, Info, Warn, Error, Fatal five log levels
✅ Secure Connection	Supports HTTPS and basic authentication
✅ Index Management	Supports fixed index and date-based rolling index strategies

---

Use Cases

Systems requiring centralized ELK logging for unified analysis

• Systems requiring real-time log monitoring and alerts
• Scenarios requiring log visualization and analysis with Kibana

.NET Framework-based applications

• WinForm desktop applications (.NET Framework 4.7.2/4.8)
• WPF desktop applications (.NET Framework 4.7.2/4.8)
• WebForm traditional web applications (.NET Framework 4.7.2/4.8)
• Windows Services and background task programs (.NET Framework 4.7.2/4.8)
• Console applications logging requirements (.NET Framework 4.7.2/4.8)

.NET Core/.NET 5+ based applications

• ASP.NET Core Web API applications
• .NET Core console applications
• Cross-platform applications (Windows/Linux/macOS)

Diagnostic and operational logging requirements in special development environments

• AutoCAD plugin logging (based on .NET Framework)
• Revit and other BIM software plugin development (based on .NET Framework)
• Industrial software plugin diagnostics and operational monitoring

---

Compatibility Information

Log Library Version	Compatible with Elasticsearch 8.x	Compatible with Elasticsearch 9.x	Compatible with Elasticsearch 10.x
9.x	❌ no	✅ yes	✅ yes
8.x	✅ yes	✅ yes	❌ no

---

Installation

Install via NuGet Package Manager:

Install-Package EasyElasticLogger

Or via .NET CLI:

dotnet add package EasyElasticLogger

---

🚀🚀🚀 Quick Start

1. Basic Usage

using EasyElasticLogger.ES.Logging; // Initialize during application startup (in Program.cs or Startup.cs) // Create configuration var config = new LoggerConfiguration { Enabled = true, IndexPrefix = "demo-app-log", ApplicationName = "DemoApplication", Cluster = new ClusterConfiguration { Nodes = new List<string> { "http://localhost:9200" } // Note: In actual usage, you need to provide valid Elasticsearch connection information } }; // Initialize static logger ElasticLogger.Initialize(config); // Use static methods directly anywhere you need to log // Synchronous logging ElasticLogger.Info("This is an info log"); ElasticLogger.Warn("This is a warning log"); ElasticLogger.Error("This is an error log", new Exception("Test exception")); // Asynchronous logging await ElasticLogger.InfoAsync("This is an async info log"); await ElasticLogger.ErrorAsync("This is an async error log", new Exception("Test exception"));

---

⚙⚙⚙ Configuration Methods

Configuration loading priority: Direct parameter > JSON configuration

1. Direct Parameter Configuration

var config = new LoggerConfiguration { Enabled = true, IndexPrefix = "myapp-log", IndexStrategy = IndexStrategy.DailyRolling, ApplicationName = "MyApplication", BatchSize = 100, TimeoutMs = 10000, Cluster = new ClusterConfiguration { Nodes = new List<string> { "http://localhost:9200" }, Username = "elastic", Password = "password", UseSsl = false, SkipSslVerification = false, ConnectionTimeoutMs = 5000, MaxRetries = 2 } }; ElasticLogger.Initialize(config);

2. JSON Configuration File (Supports environment-specific configuration)

// Automatically looks for logger-config.Production.json or logger-config.json ElasticLogger.InitializeFromJson("logger-config.json", "Production");

JSON Configuration File Examples

Default Configuration (logger-config.json)

{ "Enabled": true, "IndexPrefix": "myapp-log", "IndexStrategy": "DailyRolling", "ApplicationName": "MyApplication", "BatchSize": 100, "TimeoutMs": 10000, "Cluster": { "Nodes": ["http://localhost:9200"], "Username": "elastic", "Password": "password", "UseSsl": false, "SkipSslVerification": false, "ConnectionTimeoutMs": 5000, "MaxRetries": 2 } }

Production Environment Configuration (logger-config.Production.json)

{ "Enabled": true, "IndexPrefix": "myapp-log-prod", "IndexStrategy": "DailyRolling", "ApplicationName": "MyProductionApp", "BatchSize": 100, "TimeoutMs": 10000, "Cluster": { "Nodes": ["http://prod-es1:9200", "http://prod-es2:9200", "http://prod-es3:9200"], "Username": "elastic", "Password": "prod_password", "UseSsl": true, "SkipSslVerification": false, "ConnectionTimeoutMs": 10000, "MaxRetries": 3 } }

Usage Examples

// Use default JSON configuration file ElasticLogger.InitializeFromJson("logger-config.json"); // Use environment-specific JSON configuration file ElasticLogger.InitializeFromJson("logger-config.json", "Production");

3. Custom Configuration File Path

// Initialize with custom configuration file path and environment ElasticLogger.InitializeFromJson(@"C:\MyApp\config\logger-config.json", "Production");

4. ASP.NET Core Web API Environment Configuration and Usage

appsettings.json Configuration Example

{ "Logging": { "LogLevel": { "Default": "Information", "Microsoft.AspNetCore": "Warning" } }, "ElasticLogger": { "Enabled": true, "IndexPrefix": "webapi-log", "ApplicationName": "MyWebApiApp", "Cluster": { "Nodes": [ "http://localhost:9200" ], "Username": "elastic", "Password": "your_password", "UseSsl": false, "SkipSslVerification": false } }, "AllowedHosts": "*" }

Initialization and Usage in Program.cs

using EasyElasticLogger.ES.Configuration; using EasyElasticLogger.ES.Logging; var builder = WebApplication.CreateBuilder(args); // Add controller services builder.Services.AddControllers(); // Initialize ElasticLogger from configuration var elasticLoggerConfig = new LoggerConfiguration { Enabled = builder.Configuration.GetValue<bool>("ElasticLogger:Enabled"), IndexPrefix = builder.Configuration.GetValue<string>("ElasticLogger:IndexPrefix") ?? "webapi-log", ApplicationName = builder.Configuration.GetValue<string>("ElasticLogger:ApplicationName") ?? "MyWebApiApp", Cluster = new ClusterConfiguration { Nodes = builder.Configuration.GetSection("ElasticLogger:Cluster:Nodes").Get<List<string>>() ?? new List<string> { "http://localhost:9200" }, Username = builder.Configuration.GetValue<string>("ElasticLogger:Cluster:Username"), Password = builder.Configuration.GetValue<string>("ElasticLogger:Cluster:Password"), UseSsl = builder.Configuration.GetValue<bool>("ElasticLogger:Cluster:UseSsl"), SkipSslVerification = builder.Configuration.GetValue<bool>("ElasticLogger:Cluster:SkipSslVerification") } }; ElasticLogger.Initialize(elasticLoggerConfig); // Log application startup ElasticLogger.Info("Web API application starting"); var app = builder.Build(); // Configure HTTP request pipeline if (app.Environment.IsDevelopment()) { app.UseDeveloperExceptionPage(); } app.UseAuthorization(); app.MapControllers(); // Log after application startup completion app.Lifetime.ApplicationStarted.Register(() => { ElasticLogger.Info("Web API application successfully started"); }); app.Run();

---

Logging Examples

Synchronous Logging

// Debug level log ElasticLogger.Debug("Debug information", "MyClass.Method"); // Info level log ElasticLogger.Info("General information", "MyClass.Method"); // Warn level log ElasticLogger.Warn("Warning message", "MyClass.Method"); // Error level log ElasticLogger.Error("Error message", new Exception("Exception details"), "MyClass.Method"); // Fatal level log ElasticLogger.Fatal("Critical error", new Exception("Exception details"), "MyClass.Method"); // Log with additional data var userData = new { UserId = 123, UserName = "John" }; ElasticLogger.Info("User login", "UserService.Login", userData);

Asynchronous Logging

// Asynchronously log different levels await ElasticLogger.DebugAsync("Debug information", "MyClass.Method"); await ElasticLogger.InfoAsync("General information", "MyClass.Method"); await ElasticLogger.WarnAsync("Warning message", "MyClass.Method"); await ElasticLogger.ErrorAsync("Error message", new Exception("Exception details"), "MyClass.Method"); await ElasticLogger.FatalAsync("Critical error", new Exception("Exception details"), "MyClass.Method");

---

Configuration Parameters Detailed

Logger Configuration Items

Property	Type	Default Value	Description
Enabled	bool	true	Whether to enable logging functionality
IndexPrefix	string	"app-log"	Index prefix
IndexStrategy	IndexStrategy	DailyRolling	Index strategy (Fixed/DailyRolling)
FixedIndexName	string	null	Fixed index name (only used when IndexStrategy is Fixed)
ApplicationName	string	"DefaultApp"	Application name
BatchSize	int	100	Batch size for log sending
TimeoutMs	int	10000	Send timeout (milliseconds)

Cluster Configuration Items

Property	Type	Default Value	Description
Nodes	List<string>	empty	List of Elasticsearch node addresses
Username	string	null	Username (for Basic authentication)
Password	string	null	Password (for Basic authentication)
UseSsl	bool	false	Whether to enable SSL
SkipSslVerification	bool	false	Whether to skip SSL certificate verification
ConnectionTimeoutMs	int	5000	Connection timeout (milliseconds)
MaxRetries	int	2	Maximum retry attempts

IndexStrategy Index Strategies

Strategy	Description
Fixed	Fixed index, all logs written to the same index
DailyRolling	Date-based rolling index, generates a new index daily (default)

---

License

This project uses the MIT License - see the LICENSE file for details.

---