# EasyElasticLogger

**Repository Path**: lovelydouble/easy-elastic-logger

## Basic Information

- **Project Name**: EasyElasticLogger
- **Description**: 一个轻量级、易于使用的.NET日志库，专门用于将结构化日志写入Elasticsearch。支持多种.NET平台，包括.NET Framework和.NET Core/.NET 5+
- **Primary Language**: C#
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-25
- **Last Updated**: 2025-12-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 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+

<div align="center">

**Simple & Easy to Use | Feature Rich | Production Ready**

</div>

## 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:

```bash
Install-Package EasyElasticLogger
```

Or via .NET CLI:

```bash
dotnet add package EasyElasticLogger
```

---

## 🚀🚀🚀 Quick Start

### 1. Basic Usage

```csharp
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

```csharp
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)

```csharp
// 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)**
```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)**
```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**
```csharp
// 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

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

---

## Logging Examples

### Synchronous Logging

```csharp
// 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

```csharp
// 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.

---

## Configuration and Usage Examples for Different Environments

### .NET Framework/.NET Core/.NET 5+ Environment Configuration and Usage

#### 1. Initialization and Usage in Program.cs

```csharp
using EasyElasticLogger.ES.Configuration;
using EasyElasticLogger.ES.Logging;
using System;
using System.Collections.Generic;

namespace MyNetFrameworkApp
{
    class Program
    {
        static void Main(string[] args)
        {
            // Initialize logger
            InitializeLogger();
            
            // Log at different levels
            ElasticLogger.Info("Application starting", "Program.Main");
            
            try
            {
                // Simulate business logic
                DoWork();
            }
            catch (Exception ex)
            {
                ElasticLogger.Error("Unhandled exception in application", ex, "Program.Main");
            }
            
            ElasticLogger.Info("Application ending", "Program.Main");
            Console.WriteLine("Press any key to exit...");
            Console.ReadKey();
        }
        
        static void InitializeLogger()
        {
            var config = new LoggerConfiguration
            {
                Enabled = true,
                IndexPrefix = "myapp-log",
                ApplicationName = "MyNetFrameworkApp",
                Cluster = new ClusterConfiguration
                {
                    Nodes = new List<string> { "http://localhost:9200" },
                    Username = "elastic",
                    Password = "your_password"
                }
            };
            
            ElasticLogger.Initialize(config);
            Console.WriteLine("Logger initialization completed");
        }
        
        static void DoWork()
        {
            ElasticLogger.Info("Starting business logic", "Program.DoWork");
            
            // Simulate some work
            System.Threading.Thread.Sleep(1000);
            
            // Log with additional data
            var userData = new { UserId = 1001, UserName = "John", Action = "Query data" };
            ElasticLogger.Info("User performing action", "UserService.QueryData", userData);
            
            ElasticLogger.Info("Business logic completed", "Program.DoWork");
        }
    }
}
```

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

#### 1. appsettings.json Configuration Example

```json
{
  "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": "*"
}
```

#### 2. Initialization and Usage in Program.cs

```csharp
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();
```

#### 3. Logging Usage in Controller

```csharp
using Microsoft.AspNetCore.Mvc;
using EasyElasticLogger.ES.Logging;

namespace MyWebApiApp.Controllers
{
    [ApiController]
    [Route("[controller]")]
    public class UserController : ControllerBase
    {
        [HttpGet("{id}")]
        public IActionResult GetUser(int id)
        {
            try
            {
                ElasticLogger.Info($"Starting user query, User ID: {id}", "UserController.GetUser");
                
                // Simulate database query
                var user = new { Id = id, Name = "John", Email = "john@example.com" };
                
                // Log with additional data
                ElasticLogger.Info("User query successful", "UserController.GetUser", user);
                
                return Ok(user);
            }
            catch (Exception ex)
            {
                ElasticLogger.Error($"User query failed, User ID: {id}", ex, "UserController.GetUser");
                return StatusCode(500, "Internal server error");
            }
        }
        
        [HttpPost]
        public async Task<IActionResult> CreateUser([FromBody] CreateUserRequest request)
        {
            try
            {
                ElasticLogger.Info("Starting user creation", "UserController.CreateUser", request);
                
                // Simulate async database operation
                await Task.Delay(100);
                
                // Log asynchronously
                await ElasticLogger.InfoAsync("User creation successful", "UserController.CreateUser", request);
                
                return Ok(new { Message = "User created successfully" });
            }
            catch (Exception ex)
            {
                await ElasticLogger.ErrorAsync("User creation failed", ex, "UserController.CreateUser", request);
                return StatusCode(500, "Internal server error");
            }
        }
    }
    
    public class CreateUserRequest
    {
        public string Name { get; set; }
        public string Email { get; set; }
    }
}
```

<div align="center">

**Making Logging Simple Yet Powerful** ✨✨✨

</div>