233 lines
11 KiB
C#
233 lines
11 KiB
C#
|
||
using System;
|
||
using System.Collections.Concurrent;
|
||
using System.Runtime.CompilerServices;
|
||
using System.Threading;
|
||
using NLog;
|
||
|
||
namespace PMSWPF.Helper;
|
||
|
||
/// <summary>
|
||
/// NLog 日志帮助类，提供简化的日志记录方法，并自动捕获调用者信息。
|
||
/// 新增了日志节流功能，以防止在短时间内产生大量重复的日志（日志风暴）。
|
||
/// </summary>
|
||
public static class NlogHelper
|
||
{
|
||
/// <summary>
|
||
/// 获取当前类的 NLog 日志实例。
|
||
/// </summary>
|
||
private static readonly Logger Logger = LogManager.GetCurrentClassLogger();
|
||
|
||
/// <summary>
|
||
/// 内部类，用于存储节流日志的状态信息。
|
||
/// </summary>
|
||
private class ThrottledLogInfo
|
||
{
|
||
/// <summary>
|
||
/// 日志在节流时间窗口内的调用次数。
|
||
/// 使用 int 类型，并通过 Interlocked.Increment 进行原子性递增，确保线程安全。
|
||
/// </summary>
|
||
public int Count;
|
||
|
||
/// <summary>
|
||
/// 用于在节流时间结束后执行操作的计时器。
|
||
/// </summary>
|
||
public Timer Timer;
|
||
|
||
/// <summary>
|
||
/// 调用日志方法的源文件完整路径。
|
||
/// </summary>
|
||
public string CallerFilePath;
|
||
|
||
/// <summary>
|
||
/// 调用日志方法的成员或属性名称。
|
||
/// </summary>
|
||
public string CallerMember;
|
||
|
||
/// <summary>
|
||
/// 调用日志方法的行号。
|
||
/// </summary>
|
||
public int CallerLineNumber;
|
||
|
||
/// <summary>
|
||
/// 日志级别 (e.g., Info, Error)。
|
||
/// </summary>
|
||
public LogLevel Level;
|
||
|
||
/// <summary>
|
||
/// 关联的异常对象（如果有）。
|
||
/// </summary>
|
||
public Exception Exception;
|
||
}
|
||
|
||
/// <summary>
|
||
/// 线程安全的字典，用于存储正在被节流的日志。
|
||
/// 键 (string) 是根据日志消息和调用位置生成的唯一标识。
|
||
/// 值 (ThrottledLogInfo) 是该日志的节流状态信息。
|
||
/// </summary>
|
||
private static readonly ConcurrentDictionary<string, ThrottledLogInfo> ThrottledLogs = new ConcurrentDictionary<string, ThrottledLogInfo>();
|
||
|
||
/// <summary>
|
||
/// 定义节流的时间窗口（单位：秒）。
|
||
/// </summary>
|
||
private const int ThrottleTimeSeconds = 10;
|
||
|
||
/// <summary>
|
||
/// 内部核心日志记录方法，包含了节流逻辑。
|
||
/// </summary>
|
||
/// <param name="msg">日志消息内容。</param>
|
||
/// <param name="level">NLog 的日志级别。</param>
|
||
/// <param name="exception">可选的异常对象。</param>
|
||
/// <param name="throttle">是否启用节流。</param>
|
||
/// <param name="callerFilePath">调用此方法的源文件完整路径。</param>
|
||
/// <param name="callerMember">调用此方法的成员或属性名称。</param>
|
||
/// <param name="callerLineNumber">调用此方法的行号。</param>
|
||
private static void LogInternal(string msg, LogLevel level, Exception exception, bool throttle, string callerFilePath, string callerMember, int callerLineNumber)
|
||
{
|
||
// 如果不启用节流，则直接记录日志并返回。
|
||
if (!throttle)
|
||
{
|
||
LogWithContext(msg, level, exception, callerFilePath, callerMember, callerLineNumber);
|
||
return;
|
||
}
|
||
|
||
// 使用消息内容和调用位置生成唯一键，以区分不同的日志来源。
|
||
var key = $"{callerFilePath}:{callerLineNumber}:{msg}";
|
||
|
||
// 使用 AddOrUpdate 实现原子操作，确保线程安全。
|
||
// 它会尝试添加一个新的节流日志条目，如果键已存在，则更新现有条目。
|
||
ThrottledLogs.AddOrUpdate(
|
||
key,
|
||
// --- 添加逻辑 (addValueFactory)：当日志第一次被节流时执行 ---
|
||
_ =>
|
||
{
|
||
// 1. 首次出现，立即记录一次原始日志。
|
||
LogWithContext(msg, level, exception, callerFilePath, callerMember, callerLineNumber);
|
||
|
||
// 2. 创建一个新的节流信息对象。
|
||
var newThrottledLog = new ThrottledLogInfo
|
||
{
|
||
Count = 1,
|
||
CallerFilePath = callerFilePath,
|
||
CallerMember = callerMember,
|
||
CallerLineNumber = callerLineNumber,
|
||
Level = level,
|
||
Exception = exception
|
||
};
|
||
|
||
// 3. 创建并启动一个一次性计时器。
|
||
newThrottledLog.Timer = new Timer(s =>
|
||
{
|
||
// --- 计时器回调：在指定时间（例如30秒）后触发 ---
|
||
// 尝试从字典中移除当前日志条目。
|
||
if (ThrottledLogs.TryRemove(key, out var finishedLog))
|
||
{
|
||
// 释放计时器资源。
|
||
finishedLog.Timer.Dispose();
|
||
// 如果在节流期间有后续调用（Count > 1），则记录一条摘要日志。
|
||
if (finishedLog.Count > 1)
|
||
{
|
||
var summaryMsg = $"日志 '{msg}' 在过去 {ThrottleTimeSeconds} 秒内被调用 {finishedLog.Count} 次。";
|
||
LogWithContext(summaryMsg, finishedLog.Level, finishedLog.Exception, finishedLog.CallerFilePath, finishedLog.CallerMember, finishedLog.CallerLineNumber);
|
||
}
|
||
}
|
||
}, null, ThrottleTimeSeconds * 1000, Timeout.Infinite); // 设置30秒后触发，且不重复。
|
||
|
||
return newThrottledLog;
|
||
},
|
||
// --- 更新逻辑 (updateValueFactory)：当日志在节流窗口内再次被调用时执行 ---
|
||
(_, existingLog) =>
|
||
{
|
||
// 只需将调用次数加一。使用 Interlocked.Increment 保证原子操作，避免多线程下的竞态条件。
|
||
Interlocked.Increment(ref existingLog.Count);
|
||
return existingLog;
|
||
});
|
||
}
|
||
|
||
/// <summary>
|
||
/// 将日志信息包装在 NLog 的 MappedDiagnosticsLogicalContext 中进行记录。
|
||
/// 这允许在 nlog.config 配置文件中使用 ${mdlc:item=...} 来获取调用者信息。
|
||
/// </summary>
|
||
private static void LogWithContext(string msg, LogLevel level, Exception exception, string callerFilePath, string callerMember, int callerLineNumber)
|
||
{
|
||
using (MappedDiagnosticsLogicalContext.SetScoped("CallerFilePath", callerFilePath))
|
||
using (MappedDiagnosticsLogicalContext.SetScoped("CallerLineNumber", callerLineNumber))
|
||
using (MappedDiagnosticsLogicalContext.SetScoped("CallerMember", callerMember))
|
||
{
|
||
if (exception != null)
|
||
{
|
||
Logger.Log(level, exception, msg);
|
||
}
|
||
else
|
||
{
|
||
Logger.Log(level, msg);
|
||
}
|
||
}
|
||
}
|
||
|
||
/// <summary>
|
||
/// 记录一个错误级别的日志，支持节流。
|
||
/// </summary>
|
||
/// <param name="msg">日志消息内容。</param>
|
||
/// <param name="exception">可选：要记录的异常对象。</param>
|
||
/// <param name="throttle">是否启用日志节流。如果为 true，则在30秒内对来自同一位置的相同日志消息进行节流处理。</param>
|
||
/// <param name="callerFilePath">自动捕获：调用此方法的源文件完整路径。</param>
|
||
/// <param name="callerMember">自动捕获：调用此方法的成员或属性名称。</param>
|
||
/// <param name="callerLineNumber">自动捕获：调用此方法的行号。</param>
|
||
public static void Error(string msg, Exception exception = null, bool throttle = false,
|
||
[CallerFilePath] string callerFilePath = "",
|
||
[CallerMemberName] string callerMember = "",
|
||
[CallerLineNumber] int callerLineNumber = 0)
|
||
{
|
||
LogInternal(msg, LogLevel.Error, exception, throttle, callerFilePath, callerMember, callerLineNumber);
|
||
}
|
||
|
||
/// <summary>
|
||
/// 记录一个信息级别的日志，支持节流。
|
||
/// </summary>
|
||
/// <param name="msg">日志消息内容。</param>
|
||
/// <param name="throttle">是否启用日志节流。如果为 true，则在30秒内对来自同一位置的相同日志消息进行节流处理。</param>
|
||
/// <param name="callerFilePath">自动捕获：调用此方法的源文件完整路径。</param>
|
||
/// <param name="callerMember">自动捕获：调用此方法的成员或属性名称。</param>
|
||
/// <param name="callerLineNumber">自动捕获：调用此方法的行号。</param>
|
||
public static void Info(string msg, bool throttle = false,
|
||
[CallerFilePath] string callerFilePath = "",
|
||
[CallerMemberName] string callerMember = "",
|
||
[CallerLineNumber] int callerLineNumber = 0)
|
||
{
|
||
LogInternal(msg, LogLevel.Info, null, throttle, callerFilePath, callerMember, callerLineNumber);
|
||
}
|
||
|
||
/// <summary>
|
||
/// 记录一个警告级别的日志，支持节流。
|
||
/// </summary>
|
||
/// <param name="msg">日志消息内容。</param>
|
||
/// <param name="throttle">是否启用日志节流。如果为 true，则在30秒内对来自同一位置的相同日志消息进行节流处理。</param>
|
||
/// <param name="callerFilePath">自动捕获：调用此方法的源文件完整路径。</param>
|
||
/// <param name="callerMember">自动捕获：调用此方法的成员或属性名称。</param>
|
||
/// <param name="callerLineNumber">自动捕获：调用此方法的行号。</param>
|
||
public static void Warn(string msg, bool throttle = false,
|
||
[CallerFilePath] string callerFilePath = "",
|
||
[CallerMemberName] string callerMember = "",
|
||
[CallerLineNumber] int callerLineNumber = 0)
|
||
{
|
||
LogInternal(msg, LogLevel.Warn, null, throttle, callerFilePath, callerMember, callerLineNumber);
|
||
}
|
||
|
||
/// <summary>
|
||
/// 记录一个跟踪级别的日志，支持节流。
|
||
/// </summary>
|
||
/// <param name="msg">日志消息内容。</param>
|
||
/// <param name="throttle">是否启用日志节流。如果为 true，则在30秒内对来自同一位置的相同日志消息进行节流处理。</param>
|
||
/// <param name="callerFilePath">自动捕获：调用此方法的源文件完整路径。</param>
|
||
/// <param name="callerMember">自动捕获：调用此方法的成员或属性名称。</param>
|
||
/// <param name="callerLineNumber">自动捕获：调用此方法的行号。</param>
|
||
public static void Trace(string msg, bool throttle = false,
|
||
[CallerFilePath] string callerFilePath = "",
|
||
[CallerMemberName] string callerMember = "",
|
||
[CallerLineNumber] int callerLineNumber = 0)
|
||
{
|
||
LogInternal(msg, LogLevel.Trace, null, throttle, callerFilePath, callerMember, callerLineNumber);
|
||
}
|
||
}
|