Log Filter

模组

· 作者 LMaxRouterCN

一款轻量级的日志过滤模组,旨在减少控制台和日志文件中的垃圾信息,使开发者和玩家能够专注于关键错误并节省磁盘空间。

0 本站下载 0 关注 更新于 2 周前

最新 1.2.0-neoforge+1.21.11 · 1.21.11 · NeoForge

一键开服(送7天)

Log Filter

一款轻量级的日志过滤模组,旨在减少控制台和日志文件中的垃圾信息,让开发者和玩家能够专注于关键错误并节省磁盘空间。

功能特性

  • 正则表达式过滤:支持强大的正则匹配,精确筛选特定的日志内容。
  • 精确匹配过滤:可以精确过滤掉指定的整行文本。
  • 按记录器(Logger)过滤:支持过滤来自某个模组或类名(Logger Name)的所有日志。
  • 按日志级别过滤:一键屏蔽 TRACE 或 DEBUG 等低级日志。

    屏蔽 INFO 日志?当然可以!这样你只会看到错误和警告,非常适合调试。

  • 白名单模式:设置排除规则,确保重要日志(如严重错误)不会被意外删除。
  • 高效缓存:内置去重缓存机制,避免重复处理相同的日志。

安装方法

  1. 下载模组的 JAR 文件。
  2. 将 JAR 文件放入 Minecraft 安装目录下的 mods 文件夹中。
  3. 启动游戏一次。模组会自动生成默认配置文件。
  4. 根据需要修改配置文件并保存——配置支持热重载(无需重启游戏)。无效的正则表达式会被跳过并给出警告;详见下方说明。

或者手动创建 logfilter-common.toml 文件,按需修改配置,然后再启动游戏。

配置简介

配置文件位于:config/logfilter-common.toml 默认配置如下:


[General]
	#Enable or disable log filtering
	#启用或禁用日志过滤
	enableFilter = true
	#Enable debug mode to see which logs are being filtered
	#启用调试模式以查看哪些日志被过滤
	debugMode = false
	#Maximum size of filtered log cache (for duplicate detection)
	#过滤日志缓存的最大容量(用于重复检测)
	#Range: 100 ~ 10000
	maxCacheSize = 1000

[FilterRules]
	#Regex patterns to filter log messages. Matching is PARTIAL (regex find): a rule hits when it matches any part of the message, so wrapping with '.*' is unnecessary.
	#用于过滤日志消息的正则表达式。匹配方式为包含匹配(find): 规则命中消息任意片段即生效, 无需用 '.*' 包裹。
	#REGEX ESCAPING: metacharacters ()[]{}*+?.^$|\ are special; escape them to match literally, e.g. literal parentheses must be written as \( \).
	#正则转义: 元字符 ()[]{}*+?.^$|\ 有特殊含义, 按字面匹配必须转义, 例如字面圆括号必须写成 \( \)。
	#TOML ESCAPING: in double-quoted strings TOML consumes one level of backslashes, so write "some \\(thing\\)"; in single-quoted literal strings write 'some \(thing\)' directly.
	#TOML 转义: 双引号字符串中 TOML 会消耗一层反斜杠, 因此需写 "some \\(thing\\)"; 单引号字面字符串直接写 'some \(thing\)' 即可。
	#An invalid regex (e.g. unbalanced parentheses) is safely skipped with a warning (log WARN + in-game chat message); other rules keep working.
	#非法正则(如括号不闭合)会被安全跳过并告警(日志 WARN + 进入世界时聊天框提示), 其余规则照常生效。
	filterRules = []
	#Exact message strings to filter (case-sensitive)
	#精确匹配并过滤的消息字符串(区分大小写)
	exactMatches = []
	#Logger names to completely filter (e.g., 'net.minecraft.server.MinecraftServer')
	#完全过滤的 Logger 名称(例如 'net.minecraft.server.MinecraftServer')
	loggerNames = []
	#Log levels to filter: TRACE, DEBUG, INFO, WARN, ERROR, FATAL
	#要过滤的日志级别: TRACE, DEBUG, INFO, WARN, ERROR, FATAL
	logLevels = ["TRACE", "DEBUG"]
	#Regex patterns that will EXCLUDE logs from filtering (whitelist)
	#Regex/TOML escaping rules are the same as filterRules (see its comment above).
	#将日志排除在过滤之外的正则表达式(白名单)
	#正则与 TOML 的转义规则与 filterRules 相同(见其上方注释)。
	excludePatterns = []

