TJC.Cyclops.LogLib 2026.4.13.1

📝 Cyclops.LogLib

📋 项目概述

Cyclops.LogLib 是 Cyclops 框架中的日志管理专家，为您的应用程序提供高效的日志批量收集、处理和数据库持久化功能！ 🚀

我们精心设计的组件采用单例模式实现，支持两种类型日志的收集：普通系统日志（包括异常日志）和API调用日志，并提供批处理机制优化数据库写入性能。无论是监控系统运行状态，还是跟踪API调用情况，Cyclops.LogLib都能为您提供出色的支持。

✨ 为什么选择 Cyclops.LogLib？

• 高效批处理：采用批处理机制，优化数据库写入性能
• 自动收集：自动监听和收集日志，无需手动干预
• 全面覆盖：支持系统日志和API调用日志的收集
• 设备信息解析：自动从UserAgent中解析设备信息
• 可靠持久化：支持日志的数据库持久化和异常处理
• 易于集成：与Cyclops框架无缝集成

🎯 核心功能模块

1. 🔍 日志收集器

• 单例模式：LoggerCollector采用单例模式实现，集中管理日志收集和处理流程
• 自动监听：自动注册日志事件，监听Logger的日志记录和错误事件
• 服务识别：支持服务名称自动获取和配置，便于多服务环境的日志管理
• 事件驱动：基于事件驱动架构，响应日志记录事件

2. 📦 批处理机制

• 高效批处理：基于Batcher<T>实现的日志批处理器，优化数据库写入性能
• 独立队列：分别针对普通日志(LogInfo)和API日志(ApiLogInfo)提供独立的批处理队列
• 事件支持：支持批处理完成事件和错误处理事件，便于扩展和定制
• 可配置：支持批处理大小、处理间隔等参数的配置

3. 💾 数据库持久化

• ORM集成：使用BaseRepository实现日志的数据库操作
• 批量操作：支持两种日志表的批量插入，提高写入效率
• 异常处理：内置异常处理和错误重试机制，确保日志可靠持久化
• 连接管理：优化数据库连接管理，减少连接开销

4. 📱 设备信息解析

• 智能解析：自动从UserAgent中解析设备信息、操作系统和浏览器信息
• 详细信息：为API调用日志提供详细的客户端环境信息
• 用户分析：支持基于设备信息的用户行为分析
• 数据丰富：增强日志的上下文信息，便于问题定位

🛠️ 技术栈

• .NET 8.0 - 基础运行时环境，利用最新的.NET特性
• SqlSugar - 高性能ORM框架，用于数据库操作
• Cyclops.Common - 通用工具类库，提供基础功能
• Cyclops.Orm - ORM封装组件，简化数据库操作

📦 环境依赖

• .NET 8.0 SDK 或更高版本
• 数据库连接字符串：名为"LogsDB"的数据库连接配置
• 支持的数据库：SQL Server、MySQL、PostgreSQL等
• Cyclops.Common 和 Cyclops.Orm 组件
• 支持的平台：Windows、Linux、macOS

📊 数据模型

🚨 DbLogError - 异常日志表

异常日志表模型，包含以下关键字段：

• ServiceName - 服务名称，标识日志来源
• Description - 日志描述，简要说明日志内容
• Parmas - 相关参数，记录日志时的上下文信息
• Exception - 异常信息JSON字符串，包含完整的异常堆栈
• CreateTime - 创建时间，日志记录时间

🌐 DbLogApi - API调用日志表

API调用日志表模型，包含以下关键字段：

• ServiceName - 服务名称，标识API所属服务
• CallIp - 调用方IP，记录请求来源
• Url - 请求地址，完整的API路径
• RequestMethod - 请求方式，如GET、POST等
• Header - 请求头，包含HTTP请求头信息
• UserAgent - 用户代理信息，原始的UserAgent字符串
• Input - 输入参数，请求的参数信息
• Output - 输出结果，API返回的结果
• StatusCode - HTTP状态码，请求的HTTP响应状态
• UserId - 用户ID，请求的用户标识
• Cost - 请求耗时，API处理的毫秒数
• Device - 解析后的设备信息，如移动设备、桌面设备等
• Os - 操作系统信息，如Windows、iOS、Android等
• Ua - 浏览器信息，如Chrome、Safari等
• CreateTime - 创建时间，日志记录时间

🚀 安装与配置

🔍 安装方式

NuGet包管理器

Install-Package Cyclops.LogLib

.NET CLI

dotnet add package Cyclops.LogLib

PackageReference

<PackageReference Include="Cyclops.LogLib" Version="1.0.0" />

⚙️ 数据库配置

在应用程序配置文件中添加名为"LogsDB"的数据库连接字符串：

{
  "ConnectionStrings": {
    "LogsDB": "Data Source=your_server;Initial Catalog=LogsDB;User ID=your_user;Password=your_password;"
  }
}

