Cangming.Logs.NLog
0.1.9.1122
Prefix Reserved
dotnet add package Cangming.Logs.NLog --version 0.1.9.1122
NuGet\Install-Package Cangming.Logs.NLog -Version 0.1.9.1122
<PackageReference Include="Cangming.Logs.NLog" Version="0.1.9.1122" />
<PackageVersion Include="Cangming.Logs.NLog" Version="0.1.9.1122" />
<PackageReference Include="Cangming.Logs.NLog" />
paket add Cangming.Logs.NLog --version 0.1.9.1122
#r "nuget: Cangming.Logs.NLog, 0.1.9.1122"
#:package Cangming.Logs.NLog@0.1.9.1122
#addin nuget:?package=Cangming.Logs.NLog&version=0.1.9.1122
#tool nuget:?package=Cangming.Logs.NLog&version=0.1.9.1122
Cangming.Logs.NLog
日志领域的生产环境落地层(net8.0;net10.0),把 NLog 管线与 Cangming.Logs.Contracts 契约接通,并提供契约流生产者:LogEntryTarget、LogDirector(唯一映射点)、CompressingFileTarget(归档文件 Target)、Archive/(跨月压缩归档服务,0.3 由核心迁入,唯一使用者是 CompressingFileTarget)、TruncatingLayout(列级 UTF-8 字节截断布局)、PartitionFilter(分区位过滤)、SequenceTarget(序号首 Target)、NlogConfig(配置构建器)与 DefaultLogging(零配置默认管线)。UI 投递由宿主实现,库不提供 UI 包。本工程依赖 Cangming.Logs(间接覆盖 Contracts),是 NLog 与契约之间唯一的翻译层。
包版本由仓库根 Directory.Build.props 统一控制,项目内不覆盖。
快速接线(AI 阅读)
标准管线:归档落盘与契约流并行,同一份 NLog 事件既进文件也扇出给订阅者——
flowchart LR
A["业务 LogHub/MEL"] --> B["NLog LogEventInfo"]
B --> C["CompressingFileTarget<br/>归档 CSV + 跨月压缩"]
B --> D["LogEntryTarget(name, service 或 factory)"]
D -->|"LogDirector.Transform()"| E["LogEntry"]
E --> F["ILogService.Write"]
F --> G["订阅者:UI 集合 / 监控"]
接线代码(宿主在初始化 NLog 时执行,ILogService 实例由宿主持有;也可传延迟工厂):
var logService = new DefaultLogService();
new NlogConfig()
.AddTargets(new TargetDescriptor(LogLevel.Trace, LogLevel.Fatal, "ContractLog",
new LogEntryTarget("ContractLog", () => logService)))
.Launch(mergeWithExisting: true);
// 面板侧订阅:谓词过滤 Warning 及以上,集合与裁剪由宿主负责
logService.Subscribe(e => e.Level >= LogSeverity.Warning,
entry => myBoundCollection.Add(entry));
默认管线(DefaultLogging)
宿主不想自己拼列与 Target 时,一次调用装配零配置管线:
using Cangming.Logs.NLog;
using Microsoft.Extensions.Logging;
// 宿主自备 NLog.Extensions.Logging;工厂由宿主持有并负责释放
var factory = LoggerFactory.Create(b => b.AddNLog());
// 装配完成后 LogHub 已发布;返回值是实际使用的日志目录,可直接喂给 SupportBundle
string directory = DefaultLogging.Initialize("Mercury", factory, new LogDefaultOptions(RetainDays: 7));
Initialize 依次做五件事:解析目录(显式 Directory 优先,否则 %LocalAppData%\<application>\logs,主目录不可建时回退到临时目录下的同名路径并只写一行 Console.Error)、按 MaxTotalBytes 删除最旧的 *.csv 与 *.zip、装配序号 Target 与 CSV Target(四列 time/level/logger/message,异步写入,EnableConsole 为 true 时追加彩色控制台)、以 mergeWithExisting: false 整体替换全局 NLog 配置、最后把宿主工厂发布给 LogHub。
本工程只依赖 NLog 而不依赖桥包,因此传入的工厂必须已挂 NLog provider(宿主自备 AddNLog());目录创建与写盘失败都不向上抛,代价是目录彻底不可建时日志静默丢弃,所以调用方要把返回目录与自检快照一并记录。
DefaultLogging.Initialize、NlogConfig.BuildCsvFileTarget 与 TruncatingLayout 构造函数都标了 [RequiresUnreferencedCode]:列布局文本经 Layout.FromString 解析,裁剪后可能丢失渲染器的反射元数据,因此三者只能在装配期调用,AOT/裁剪应用按该标注自行声明。
各类型职责与边界
| 类型 | 职责 | 不做什么 |
|---|---|---|
LogEntryTarget : Target |
LogEventInfo → Transform → ILogService.Write;可直接注入服务,也可传 Func<ILogService>:首次成功求值后缓存,失败/返回 null 不冒泡并重试;写不抛出,异常入 NLog InternalLogger |
不自建队列(异步由 TargetDescriptor.NeedAsync 套 AsyncTargetWrapper);不能经 nlog.config XML 声明(构造需注入服务或工厂) |
LogDirector.Transform |
唯一映射点:级别按 NLog 序归一;Exception 仅 Warning 及以上携带;读 cangming.partition / cangming.route / cangming.seq,成功消费的 partition/route 剥离,回退键与宿主键保留;Properties 无剩余键则 null |
不猜测分区归属;不计数、不读 PartitionRegistry;不改写时间戳口径 |
CompressingFileTarget : FileTarget |
归档落盘 + 跨月压缩(经 ArchiveCompressionService),Metrics 暴露压缩指标 |
不负责契约流 |
NlogConfig |
Target 构建器与注册(AddTargets/Launch)、显式 CsvFileTargetOptions 工厂 |
不预设契约流接线(宿主自行决定是否注册 LogEntryTarget) |
PartitionFilter |
读 cangming.partition 的 ulong 与构造位做位与;命中 Log,缺失/类型错/不命中 Ignore 并计数 |
不解析分区名,不替宿主决定文件 |
SequenceTarget |
同步首 Target,写 cangming.seq;已有序号不覆盖 |
不写 session、不做 route.fallback、不写文件 |
TruncatingLayout : Layout |
按 UTF-8 字节预算截断内层布局的渲染结果:构造 TruncatingLayout(string layoutText, int maxBytes, string? marker = null) 只收布局文本,内部经 Layout.FromString 建内层;标记字节数计入预算,null 标记取 [...truncated](14 字节)、空串表示硬截断;截断按码点边界回退,静态 Truncate(string? text, int maxBytes, string? marker) 供不经过布局的调用点直接用;TruncatedCount 与 RenderFailureCount 用 Interlocked 维护 |
不接受已构造的 Layout 实例(NLog 6.2.2 的 Layout.Initialize 经内部接口实现、外部不可调,传入带初始化状态的布局会静默丢表头);渲染异常折算空串并计数,不向写日志方抛出 |
CsvFileTargetOptions / CsvColumnSpec |
CSV 的显式选项与列定义:表头、引号、分隔符、BOM、归档参数,以及列级 MaxBytes/TruncateMarker |
不内置产品列、保留期与根目录;列级预算含标记字节,非正预算或标记超预算在构建期抛异常 |
LogEntryTarget 暴露实例 Metrics 快照(名称与四项计数),静态汇总仍保留;两个回退键首次出现各写一条 InternalLogger.Warn。
CSV 选项与列级截断
四个新选项都是 init 属性而非位置参数,旧构造与旧二进制都能继续用;默认值刻意对齐改动前文件的实际输出,因此升级不会给文件多一行表头,也不会丢 BOM:
| 选项 | 默认 | 落到哪里 | 为什么是这个默认 |
|---|---|---|---|
WithHeader |
true |
CsvLayout.WithHeader |
改动前 BuildCsvFileTarget 没碰 CsvLayout 的默认值,文件本来就有表头;去掉表头必须显式 false |
Quoting |
CsvQuotingMode.Auto |
CsvLayout.Quoting |
与 NLog 默认一致:只在内容含分隔符或引号时才加引号,All 恒加、Nothing 完全不转义 |
Delimiter |
CsvColumnDelimiterMode.Auto |
CsvLayout.Delimiter |
与 NLog 默认一致;Auto 按当前区域设置选逗号或分号,跨机器部署时建议显式给 Comma/Semicolon |
WriteBom |
true |
CompressingFileTarget.WriteBom |
改动前这里是硬编码 true,默认保留 BOM 才能让升级前后的文件逐字节一致 |
Delimiter 接收 CsvColumnDelimiterMode 的全部取值,但 Custom 要靠 CsvLayout.CustomColumnDelimiter 给出分隔字符串,选项层没有暴露该值,因此本工厂能生效的只有 Auto/Comma/Semicolon/Tab/Pipe/Space 这几种固定模式。
列级截断只对配了 MaxBytes 的列生效,其余列的布局文本原样交给 CsvColumn:
| 成员 | 语义 |
|---|---|
CsvColumnSpec.MaxBytes |
列内容的 UTF-8 字节预算,null 不截断;预算包含截断标记自身,因此 maxBytes <= 0 与标记超预算都在 BuildCsvFileTarget 构建期抛异常,不等写第一条日志才暴露 |
CsvColumnSpec.TruncateMarker |
截断标记,null 取 [...truncated],空串表示硬截断;与预算的关系由 TruncatingLayout 判定,标记字节数大于预算没有合法结果 |
两类构建期异常的消息都以 列 '<name>' 开头并保留原参数名,因为一份 options 通常同时配十几列,不点名就只能二分定位:
using Cangming.Logs.NLog;
using NLog.Layouts;
var options = new CsvFileTargetOptions(
@"D:\Logs",
[
new CsvColumnSpec("time", "${date:format=yyyy-MM-dd HH\\:mm\\:ss.fff}"),
new CsvColumnSpec("level", "${level}"),
new CsvColumnSpec("logger", "${logger}") { MaxBytes = 128 },
new CsvColumnSpec("message", "${message}") { MaxBytes = 8192, TruncateMarker = "…" },
],
FileNamePattern: "app-${shortdate}.csv",
NeedAsync: true)
{
Delimiter = CsvColumnDelimiterMode.Comma,
};
var descriptor = NlogConfig.BuildCsvFileTarget("AppMain", options);
截断按 UTF-8 码点边界回退,不会切出半个汉字或半个代理对,代价是同一份配置对中文与 ASCII 的可见长度不同:MaxBytes 按字节计,需要按字符数封顶时由调用方先换算成字节预算,库不做字符维度的限制。
异步包装回调(ConfigureAsyncWrapper)
TargetDescriptor 仍是十个位置参数的记录,回调以 init 属性追加,旧构造签名与旧二进制不变;要观测异步队列的丢弃,就在回调里订阅 LogEventDropped:
using Cangming.Logs.NLog;
long dropped = 0; // 实际代码放在宿主字段或统计对象里
var csv = NlogConfig.BuildCsvFileTarget("AppMain", options); // options 见上一节,NeedAsync 为 true
new NlogConfig()
.AddTargets(csv with
{
ConfigureAsyncWrapper = wrapper =>
{
wrapper.LogEventDropped += (_, args) => Interlocked.Increment(ref dropped);
},
})
.Launch();
| 约束 | 内容 |
|---|---|
| 调用时刻 | AddTargets 先写 QueueLimit、OverflowAction、BatchSize,再调回调,最后才 AddTarget;回调读到的是描述符给出的最终值,订阅也在包装器进入配置之前完成 |
| 线程 | LogEventDropped 在写日志线程上同步触发,处理器只许做 Interlocked 一类计数,不得阻塞、不得再写日志;要落盘只能把 LogEventDroppedEventArgs.DroppedLogEventInfo 交给别的线程 |
| 触发条件 | 只在 OverflowAction 为 Discard 时触发;Block 与 Grow 下队列不丢事件,处理器永远收不到调用 |
| 异常 | 回调抛出的异常由 AddTargets 原样上抛,失败的 Target 不登记、同名描述符可重试;这是有意的配置期错误,不要吞掉 |
| 非异步 | NeedAsync=false 不创建包装器,回调不执行 |
效率语义(AI 阅读须知)
- 热路径零堆分配:
Transform产出readonly record struct LogEntry(栈复制),面板集合存储即 struct 本体,无第二次转换;Properties空时为 null,不 new 字典。 - NLog 异步:需要异步写契约流时经
TargetDescriptor.NeedAsync包裹,本层不自建队列。
同族项目
| 项目 | 角色 |
|---|---|
Cangming.Logs.Contracts |
契约(本工程是它的生产环境落地) |
Cangming.Logs |
默认实现 DefaultLogService + LogHub 门面 + 路由装饰器(本工程的 ProjectReference 上游,Archive/ 已迁到本工程) |
Cangming.Logs.xUnit |
测试环境落地(与本工程平行,互不依赖) |
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net8.0 is compatible. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. net9.0 was computed. net9.0-android was computed. net9.0-browser was computed. net9.0-ios was computed. net9.0-maccatalyst was computed. net9.0-macos was computed. net9.0-tvos was computed. net9.0-windows was computed. net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. |
-
net10.0
- Cangming.Logs (>= 0.1.9.1122)
- NLog (>= 6.2.2)
-
net8.0
- Cangming.Logs (>= 0.1.9.1122)
- NLog (>= 6.2.2)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.
| Version | Downloads | Last Updated |
|---|---|---|
| 0.1.9.1122 | 0 | 11/22/2026 |
| 0.1.8.1117 | 82 | 11/17/2026 |
| 0.1.7.1116 | 85 | 11/16/2026 |
| 0.1.6.1109 | 94 | 11/9/2026 |
| 0.1.5.1105 | 102 | 11/5/2026 |
| 0.1.4.1105 | 96 | 11/5/2026 |
| 0.1.3.1102 | 106 | 11/2/2026 |
| 0.1.2.1029 | 105 | 10/29/2026 |
| 0.1.1.1028 | 106 | 10/28/2026 |
见仓库根 CHANGELOG.md