[async]
	#Enable async log output: wraps all root appenders into a Log4j2 AsyncAppender so console/file I/O runs on a background thread instead of the logging thread
	#启用异步日志输出: 将 root logger 的全部 appender 包装进 Log4j2 AsyncAppender, 控制台/文件 I/O 转移到后台线程执行, 打日志的线程只付入队成本
	enableAsyncLogging = true
	#Capacity of the async queue (number of buffered log events)
	#异步队列容量(缓冲的日志事件数量)
	#Range: 128 ~ 65536
	asyncQueueSize = 4096
	#When queue is full: true = briefly block the logging thread (no log loss), false = drop the log event
	#队列满时: true = 短暂阻塞打日志线程(不丢日志), false = 丢弃该条日志事件
	asyncBlockingWhenFull = true
	#Milliseconds to wait for the queue to drain before discarding remaining events (on pipeline rebuild and JVM shutdown)
	#等待队列排干的毫秒数, 超时后丢弃剩余事件(在管线重建与 JVM 关闭时生效)
	#Range: 0 ~ 600000
	asyncShutdownTimeoutMs = 5000
	#Capture caller location (class/method/line). Costs a stack walk per event; Minecraft's default log pattern does not need it
	#捕获调用方位置(类/方法/行号)。每条日志付出一次栈遍历成本; Minecraft 默认日志格式用不到它, 保持 false 即可
	asyncIncludeLocation = false
	#Fully qualified class name of a org.apache.logging.log4j.core.async.BlockingQueueFactory implementation (empty = default ArrayBlockingQueue). Upgrade hook: a Disruptor-based factory can be injected later via JarJar without code changes
	#BlockingQueueFactory 实现类的全限定名(留空 = 默认 ArrayBlockingQueue)。升级钩子: 后续可通过 JarJar 注入 Disruptor 队列工厂而无需改代码
	asyncQueueFactoryClass = ""


General (常规设置)

选项 默认值 描述
enableFilter true 是否启用日志过滤功能。
debugMode false 启用调试模式,将过滤掉的日志打印到控制台,方便测试规则。
maxCacheSize 1000 已过滤日志的缓存大小,用于去重。

FilterRules (过滤规则)

1. filterRules (正则表达式)

使用正则表达式匹配需要过滤的日志。

filterRules = [
    ".*Exception.*",          # 过滤掉所有包含 "Exception" 的日志
    ".*stack trace.*",        # 过滤掉堆栈跟踪信息
    ".*Could not pass event.*"# 过滤掉特定的事件错误
]

⚠ 常见陷阱:正则元字符与双重 TOML 转义

  1. 正则层:()[]{}*+?.^$|\ 是正则元字符;若需匹配字面量,必须对其进行转义。例如日志中的 some (thing) 必须写为 \(thing\) —— 否则它们会被解析为捕获组,导致规则静默失效(正则本身是合法的,不会报错)。
  2. TOML 层:在双引号字符串中,TOML 会消耗一层反斜杠,因此需要双写:"some \\(thing\\)";推荐使用单引号字面量字符串(无需 TOML 转义):'some \(thing\)'。
  3. 匹配语义:filterRules 使用部分匹配(find);只要消息的任何部分匹配到规则,即视为命中,因此无需使用 .* 进行包裹。
  4. 无效正则(如括号不匹配)会被安全跳过:日志中会写入 WARN 警告,进入世界时会在游戏聊天栏显示警告;其他规则继续正常工作 —— 不会导致启动崩溃。建议先在 regex101.com(Java 模式)上验证规则。

2. exactMatches(精确匹配)

仅当日志内容完全相同(区分大小写)时才被过滤。

exactMatches = [
    "This message will be completely filtered out"
]

3. loggerNames(记录器名称)

基于日志来源(类名或模组包名)进行过滤。支持层级过滤。

