Log Filter

Log Filter

Легковесный мод для фильтрации логов, созданный, чтобы уменьшить спам в консоли и лог-файлах, позволяя разработчикам и игрокам сосредоточиться на критических ошибках и сэкономить место на диске.

Возможности

• Фильтрация по регулярным выражениям: Поддерживает мощное сопоставление по regex для точной фильтрации определённого содержимого логов.
• Фильтрация по точному совпадению: Позволяет точно отфильтровать указанные целые строки текста.
• Фильтрация по Logger: Поддерживает фильтрацию всех логов от имени мода или класса (Logger Name).

• Фильтрация по уровню логов: Блокировка низкоуровневых логов вроде TRACE или DEBUG в один клик.

  Заблокировать логи INFO? Конечно! Так вы будете видеть только ошибки и предупреждения — удобно для отладки.

• Режим белого списка: Задайте правила исключения, чтобы важные логи (например, критические ошибки) не были случайно удалены.
• Эффективное кэширование: Встроенный механизм кэша дедупликации, чтобы избежать повторной обработки одних и тех же логов.

Установка

1. Скачайте JAR-файл мода.
2. Поместите JAR-файл в папку mods в директории установки Minecraft.
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` (Regex)

Используйте регулярные выражения для сопоставления логов, которые нужно отфильтровать.
```toml
filterRules = [
    ".*Exception.*",          # Отфильтровать все логи, содержащие "Exception"
    ".*stack trace.*",        # Отфильтровать стектрейсы
    ".*Could not pass event.*"# Отфильтровать ошибки конкретных событий
]

⚠ Частая ошибка: метасимволы regex и двойное экранирование в TOML

1. Уровень regex: ()[]{}*+?.^$|\ — метасимволы regex; экранируйте их для буквального совпадения. Например, скобки в логе some (thing) нужно записать как \(thing\) — иначе они будут восприняты как группа захвата, и правило молча никогда не сработает (сам regex при этом валиден, ошибка не показывается).
2. Уровень TOML: внутри строк в двойных кавычках TOML съедает один уровень обратных слэшей, поэтому удваивайте их: "some \\(thing\\)"; рекомендуются строки в одинарных кавычках (экранирование TOML не нужно): 'some \(thing\)'.
3. Семантика совпадения: filterRules использует частичное совпадение (find); правило срабатывает, если совпадает любая часть сообщения, так что оборачивать в .* не нужно.
4. Некорректный regex (например, несбалансированные скобки) безопасно пропускается: в лог пишется WARN, а при входе в мир появляется предупреждение в игровом чате; все остальные правила продолжают работать — краша при запуске не будет. Сначала проверяйте правила на regex101.com (Java flavor).

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/.

Глубокое погружение

Часть 1: Как это работает на уровне кода мода

Основная идея мода — перехват. Он «угоняет» данные до того, как вывод логов Minecraft дойдёт до консоли или файлов, решая, пропустить их или отбросить.

1. Основы фреймворка логирования: Log4j 2

Minecraft 1.20.1 использует фреймворк логирования Log4j 2.

• Поток логов: код игры генерирует события логов (LogEvent) -> передаёт их в LoggerContext Log4j -> передаёт в Appender (например, консольный appender, запись в файл) -> в итоге отображается на экране.
• Механизм фильтров: Log4j позволяет навешивать «фильтры (Filter)» на логгеры или appender'ы.
• Асинхронный конвейер вывода: все appender'ы на корневом логгере оборачиваются в Log4j2 AsyncAppender (включён по умолчанию, настраивается): ввод-вывод консоли/файлов выполняется в фоновом потоке, поток логирования платит только за постановку в очередь; размер очереди и политика переполнения настраиваются.

2. Поток выполнения кода

Наш мод выполняет следующие операции через LogFilterManager.java при запуске игры (FMLCommonSetupEvent):

1. Получение контекста:

   LoggerContext loggerContext = LoggerContext.getContext(false);

   Мы получили текущий контекст окружения логов Minecraft.

2. Получение конфигурации Root:

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

   Мы получили конфигурацию "Root Logger". Поскольку почти все логи в конечном итоге стекаются в Root Logger, установка фильтра здесь позволяет перехватывать глобальные логи.