🎯 启动配置

基本启动

在应用程序启动时初始化并启动日志收集器：

// 在应用程序启动时
var loggerCollector = LoggerCollector.Instance;
loggerCollector.Start();

自定义配置

// 自定义服务名称
var loggerCollector = LoggerCollector.Instance;
loggerCollector.ServiceName = "MyCustomService";
loggerCollector.Start();

📝 配置建议

• 数据库选择：选择性能稳定的数据库，如SQL Server或PostgreSQL
• 连接池配置：适当配置数据库连接池，提高性能
• 批处理参数：根据应用流量调整批处理大小和间隔
• 日志表索引：为日志表添加适当的索引，提高查询性能
• 定期清理：实现日志定期清理机制，避免数据库过大

📝 使用示例

1. 🎯 自动收集日志

配置完成后，通过Cyclops.Common.LogCom.Logger记录的日志会自动被收集：

// 记录普通信息日志
Logger.Info("这是一条信息日志");

// 记录警告日志
Logger.Warn("这是一条警告日志");

// 记录错误日志
try
{
    // 可能抛出异常的代码
    throw new Exception("测试异常");
}
catch (Exception ex)
{
    Logger.Error("操作失败", ex);
}

// 记录API调用日志
Logger.ApiLog(new ApiLogInfo
{
    Url = "/api/users",
    RequestMethod = "GET",
    Input = "{\"id\":1}",
    Output = "{\"success\":true,\"data\":{\"id\":1,\"name\":\"张三\"}}",
    Cost = 100, // 耗时100毫秒
    StatusCode = 200, // HTTP状态码
    CallIp = "192.168.1.1", // 调用方IP
    UserID = "user123" // 用户ID
});

2. 🔧 手动添加日志（不推荐）

如果需要手动控制日志收集，可以直接使用批处理器：

// 直接获取实例并添加日志
var logCollector = LoggerCollector.Instance;
var logInfo = new LogInfo { Description = "手动添加的日志" };

// 这种方式不推荐，建议通过Logger来记录，让收集器自动处理
// 因为手动添加可能会绕过一些内部处理逻辑

⚙️ 高级配置

1. 📦 批处理器配置

批处理器的行为（如批量大小、处理间隔等）可以在Cyclops.Common中进行配置：

// 在应用程序启动时配置批处理器
// 注意：具体配置方式可能因Cyclops.Common版本而异
// 请参考Cyclops.Common的文档获取详细配置方法

2. 🚫 启用/禁用数据库日志

通过DbConnectionOptions的EnableDBLogs属性控制是否将日志写入数据库：

// 在数据库配置中设置
_errorLogRepo.DbConnectionOptions.EnableDBLogs = true; // 默认值为true

// 禁用数据库日志（仅内存收集）
_errorLogRepo.DbConnectionOptions.EnableDBLogs = false;

3. 📈 性能优化配置

• 批处理大小：根据服务器性能和日志量调整批处理大小
• 处理间隔：设置合适的批处理间隔，平衡实时性和性能
• 连接池：优化数据库连接池配置，提高并发性能
• 索引优化：为日志表添加适当的索引，提高查询速度

⚠️ 注意事项

1. 性能考量

• 高流量应用：对于高流量应用，建议适当调整批处理器配置以优化性能
• 数据库负载：监控数据库负载，避免日志写入影响业务操作
• 内存使用：注意批处理器的内存使用，避免内存溢出

2. 可靠性

• 数据库连接：当数据库连接不可用时，组件会抛出异常并停止日志收集
• 错误处理：确保应用程序有适当的错误处理机制，避免日志收集失败影响业务逻辑
• 故障恢复：实现日志收集服务的故障恢复机制

3. 安全性

• 敏感信息：避免在日志中记录敏感信息，如密码、令牌等
• 数据脱敏：对日志中的敏感数据进行脱敏处理
• 访问控制：确保日志数据库有适当的访问控制

4. 维护

• 日志清理：定期清理过期日志，避免数据库过大
• 索引维护：定期维护日志表索引，保持查询性能
• 监控：监控日志收集服务的运行状态

🤝 贡献者

我们欢迎社区贡献！如果您有任何改进建议或功能需求，欢迎提交PR或Issue。

• yswenli：核心开发者

📋 版本信息

• 当前版本：
• 作者：yswenli
• 描述：企服版框架中日志管理组件
• 更新频率：定期更新，持续改进

📄 许可证

保留所有权利

🎉 结语

Cyclops.LogLib 致力于为您的应用程序提供高效、可靠的日志管理功能。我们相信，通过简化日志收集和处理的复杂性，您可以更专注于业务逻辑的实现，同时拥有强大的系统监控和问题定位能力。

如果您有任何问题或建议，欢迎与我们联系！让我们一起构建更好的日志管理解决方案！ 🚀