feat(docs): 添加日志模块文档

aspnet-core/framework/logging/LINGYUN.Abp.Logging.Serilog.Elasticsearch/README.EN.md

@@ -4,6 +4,15 @@
 
 Elasticsearch implementation of the ILoggingManager interface, retrieving log information from Elasticsearch.
 
+## Features
+
+* Elasticsearch-based log storage and retrieval
+* Support for various log levels (Debug, Information, Warning, Error, Critical)
+* Automatic mapping between Serilog and Microsoft.Extensions.Logging log levels
+* Rich query conditions (time range, log level, machine name, environment name, etc.)
+* Exception information storage and retrieval
+* Multi-tenancy support
+
 ## Module Dependencies
 
 ```csharp
@@ -18,19 +27,6 @@ public class YouProjectModule : AbpModule
 
 * AbpLoggingSerilogElasticsearchOptions.IndexFormat - Must match the IndexFormat in Serilog configuration, otherwise the correct index cannot be located
 
-## Features
-
-1. Log Retrieval
-   - Retrieve logs from Elasticsearch using ILoggingManager interface
-   - Support for various log levels (Debug, Information, Warning, Error, Critical)
-   - Automatic mapping between Serilog and Microsoft.Extensions.Logging log levels
-
-2. Object Mapping
-   - Automatic mapping of Serilog entities to application entities
-   - Maps SerilogException to LogException
-   - Maps SerilogField to LogField with unique ID support
-   - Maps SerilogInfo to LogInfo with proper log level conversion
-
 ## appsettings.json
 
 ```json
@@ -45,6 +41,73 @@ public class YouProjectModule : AbpModule
 }
 ```
 
+## Basic Usage
+
+1. Inject ILoggingManager interface:
+```csharp
+public class YourService
+{
+    private readonly ILoggingManager _loggingManager;
+
+    public YourService(ILoggingManager loggingManager)
+    {
+        _loggingManager = loggingManager;
+    }
+}
+```
+
+2. Query logs:
+```csharp
+// Get log list
+var logs = await _loggingManager.GetListAsync(
+    startTime: DateTime.Now.AddDays(-1),
+    maxResultCount: 10,
+    skipCount: 0,
+    level: LogLevel.Error,
+    environment: "Production",
+    application: "YourApp"
+);
+
+// Get log count
+var count = await _loggingManager.GetCountAsync(
+    startTime: DateTime.Now.AddDays(-1),
+    level: LogLevel.Error
+);
+
+// Get single log
+var log = await _loggingManager.GetAsync(id);
+```
+
+## Supported Query Conditions
+
+* Time range (startTime, endTime)
+* Log level (level)
+* Machine name (machineName)
+* Environment name (environment)
+* Application name (application)
+* Context (context)
+* Request ID (requestId)
+* Request path (requestPath)
+* Correlation ID (correlationId)
+* Process ID (processId)
+* Thread ID (threadId)
+* Has exception (hasException)
+
 ## Important Notes
 
-The IndexFormat configuration must be consistent between your Serilog settings and this module's configuration to ensure proper log retrieval. The default format is "logstash-{0:yyyy.MM.dd}".
+1. The IndexFormat configuration must be consistent between your Serilog settings and this module's configuration. The default format is "logstash-{0:yyyy.MM.dd}".
+2. Multi-tenancy support with automatic filtering based on current tenant ID.
+3. Query results support pagination and sorting.
+4. Support for fuzzy matching of request paths.
+5. Support for existence query of exception information.
+
+## Object Mapping
+
+* SerilogInfo to LogInfo
+  - Automatic mapping of timestamp and log level
+  - Proper conversion between Serilog and Microsoft.Extensions.Logging log levels
+* SerilogException to LogException
+  - Maps exception details including message, type, and stack trace
+* SerilogField to LogField
+  - Maps all log fields including machine name, environment, application name, etc.
+  - Supports unique ID generation for log entries

aspnet-core/framework/logging/LINGYUN.Abp.Logging.Serilog.Elasticsearch/README.md

@@ -4,6 +4,15 @@
 
 ILoggingManager 接口的ES实现, 从ES中检索日志信息  
 
+## 功能特性
+
+* 基于Elasticsearch的日志存储和检索
+* 支持多种日志级别（Debug、Information、Warning、Error、Critical）
+* 支持Serilog和Microsoft.Extensions.Logging日志级别的自动映射
+* 支持丰富的查询条件（时间范围、日志级别、机器名称、环境名称等）
+* 支持异常信息的存储和检索
+* 支持多租户
+
 ## 模块引用
 
 ```csharp
