diff --git a/aspnet-core/framework/logging/LINGYUN.Abp.Logging.Serilog.Elasticsearch/README.EN.md b/aspnet-core/framework/logging/LINGYUN.Abp.Logging.Serilog.Elasticsearch/README.EN.md index 241469379..4326a7bb2 100644 --- a/aspnet-core/framework/logging/LINGYUN.Abp.Logging.Serilog.Elasticsearch/README.EN.md +++ b/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 diff --git a/aspnet-core/framework/logging/LINGYUN.Abp.Logging.Serilog.Elasticsearch/README.md b/aspnet-core/framework/logging/LINGYUN.Abp.Logging.Serilog.Elasticsearch/README.md index 13367b1c4..c2b72bd20 100644 --- a/aspnet-core/framework/logging/LINGYUN.Abp.Logging.Serilog.Elasticsearch/README.md +++ b/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 } } } -} \ No newline at end of file +} +``` + +## 基本用法 + +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. 支持异常信息的存在性查询 \ No newline at end of file diff --git a/aspnet-core/framework/logging/LINGYUN.Abp.Logging/README.EN.md b/aspnet-core/framework/logging/LINGYUN.Abp.Logging/README.EN.md new file mode 100644 index 000000000..824800b7e --- /dev/null +++ b/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 diff --git a/aspnet-core/framework/logging/LINGYUN.Abp.Logging/README.md b/aspnet-core/framework/logging/LINGYUN.Abp.Logging/README.md index 5f8b18560..8314f5605 100644 --- a/aspnet-core/framework/logging/LINGYUN.Abp.Logging/README.md +++ b/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 - 异常信息列表 diff --git a/aspnet-core/framework/logging/LINGYUN.Abp.Serilog.Enrichers.Application/README.EN.md b/aspnet-core/framework/logging/LINGYUN.Abp.Serilog.Enrichers.Application/README.EN.md new file mode 100644 index 000000000..56f11bd2b --- /dev/null +++ b/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. diff --git a/aspnet-core/framework/logging/LINGYUN.Abp.Serilog.Enrichers.Application/README.md b/aspnet-core/framework/logging/LINGYUN.Abp.Serilog.Enrichers.Application/README.md index 87c5b4e61..928eb74db 100644 --- a/aspnet-core/framework/logging/LINGYUN.Abp.Serilog.Enrichers.Application/README.md +++ b/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"]; +``` + +## 注意事项 -``` \ No newline at end of file +1. 应用程序名称一旦设置就是静态的,对应用程序的所有日志条目都相同 +2. enricher使用属性缓存来提高性能 +3. 只有在日志事件中不存在该属性时才会添加 \ No newline at end of file diff --git a/aspnet-core/framework/logging/LINGYUN.Abp.Serilog.Enrichers.UniqueId/README.EN.md b/aspnet-core/framework/logging/LINGYUN.Abp.Serilog.Enrichers.UniqueId/README.EN.md new file mode 100644 index 000000000..88695a9c8 --- /dev/null +++ b/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 diff --git a/aspnet-core/framework/logging/LINGYUN.Abp.Serilog.Enrichers.UniqueId/README.md b/aspnet-core/framework/logging/LINGYUN.Abp.Serilog.Enrichers.UniqueId/README.md new file mode 100644 index 000000000..0bac562bc --- /dev/null +++ b/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,这可能会增加一些性能开销