loggerNames = [
    "net.minecraft.server.MinecraftServer",  # 过滤主服务器的日志
    "com.some.noisy.mod"                     # 过滤某个嘈杂模组的所有日志
]

4. logLevels(日志级别)

基于日志级别进行过滤。可用值:TRACE、DEBUG、INFO、WARN、ERROR、FATAL。

logLevels = [
    "TRACE",
    "DEBUG"
]

5. excludePatterns(白名单/排除规则)

非常重要。与此处规则匹配的日志将不会被过滤,即使其他规则也匹配了它们。用于保留关键错误信息。

excludePatterns = [
    ".*CRITICAL ERROR.*",  # 即使它匹配 Exception,如果是 CRITICAL ERROR,则保留
    ".*IMPORTANT.*"
]

? 构建

如果你想自己编译此模组:

./gradlew build

编译后的 JAR 文件位于 build/libs/ 目录中。


深入探究

第一部分:模组代码层面的工作原理

此模组的核心思想是拦截。它在 Minecraft 的日志输出到达控制台或文件之前“劫持”数据,决定是让通过还是丢弃。

1. 日志框架基础:Log4j 2

Minecraft 1.20.1 使用 Log4j 2 日志框架。

  • 日志流程:游戏代码生成日志事件 (LogEvent) -> 传递给 Log4j 的 LoggerContext -> 传递给 Appender(如控制台 appender、文件写入器)-> 最终显示在屏幕上。
  • 过滤机制:Log4j 允许在 Logger 或 Appender 上挂载“过滤器 (Filter)”。
  • 异步输出管道:根 logger 上的所有 appender 都被包装进 Log4j2 的 AsyncAppender(默认启用,可配置):控制台/文件 I/O 在后台线程运行,日志线程仅支付入队成本;队列大小和溢出策略均可配置。

2. 代码执行流程

我们的模组在游戏启动时(FMLCommonSetupEvent)通过 LogFilterManager.java 执行以下操作:

  1. 获取上下文:

    LoggerContext loggerContext = LoggerContext.getContext(false);
    

    我们获取了 Minecraft 当前的日志环境上下文。

  2. 获取根配置:

    Configuration configuration = loggerContext.getConfiguration();
    LoggerConfig rootLoggerConfig = configuration.getRootLogger();
    

    我们获取了“根 Logger”的配置。由于几乎所有日志最终都会流向根 Logger,在此挂载过滤器可以捕获全局日志。

  3. 注册自定义过滤器:

    log4jFilter = new FilteringLogFilter(); // 我们的自定义过滤器类
    log4jFilter.start();
    rootLoggerConfig.addFilter(log4jFilter);
    

    我们在日志处理链的最前端插入了自定义的 FilteringLogFilter。

7. 拦截与决策 (FilteringLogFilter.filter 方法): 每当 Minecraft 尝试输出一条日志行时,Log4j 都会调用我们的 filter(LogEvent event) 方法。为防止因日志过滤导致的游戏卡顿,我们采用了“快速失败”设计,逻辑优先级如下: * 步骤 A:提取关键信息。 直接从 Log4j LogEvent 中提取 Logger 名称和级别等关键细节。 * 步骤 B:快速检查(级别与 Logger)。 优先检查日志级别 (logLevels) 和 Logger 名称 (loggerNames)。这是一个极低开销的操作。如果找到匹配项,日志将被立即丢弃,完全跳过后续昂贵的消息格式化和正则匹配,显著降低主线程开销。 * 步骤 C:消息格式化。 只有当日志通过快速检查且未被拦截时,才会调用 getFormattedMessage() 来生成消息文本。 * 步骤 D:缓存检查。 计算日志内容的哈希值以检查其是否存在于缓存中。如果存在,立即返回 DENY,避免冗余计算。 * 步骤 E:白名单检查 (excludePatterns)。 如果日志匹配白名单正则,返回 NEUTRAL。白名单具有最高优先级,用于保护重要日志。 * 步骤 F:精确匹配检查 (exactMatches)。 如果日志消息与配置的字符串完全匹配,返回 DENY。 * 步骤 G:正则规则检查 (filterRules)。 如果日志消息匹配配置的正则表达式,返回 DENY。

  1. 最终结论:
    • 如果上述拦截条件中的任何一个匹配,我们返回 Result.DENY。收到 DENY 后,Log4j 会立即丢弃该日志,它不会出现在控制台或文件中。
    • 如果没有匹配项,我们返回 Result.NEUTRAL。Log4j 认为过滤器“没有意见”,并将日志继续传递给下一个处理器,最终正常显示。
  2. 配置热重载:在您编辑并保存 logfilter-common.toml 后,Forge 的配置文件监听器会立即触发重载事件:异步流水线以幂等方式重建(如果参数未更改则跳过),过滤规则重新编译,无效的正则表达式将被跳过并发出警告——无需重启游戏,所有操作均由事件驱动。