@@ -29,4 +38,65 @@ public class YouProjectModule : AbpModule
       }
     }
   }
-}
+}
+```
+
+## 基本用法
+
+1. 注入 ILoggingManager 接口：
+```csharp
+public class YourService
+{
+    private readonly ILoggingManager _loggingManager;
+
+    public YourService(ILoggingManager loggingManager)
+    {
+        _loggingManager = loggingManager;
+    }
+}
+```
+
+2. 查询日志：
+```csharp
+// 获取日志列表
+var logs = await _loggingManager.GetListAsync(
+    startTime: DateTime.Now.AddDays(-1),
+    maxResultCount: 10,
+    skipCount: 0,
+    level: LogLevel.Error,
+    environment: "Production",
+    application: "YourApp"
+);
+
+// 获取日志总数
+var count = await _loggingManager.GetCountAsync(
+    startTime: DateTime.Now.AddDays(-1),
+    level: LogLevel.Error
+);
+
+// 获取单条日志
+var log = await _loggingManager.GetAsync(id);
+```
+
+## 支持的查询条件
+
+* 时间范围（startTime、endTime）
+* 日志级别（level）
+* 机器名称（machineName）
+* 环境名称（environment）
+* 应用名称（application）
+* 上下文（context）
+* 请求ID（requestId）
+* 请求路径（requestPath）
+* 关联ID（correlationId）
+* 进程ID（processId）
+* 线程ID（threadId）
+* 是否包含异常（hasException）
+
+## 注意事项
+
+1. IndexFormat配置必须与Serilog配置保持一致，默认格式为"logstash-{0:yyyy.MM.dd}"
+2. 支持多租户，会自动根据当前租户ID过滤日志
+3. 查询结果支持分页和排序
+4. 支持请求路径的模糊匹配
+5. 支持异常信息的存在性查询

aspnet-core/framework/logging/LINGYUN.Abp.Logging/README.EN.md

@@ -0,0 +1,96 @@
+# LINGYUN.Abp.Logging
+
+Basic logging module
+
+Defines the ILoggingManager interface for implementing log information queries.
+
+[简体中文](./README.md)
+
+## Features
+
+* Provides unified logging query interface ILoggingManager
+* Supports various log field queries, including timestamp, log level, message, etc.
+* Supports exception information recording and querying
+* Supports rich log field information such as machine name, environment name, application name, etc.
+* Supports pagination query and count statistics
+
+## Module Reference
+
+```csharp
+[DependsOn(typeof(AbpLoggingModule))]
+public class YouProjectModule : AbpModule
+{
+  // other
+}
+```
+
+## Configuration
+
+Configure in `appsettings.json`:
+
+```json
+{
+  "Logging": {
+    "MachineName": "your-machine-name",
+    "EnvironmentName": "environment-name"
+  }
+}
+```
+
+## Basic Usage
+
+1. Inject ILoggingManager interface:
+```csharp
+public class YourService
+{
+    private readonly ILoggingManager _loggingManager;
+
+    public YourService(ILoggingManager loggingManager)
+    {
+        _loggingManager = loggingManager;
+    }
+}
+```
+
+2. Query logs:
+```csharp
+// Get log list
+var logs = await _loggingManager.GetListAsync(
+    startTime: DateTime.Now.AddDays(-1),
+    maxResultCount: 10,
+    skipCount: 0,
+    level: LogLevel.Error
+);
+
+// Get log count
+var count = await _loggingManager.GetCountAsync(
+    startTime: DateTime.Now.AddDays(-1),
+    level: LogLevel.Error
+);
+
+// Get single log
+var log = await _loggingManager.GetAsync(id);
+```
+
+## Log Field Description
+
+* TimeStamp - Log timestamp
+* Level - Log level
+* Message - Log message
+* Fields - Log field information
+  * Id - Log unique identifier
+  * MachineName - Machine name
+  * Environment - Environment name
+  * Application - Application name
+  * Context - Context
+  * ActionId - Action ID
+  * ActionName - Action name
+  * RequestId - Request ID
+  * RequestPath - Request path
+  * ConnectionId - Connection ID
+  * CorrelationId - Correlation ID
+  * ClientId - Client ID
+  * UserId - User ID
+  * ProcessId - Process ID
+  * ThreadId - Thread ID
+* Exceptions - Exception information list

aspnet-core/framework/logging/LINGYUN.Abp.Logging/README.md

@@ -4,6 +4,16 @@
 
 定义 ILoggingManager 接口, 实现日志信息查询  
 
+[English](./README.EN.md)
+
+## 功能特性
+
+* 提供统一的日志查询接口 ILoggingManager
+* 支持多种日志字段查询，包括时间戳、日志级别、消息等
+* 支持异常信息记录和查询
+* 支持丰富的日志字段信息，如机器名称、环境名称、应用名称等
+* 支持分页查询和计数统计
+
 ## 模块引用
 
 ```csharp
