LazyLogNet 1.0.14

LazyLogNet

一个高性能、轻量级的 .NET 日志库，专注简洁易用与稳定性能。支持异步批量写入、结构化日志、按天轮转、同日大小分片与自动清理。

兼容性与依赖

• 目标框架：netstandard1.2
• 依赖：Newtonsoft.Json 13.0.1、System.ValueTuple 4.5.0

构建与安装

• 构建：dotnet build source/LazyLogNet.slnx -c Debug
• 引用：直接引用 source/bin/LazyLogNet.dll 或将 source/LazyLogNet 作为项目引用

快速开始

using LazyLogNet;

// 零配置直接使用（首次调用自动初始化，默认控制台输出启用，文件输出关闭）
LazyLogHelper.Info("应用启动");
LazyLogHelper.Warn("警告示例");
LazyLogHelper.Error("错误示例", new Exception("示例异常"));

// 显式初始化（常用）：启用文件输出并指定路径
LazyLogHelper.Initialize(enableConsole: true, enableFile: true, filePath: "logs/app.log", minLevel: LazyLogLevel.Debug);
LazyLogHelper.InfoStructured("用户登录", new Dictionary<string, object> { ["UserId"] = 123, ["Role"] = "Admin" });

使用方式

1) 静态辅助类 LazyLogHelper

// 自动初始化（默认配置）：首次调用即生效
LazyLogHelper.Debug("调试");
LazyLogHelper.Info("信息");
LazyLogHelper.Warn("警告");
LazyLogHelper.Error("错误", new Exception("错误详情"));
LazyLogHelper.Fatal("致命错误");

// 显式初始化（推荐在应用启动时调用一次）
LazyLogHelper.Initialize(new LazyLoggerConfiguration
{
    EnableConsole = true,
    EnableFile = true,
    FilePath = "logs/app.log",
    MinLevel = LazyLogLevel.Debug
});

// 结构化日志（模板替换 + 可选 JSON 属性输出）
LazyLogHelper.InfoStructured("订单 {id} 创建", new Dictionary<string, object> { ["id"] = 1001 });

2) 直接使用 LazyLogger 实例

var config = new LazyLoggerConfiguration
{
    EnableConsole = false,
    EnableFile = true,
    FilePath = "logs/app.log",
    MinLevel = LazyLogLevel.Debug,
    BatchSize = 64,
    FlushIntervalMs = 50
};
using var logger = new LazyLogger(config);

logger.Debug("调试");
logger.Info("信息");
logger.Warn("警告");
logger.Error("错误", new Exception("异常"));
logger.Fatal("致命");

// 结构化
logger.InfoStructured("用户 {name} 登录", new Dictionary<string, object> { ["name"] = "Alice" });

配置项（LazyLoggerConfiguration）

说明：当 EnableDailyRotation 为 true 时，日志文件命名为 name_yyyy-MM-dd.ext，同日分片命名为 name_yyyy-MM-dd_NN.ext（NN 为两位索引，从 01 开始）。

文件输出与路径策略

// 使用文件夹名（自动生成默认文件名）
LazyLogHelper.Initialize(enableConsole: false, enableFile: true, logFolderName: "my-app-logs");

// 使用完整路径（最高优先级）
LazyLogHelper.Initialize(enableConsole: true, enableFile: true, filePath: "D:/logs/app.log");

结构化日志

var props = new Dictionary<string, object> { ["UserId"] = 123, ["IP"] = "10.0.0.1" };

// 占位符替换（不会追加 JSON）
LazyLogHelper.InfoStructured("用户 {UserId} 登录", props);

// 追加 JSON 属性块
var cfg = new LazyLoggerConfiguration { EnableFile = true, FilePath = "logs/structured.log", IncludeStructuredData = true };
using var logger = new LazyLogger(cfg);
logger.InfoStructured("用户 {UserId} 登录", props);

按天轮转与同日大小分片

// 当天文件命名：app_yyyy-MM-dd.log
// 超过当日大小阈值时，生成 app_yyyy-MM-dd_01.log、_02.log ...
var cfg = new LazyLoggerConfiguration
{
    EnableFile = true,
    FilePath = "logs/app.log",
    EnableDailyRotation = true,
    RetentionDays = 30,
    DailyMaxFileSize = 100L * 1024 * 1024 // 100MB
};
LazyLogHelper.Initialize(cfg);

保留清理：写入新日文件时，自动清理早于 RetentionDays 的旧日志文件。

性能调优

• BatchSize：增大批次减少 I/O；低延迟场景可适当减小
• FlushIntervalMs：缩短可提高实时性；延长可提高吞吐
• QueueCapacity：高并发场景适当增大，避免队列满丢弃
• FileBufferSize：增大缓冲提升顺序写性能

日志级别

public enum LazyLogLevel { Debug = 0, Info = 1, Warn = 2, Error = 3, Fatal = 4 }

项目结构

source/
├── LazyLogNet/            # 核心库
│   ├── ILogger.cs
│   ├── LazyLogger.cs
│   ├── LazyLogHelper.cs
│   ├── LazyLoggerConfiguration.cs
│   ├── LazyLogLevel.cs
│   ├── LazyLogFormat.cs
│   └── LazyLogEntry.cs
└── SampleRunner/          # 示例/验证程序
    └── Program.cs

许可证

MIT License（详见 LICENSE）。

支持

如有问题或建议，请通过 Issue 反馈。