第二部分:实际案例分析与配置

让我们看看这条日志:

[241... 00:32:22.574] [Render thread/WARN] [net.minecraft.client.renderer.ShaderInstance/]: Shader rendertype_entity_translucent_emissive could not find sampler named Sampler2 in the specified shader program.

1. 日志条目拆解

我们需要将这条日志分解为几个关键部分:

日志片段 含义 对应配置项 备注
WARN 日志级别 logLevels 表示这是警告,而非错误或信息。
net.minecraft.client.renderer.ShaderInstance Logger 名称 loggerNames 发出此日志的 Java 类的全限定名。
Shader ... program. 日志消息 filterRules, exactMatches 具体的错误内容。

2. 如何确定它属于哪个配置项?

  • 如果您想阻止由特定类/模组发出的所有消息(例如,我厌倦了看到此类 Shader 的所有错误),您应该使用 loggerNames。
  • 如果您想阻止特定级别的所有消息(例如,我不想看到任何 WARN 级别的日志),您应该使用 logLevels。
  • 如果您想精确阻止这一句话(即使它只出现一次),您应该使用 exactMatches。
  • 如果您想模糊阻止这类错误(例如,无论找不到的是 Sampler1 还是 Sampler2,或者是哪个 Shader,只要它是“cannot find sampler”就阻止它),您应该使用 filterRules。

3. 实际配置解决方案

针对这个特定的 Shader 错误,我们有四种过滤策略。请根据您的需要选择:

方案 A:精确过滤此错误(推荐 - 使用 filterRules)

这条日志的核心特征是“无法找到采样器”。我们可以编写一个正则表达式,涵盖所有找不到采样器的情况,而不影响其他日志。 适用场景:您认为所有关于缺失着色器采样器的警告都是无关紧要的,并希望全部阻止它们。
配置代码:

# 解释:.* 表示任意字符,匹配所有包含 "could not find sampler named" 的日志,无论前后是什么。
	filterRules = [".*could not find sampler named.*"]
方案 B:仅阻止这条特定的长句子(使用 exactMatches)

如果您只想阻止关于找不到 Sampler2 的特定警告,但保留其他 Shader 警告。 适用场景:极其精准的打击,无附带伤害。
配置代码:

# 必须与日志中的文本完全相同(通常不包括时间戳和线程名称,仅包括冒号后的内容)
	exactMatches = ["Shader rendertype_entity_translucent_emissive could not find sampler named Sampler2 in the specified shader program."]
方案 C:阻止来自 ShaderInstance 类的所有日志(使用 loggerNames)

如果 ShaderInstance 类非常嘈杂,并且您不想看到它输出的任何内容。 适用场景:激进过滤。警告:如果此类后来输出严重的错误日志,您将看不到它们。
配置代码:

# 只要日志来源是 net.minecraft.client.renderer.ShaderInstance,就阻止一切。
	loggerNames = ["net.minecraft.client.renderer.ShaderInstance"]
方案 D:阻止所有 WARN 级别的日志(使用 logLevels)

适用场景:不推荐。这将阻止所有警告消息,可能导致您错过真正需要注意的潜在问题。
配置代码:

	logLevels = ["WARN"]

你是这个资源的作者?登录后可认领此资源。

评论 0

0.0
暂无评分
5 星
0
4 星
0
3 星
0
2 星
0
1 星
0
我的评分

登录后参与评分

还没有评论,来抢沙发吧

评论配图

相似资源