@@ -13,3 +23,74 @@ public class YouProjectModule : AbpModule
   // other
 }
 ```
+
+## 配置项
+
+在 `appsettings.json` 中配置：
+
+```json
+{
+  "Logging": {
+    "MachineName": "你的机器名称",
+    "EnvironmentName": "环境名称"
+  }
+}
+```
+
+## 基本用法
+
+1. 注入 ILoggingManager 接口：
+```csharp
+public class YourService
+{
+    private readonly ILoggingManager _loggingManager;
+
+    public YourService(ILoggingManager loggingManager)
+    {
+        _loggingManager = loggingManager;
+    }
+}
+```
+
+2. 查询日志：
+```csharp
+// 获取日志列表
+var logs = await _loggingManager.GetListAsync(
+    startTime: DateTime.Now.AddDays(-1),
+    maxResultCount: 10,
+    skipCount: 0,
+    level: LogLevel.Error
+);
+
+// 获取日志总数
+var count = await _loggingManager.GetCountAsync(
+    startTime: DateTime.Now.AddDays(-1),
+    level: LogLevel.Error
+);
+
+// 获取单条日志
+var log = await _loggingManager.GetAsync(id);
+```
+
+## 日志字段说明
+
+* TimeStamp - 日志时间戳
+* Level - 日志级别
+* Message - 日志消息
+* Fields - 日志字段信息
+  * Id - 日志唯一标识
+  * MachineName - 机器名称
+  * Environment - 环境名称
+  * Application - 应用名称
+  * Context - 上下文
+  * ActionId - 操作ID
+  * ActionName - 操作名称
+  * RequestId - 请求ID
+  * RequestPath - 请求路径
+  * ConnectionId - 连接ID
+  * CorrelationId - 关联ID
+  * ClientId - 客户端ID
+  * UserId - 用户ID
+  * ProcessId - 进程ID
+  * ThreadId - 线程ID
+* Exceptions - 异常信息列表

aspnet-core/framework/logging/LINGYUN.Abp.Serilog.Enrichers.Application/README.EN.md

@@ -0,0 +1,91 @@
+# LINGYUN.Abp.Serilog.Enrichers.Application
+
+[简体中文](./README.md) | English
+
+A Serilog enricher that adds application identifier to log properties.
+
+## Features
+
+* Adds application name to log events
+* Configurable application name field
+* Support for both code-based and configuration-based setup
+* Caches log event property for better performance
+* Seamless integration with Serilog
+
+## Module Dependencies
+
+```csharp
+[DependsOn(typeof(AbpSerilogEnrichersApplicationModule))]
+public class YouProjectModule : AbpModule
+{
+  public override void PreConfigureServices(ServiceConfigurationContext context)
+  {
+    AbpSerilogEnrichersConsts.ApplicationName = "demo-app";
+  }
+}
+```
+
+## Configuration Options
+
+The following are field constants that need to be explicitly changed:
+
+* AbpSerilogEnrichersConsts.ApplicationNamePropertyName - Used to customize the name of the ApplicationName field
+* AbpSerilogEnrichersConsts.ApplicationName - The name of the current application to be identified in logs
+
+## Usage
+
+### Code-based Configuration
+
+```csharp
+Log.Logger = new LoggerConfiguration()
+    .Enrich.WithApplicationName()
+    // ...other configuration...
+    .CreateLogger();
+```
+
+### JSON Configuration
+
+```json
+{
+   "Serilog": {
+    "MinimumLevel": {
+      "Default": "Information"
+    },
+    "Enrich": [ "WithApplicationName" ]
+  }
+}
+```
+
+## Implementation Details
+
+The enricher adds a property named "ApplicationName" (configurable) to each log event with the value specified in `AbpSerilogEnrichersConsts.ApplicationName`. The property is cached for better performance.
+
+## Best Practices
+
+1. Set the application name early in your application's startup:
+```csharp
+public override void PreConfigureServices(ServiceConfigurationContext context)
+{
+    AbpSerilogEnrichersConsts.ApplicationName = "your-app-name";
+}
+```
+
+2. Use a consistent naming convention for your applications to make log filtering easier.
+
+3. Consider setting the application name through configuration:
+```json
+{
+  "App": {
+    "Name": "your-app-name"
+  }
+}
+```
+```csharp
+AbpSerilogEnrichersConsts.ApplicationName = configuration["App:Name"];
+```
+
+## Notes
+
+1. The application name is static once set and will be the same for all log entries from the application.
+2. The enricher uses property caching to improve performance.
+3. The property will only be added if it doesn't already exist in the log event.

aspnet-core/framework/logging/LINGYUN.Abp.Serilog.Enrichers.Application/README.md

@@ -1,7 +1,17 @@
 # LINGYUN.Abp.Serilog.Enrichers.Application
 
+简体中文 | [English](./README.EN.md)
+
 日志属性添加应用程序标识  
 
+## 功能特性
+
+* 为日志事件添加应用程序名称
+* 支持自定义应用程序名称字段
+* 支持代码配置和JSON配置两种方式
+* 缓存日志事件属性以提高性能
+* 与Serilog无缝集成
+
 ## 模块引用
 
 ```csharp