3. Регистрация кастомного фильтра:

   log4jFilter = new FilteringLogFilter(); // Наш кастомный класс фильтра
   log4jFilter.start();
   rootLoggerConfig.addFilter(log4jFilter);

   Мы вставили наш кастомный FilteringLogFilter в самое начало цепочки обработки логов.

7. Перехват и принятие решений (метод FilteringLogFilter.filter): Всякий раз, когда Minecraft пытается вывести строку лога, Log4j вызывает наш метод filter(LogEvent event). Чтобы предотвратить подвисания игры из-за фильтрации логов, мы применяем дизайн "fail-fast" со следующим приоритетом логики: * Шаг A: Извлечение ключевой информации. Напрямую извлекаем ключевые данные, такие как имя Logger и уровень, из Log4j LogEvent. * Шаг B: Быстрая проверка (уровень и Logger). В первую очередь проверяем уровень лога (logLevels) и имя Logger (loggerNames). Это крайне малозатратная операция. Если совпадение найдено, лог отбрасывается немедленно, полностью пропуская дорогостоящее форматирование сообщения и последующий поиск по регуляркам, что значительно снижает нагрузку на главный поток. * Шаг C: Форматирование сообщения. Только когда лог проходит быструю проверку и не перехвачен, вызывается getFormattedMessage() для генерации текста сообщения. * Шаг D: Проверка кэша. Вычисляем хеш содержимого лога, чтобы проверить, есть ли оно в кэше. Если есть, немедленно возвращаем DENY, чтобы избежать повторных вычислений. * Шаг E: Проверка белого списка (excludePatterns). Если лог совпадает с регуляркой белого списка, возвращаем NEUTRAL. Белый список имеет наивысший приоритет и используется для защиты важных логов. * Шаг F: Проверка точного совпадения (exactMatches). Если сообщение лога точно совпадает с настроенной строкой, возвращаем DENY. * Шаг G: Проверка правил регулярных выражений (filterRules). Если сообщение лога совпадает с настроенным регулярным выражением, возвращаем DENY.

8. Финальный вердикт:

   • Если совпадает любое из вышеперечисленных условий перехвата, мы возвращаем Result.DENY. Получив DENY, Log4j немедленно отбрасывает лог, и он не появится ни в консоли, ни в файле.
   • Если ничего не совпало, мы возвращаем Result.NEUTRAL. Log4j считает, что фильтр "не имеет мнения", и продолжает передавать лог следующему обработчику, в итоге отображая его как обычно.
9. Горячая перезагрузка конфига: после того как вы отредактируете и сохраните logfilter-common.toml, наблюдатель за файлами конфигурации Forge немедленно запускает событие перезагрузки: асинхронный конвейер идемпотентно перестраивается (пропускается, если параметры не изменились), правила фильтрации перекомпилируются, невалидные регулярки пропускаются с предупреждениями — перезапуск игры не нужен, всё управляется событиями.

Часть 2: Разбор практического примера и настройка

Посмотрим на этот лог:

[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. Разбор строки лога

Нам нужно разбить этот лог на несколько ключевых частей:

2. Как определить, к какому элементу конфигурации он относится?

• Если вы хотите заблокировать все сообщения, выводимые определённым классом/модом (например, вам надоело видеть все ошибки от этого класса Shader), используйте loggerNames.
• Если вы хотите заблокировать все сообщения определённого уровня (например, не хотите видеть никакие сообщения уровня WARN), используйте logLevels.
• Если вы хотите точно заблокировать именно это одно предложение (даже если оно появляется всего один раз), используйте exactMatches.
• Если вы хотите нечётко заблокировать этот тип ошибки (например, независимо от того, не может ли он найти Sampler1 или Sampler2, или какой это Shader, просто блокировать всё, где есть "cannot find sampler"), используйте filterRules.

3. Практические варианты конфигурации

Для этой конкретной ошибки Shader у нас есть четыре стратегии фильтрации. Выбирайте по своим потребностям:

Вариант A: Точно отфильтровать эту ошибку (Рекомендуется — использовать filterRules)

Ключевая особенность этого лога — "cannot find sampler". Мы можем написать регулярное выражение, которое охватит все случаи, когда sampler не найден, не затрагивая другие логи. Подходящий сценарий: Вы считаете все предупреждения о ненайденных shader sampler неважными и хотите заблокировать их все.
Код конфигурации:

# Пояснение: .* означает любые символы, соответствует всем логам, содержащим "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"]