@@ -10,32 +20,32 @@ public class YouProjectModule : AbpModule
 {
   public override void PreConfigureServices(ServiceConfigurationContext context)
   {
-	 AbpSerilogEnrichersConsts.ApplicationName = "demo-app";
+    AbpSerilogEnrichersConsts.ApplicationName = "demo-app";
   }
 }
 ```
 
 ## 配置项
 
-以下为字段常量,需要明确变更  
+以下为字段常量，需要明确变更：
 
-*  AbpSerilogEnrichersConsts.ApplicationNamePropertyName	用于自定义ApplicationName字段的名称  
-*  AbpSerilogEnrichersConsts.ApplicationName				在日志中标识当前应用的名称  
+* AbpSerilogEnrichersConsts.ApplicationNamePropertyName - 用于自定义ApplicationName字段的名称
+* AbpSerilogEnrichersConsts.ApplicationName - 在日志中标识当前应用的名称
 
-## How to Use
+## 使用方法
 
-```csharp
+### 代码配置方式
 
+```csharp
 Log.Logger = new LoggerConfiguration()
     .Enrich.WithApplicationName()
-    // ...other configuration...
+    // ...其他配置...
     .CreateLogger();
-
 ```
-**Or**
 
-```json
+### JSON配置方式
 
+```json
 {
    "Serilog": {
     "MinimumLevel": {
@@ -44,5 +54,38 @@ Log.Logger = new LoggerConfiguration()
     "Enrich": [ "WithApplicationName" ]
   }
 }
+```
+
+## 实现细节
+
+该enricher为每个日志事件添加一个名为"ApplicationName"（可配置）的属性，其值为`AbpSerilogEnrichersConsts.ApplicationName`中指定的值。为了提高性能，属性会被缓存。
+
+## 最佳实践
+
+1. 在应用程序启动时尽早设置应用程序名称：
+```csharp
+public override void PreConfigureServices(ServiceConfigurationContext context)
+{
+    AbpSerilogEnrichersConsts.ApplicationName = "your-app-name";
+}
+```
+
+2. 为应用程序使用一致的命名约定，以便于日志过滤。
+
+3. 考虑通过配置文件设置应用程序名称：
+```json
+{
+  "App": {
+    "Name": "your-app-name"
+  }
+}
+```
+```csharp
+AbpSerilogEnrichersConsts.ApplicationName = configuration["App:Name"];
+```
+
+## 注意事项
 
-```
+1. 应用程序名称一旦设置就是静态的，对应用程序的所有日志条目都相同
+2. enricher使用属性缓存来提高性能
+3. 只有在日志事件中不存在该属性时才会添加

aspnet-core/framework/logging/LINGYUN.Abp.Serilog.Enrichers.UniqueId/README.EN.md

@@ -0,0 +1,113 @@
+# LINGYUN.Abp.Serilog.Enrichers.UniqueId
+
+[简体中文](./README.md) | English
+
+A Serilog enricher that adds unique identifiers to log properties using the Snowflake algorithm.
+
+## Features
+
+* Adds unique identifier to each log event
+* Uses Snowflake algorithm for distributed unique ID generation
+* Supports custom Snowflake algorithm configuration
+* Supports both code-based and configuration-based setup
+* Seamless integration with Serilog
+
+## Module Dependencies
+
+```csharp
+[DependsOn(typeof(AbpSerilogEnrichersUniqueIdModule))]
+public class YouProjectModule : AbpModule
+{
+  // other
+}
+```
+
+## Configuration Options
+
+### Constants
+
+* AbpSerilogUniqueIdConsts.UniqueIdPropertyName - Name of the unique identifier field, defaults to "UniqueId"
+
+### Snowflake Configuration
+
+Configure Snowflake algorithm parameters through `AbpSerilogEnrichersUniqueIdOptions`:
+
+```json
+{
+  "UniqueId": {
+    "Snowflake": {
+      "WorkerId": 1,        // Worker machine ID
+      "DatacenterId": 1,    // Datacenter ID
+      "Sequence": 0,        // Sequence number
+      "BaseTime": "2020-01-01 00:00:00"  // Base time
+    }
+  }
+}
+```
+
+## Usage
+
+### Code-based Configuration
+
+```csharp
+Log.Logger = new LoggerConfiguration()
+    .Enrich.WithUniqueId()
+    // ...other configuration...
+    .CreateLogger();
+```
+
+### JSON Configuration
+
+```json
+{
+   "Serilog": {
+    "MinimumLevel": {
+      "Default": "Information"
+    },
+    "Enrich": [ "WithUniqueId" ]
+  }
+}
+```
+
+## Implementation Details
+
+This enricher uses the Snowflake algorithm to generate a unique ID for each log event. The Snowflake algorithm features:
+
+* Generates 64-bit long integer IDs
+* ID consists of timestamp, datacenter ID, worker machine ID, and sequence number
+* Ensures uniqueness in distributed environments
+* Time-based ordering
+
+## Best Practices
+
+1. Configure worker ID and datacenter ID appropriately to avoid conflicts in distributed environments:
+```json
+{
+  "UniqueId": {
+    "Snowflake": {
+      "WorkerId": 1,
+      "DatacenterId": 1
+    }
+  }
+}
+```
+
+2. Set an appropriate base time to maximize the available time range for IDs:
+```json
+{
+  "UniqueId": {
+    "Snowflake": {
+      "BaseTime": "2020-01-01 00:00:00"
+    }
+  }
+}
+```
+
+3. Use the UniqueId field for precise log event location in queries.
+
+## Notes
+
+1. IDs generated by the Snowflake algorithm are roughly increasing but not strictly monotonic
+2. Worker ID and datacenter ID must be unique within the cluster
+3. Base time cannot be modified once set, as it may cause ID duplicates
+4. Each log event generates a new unique ID, which may incur some performance overhead

aspnet-core/framework/logging/LINGYUN.Abp.Serilog.Enrichers.UniqueId/README.md

@@ -0,0 +1,113 @@
+# LINGYUN.Abp.Serilog.Enrichers.UniqueId
+
+简体中文 | [English](./README.EN.md)
+
+日志属性添加唯一标识，使用雪花算法生成唯一ID。
+
+## 功能特性
+
+* 为每个日志事件添加唯一标识
+* 基于雪花算法（Snowflake）生成分布式唯一ID
+* 支持自定义雪花算法配置
+* 支持代码配置和JSON配置两种方式
+* 与Serilog无缝集成
+
+## 模块引用
+
+```csharp
+[DependsOn(typeof(AbpSerilogEnrichersUniqueIdModule))]
+public class YouProjectModule : AbpModule
+{
+  // other
+}
+```
+
+## 配置项
+
+### 常量配置
+
+* AbpSerilogUniqueIdConsts.UniqueIdPropertyName - 唯一标识字段的名称，默认为"UniqueId"
+
+### 雪花算法配置
+
+通过 `AbpSerilogEnrichersUniqueIdOptions` 配置雪花算法参数：
+
+```json
+{
+  "UniqueId": {
+    "Snowflake": {
+      "WorkerId": 1,        // 工作机器ID
+      "DatacenterId": 1,    // 数据中心ID
+      "Sequence": 0,        // 序列号
+      "BaseTime": "2020-01-01 00:00:00"  // 基准时间
+    }
+  }
+}
+```
+
+## 使用方法
+
+### 代码配置方式
+
+```csharp
+Log.Logger = new LoggerConfiguration()
+    .Enrich.WithUniqueId()
+    // ...其他配置...
+    .CreateLogger();
+```
+
+### JSON配置方式
+
+```json
+{
+   "Serilog": {
+    "MinimumLevel": {
+      "Default": "Information"
+    },
+    "Enrich": [ "WithUniqueId" ]
+  }
+}
+```
+
+## 实现细节
+
+该enricher使用雪花算法为每个日志事件生成一个唯一的ID。雪花算法的特点是：
+
+* 生成的ID是64位的长整型
+* ID由时间戳、数据中心ID、工作机器ID和序列号组成
+* 保证在分布式环境下的唯一性
+* 基于时间戳的有序性
+
+## 最佳实践
+
+1. 合理配置工作机器ID和数据中心ID，避免在分布式环境中产生冲突：
+```json
+{
+  "UniqueId": {
+    "Snowflake": {
+      "WorkerId": 1,
+      "DatacenterId": 1
+    }
+  }
+}
+```
+
+2. 设置合适的基准时间以最大化ID的可用时间范围：
+```json
+{
+  "UniqueId": {
+    "Snowflake": {
+      "BaseTime": "2020-01-01 00:00:00"
+    }
+  }
+}
+```
+
+3. 在日志查询时可以使用UniqueId字段进行精确定位。
+
+## 注意事项
+
+1. 雪花算法生成的ID是趋势递增的，但不保证严格递增
+2. 工作机器ID和数据中心ID在集群中必须唯一
+3. 基准时间一旦设置就不能修改，否则可能导致ID重复
+4. 每个日志事件都会生成新的唯一ID，这可能会增加一些性能开销